[Vorbis-dev] manpages in mdoc(7)

[Jan Stary]

Dear authors of Vorbis,

currently, the manpages that come with vorbistools
are written in the traditional man(7) markup language.
I am proposing to rewrite them into the semantic markup
of the mdoc(7) language. I am willing to do the work.

Both the man(7) and mdoc(7) languages have been around for decades,
and are supported by the prevalent formatters: groff(1) on most Linuxes
and mandoc(1) on the *BSDs and some others. In particular,
there is nothing to install or reconfigure on most systems
- both formats can be rendered with man(1) or processed
into html or pdf or ps.

The main point is that mdoc(7) allows for constructs like

	.Op Fl f Ar arg

meaning

	there is an optional 'f' flag
	which takes an 'arg' argument

as opposed to

	switch to italics, type a bracket, a dash, "f",
	then switch to boldface and type "arg"

in the physical roff markup of man(7).
Similarly for other constructs like cross-referenes,
filenames, author emails, env variables, etc.

See http://mdocml.bsd.lv for a thorough discussion
of the many benefits of such a markup - most important
of which is better readability and writability.

See below for a rewrite of ogginfo.1
as an example of what I have in mind.

Please let me know if you are interested.

	Jan


.Dd November 15, 2017
.Dt OGGINFO 1
.Os
.Sh NAME
.Nm ogginfo
.Nd information about Ogg files and extensive validity checking
.Sh SYNOPSIS
.Nm
.Op Fl h
.Op Fl q
.Op Fl v
.Ar
.Sh DESCRIPTION
.Nm
reads one or more Ogg files and prints information about stream contents
(including chained and/or multiplexed streams) to standard output.
It will detect (but not correct) a wide range of common defects,
with many additional checks specifically for Ogg Vorbis streams.
.Pp
For all stream types,
.Nm
will print the filename being processed, the stream serial numbers,
and various common error conditions.
.Pp
For Vorbis streams, information including the version used for encoding,
the sample rate and number of channels, the bitrate and playback length,
and the contents of the comment header are printed.
.Pp
Similarly, for Theora streams, basic information about the video is provided,
including frame rate, aspect ratio, bitrate, length, and the comment header.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl h
Show a help and usage message.
.It Fl q
Quiet mode.
This may be specified multiple times.
Doing so once will remove the detailed informative messages,
twice will remove warnings as well.
.It Fl v
Verbose mode.
At the current time, this does not do anything.
.El
.Sh SEE ALSO
.Xr ogg123 1 ,
.Xr oggdec 1 ,
.Xr oggenc 1 ,
.Xr vorbiscomment 1
.Sh AUTHORS
.An Michael Smith Aq Mt msmith at xiph.org