[Vorbis-dev] manpages in mdoc(7)

[Jan Stary]

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 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
> _______________________________________________
> Vorbis-dev mailing list
> Vorbis-dev at xiph.org
> http://lists.xiph.org/mailman/listinfo/vorbis-dev