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 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
Is there simply no interest in this? Jan On Nov 15 09:06:18, hans at stare.cz wrote:> 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 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 > _______________________________________________ > Vorbis-dev mailing list > Vorbis-dev at xiph.org > lists.xiph.org/mailman/listinfo/vorbis-dev