Dear authors of Opus, currently, the manpages that come with opus-tools 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 plaintext, html, pdf, or ps (or even into markdown, with mandoc(1)). 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 opusrtp.1 and opusinfo.1 as an example of what I have in mind. Please let me know if you are interested. (PS: Should I rather prepare a github pull request?) Jan .Dd January 29, 2018 .Dt OPUSRTP 1 .Os .Sh NAME .Nm opusrtp .Nd Opus audio in RTP .Sh SYNOPSIS .Nm .Op Fl hV .Op Fl -sniff .Ar file.opus .Op Ar ... .Sh DESCRIPTION .Nm sends and receives Opus audio data in RTP, used for interactive applications on the internet. By default, Opus audio from each given file is sent as an RTP stream. .Pp The options are as follows: .Pp .Bl -tag -compact -width versionxxxxx .It Fl h Fl -help Print a help message and exit. .It Fl V Fl -version Display version information and exit. .It Fl -quiet Suppresses program output. .It Fl -sniff Sniff the network for active RTP sessions and save them to Opus files. This can be useful for debugging other Opus RTP implementations. For this function to work, the program must be run with superuser privileges. .El .Sh SEE ALSO .Xr opusdec 1 , .Xr opusenc 1 , .Xr opusinfo 1 .Sh AUTHORS .An Ralph Giles Aq Mt giles at thaumas.net .Sh BUGS Only the sniff mode is implemented; the tool should do normal unicast and multicast send/receive. The sniff mode should allow specifying the device, host, port and payload type to limit capture; all that is hard-coded. .Dd January 29, 2018 .Dt OPUSINFO 1 .Os .Sh NAME .Nm opusinfo .Nd information about Opus files and extensive validity checking .Sh SYNOPSIS .Nm .Op Fl hqvV .Ar file.opus .Op Ar ... .Sh DESCRIPTION .Nm reads one or more Opus 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 Opus streams. .Pp For all stream types, .Nm will print the filename being processed, the stream serial numbers, and various common error conditions. For Opus streams, information including the version used for encoding, number of channels and other header information, the bitrate and playback length, the contents of the comment header, and general statistics about the stream are printed. .Pp There are many kinds of errored, invalid, non-normative, or otherwise unwise stream constructions which .Nm will not produce warnings on. Passing .Nm with flying colors is not certification of the correctness of a stream. Future versions may detect more error conditions. .Pp The options are as follows: .Pp .Bl -tag -compact -width Ds .It Fl h Show a help message and exit. .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. .It Fl V Show version info and exit. .El .Sh SEE ALSO .Xr opusdec 1 , .Xr opusenc 1 .Sh AUTHORS .An Michael Smith Aq Mt msmith at xiph.org .An Gregory Maxwell Aq Mt greg at xiph.org
ping On Jan 29 15:41:57, hans at stare.cz wrote:> Dear authors of Opus, > > currently, the manpages that come with opus-tools > 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 plaintext, html, pdf, or ps > (or even into markdown, with mandoc(1)). > > 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 opusrtp.1 and opusinfo.1 > as an example of what I have in mind. > > Please let me know if you are interested. > (PS: Should I rather prepare a github pull request?) > > Jan > > > > .Dd January 29, 2018 > .Dt OPUSRTP 1 > .Os > .Sh NAME > .Nm opusrtp > .Nd Opus audio in RTP > .Sh SYNOPSIS > .Nm > .Op Fl hV > .Op Fl -sniff > .Ar file.opus > .Op Ar ... > .Sh DESCRIPTION > .Nm > sends and receives Opus audio data in RTP, > used for interactive applications on the internet. > By default, Opus audio from each given file is sent as an RTP stream. > .Pp > The options are as follows: > .Pp > .Bl -tag -compact -width versionxxxxx > .It Fl h Fl -help > Print a help message and exit. > .It Fl V Fl -version > Display version information and exit. > .It Fl -quiet > Suppresses program output. > .It Fl -sniff > Sniff the network for active RTP sessions and save them to Opus files. > This can be useful for debugging other Opus RTP implementations. > For this function to work, the program must be run with superuser privileges. > .El > .Sh SEE ALSO > .Xr opusdec 1 , > .Xr opusenc 1 , > .Xr opusinfo 1 > .Sh AUTHORS > .An Ralph Giles Aq Mt giles at thaumas.net > .Sh BUGS > Only the sniff mode is implemented; > the tool should do normal unicast and multicast send/receive. > The sniff mode should allow specifying the device, host, port > and payload type to limit capture; all that is hard-coded. > > > > .Dd January 29, 2018 > .Dt OPUSINFO 1 > .Os > .Sh NAME > .Nm opusinfo > .Nd information about Opus files and extensive validity checking > .Sh SYNOPSIS > .Nm > .Op Fl hqvV > .Ar file.opus > .Op Ar ... > .Sh DESCRIPTION > .Nm > reads one or more Opus 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 Opus streams. > .Pp > For all stream types, > .Nm > will print the filename being processed, the stream serial numbers, > and various common error conditions. > For Opus streams, information including the version used for encoding, > number of channels and other header information, the bitrate > and playback length, the contents of the comment header, > and general statistics about the stream are printed. > .Pp > There are many kinds of errored, invalid, non-normative, > or otherwise unwise stream constructions which > .Nm > will not produce warnings on. > Passing > .Nm > with flying colors is not certification of the correctness of a stream. > Future versions may detect more error conditions. > .Pp > The options are as follows: > .Pp > .Bl -tag -compact -width Ds > .It Fl h > Show a help message and exit. > .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. > .It Fl V > Show version info and exit. > .El > .Sh SEE ALSO > .Xr opusdec 1 , > .Xr opusenc 1 > .Sh AUTHORS > .An Michael Smith Aq Mt msmith at xiph.org > .An Gregory Maxwell Aq Mt greg at xiph.org > _______________________________________________ > opus mailing list > opus at xiph.org > http://lists.xiph.org/mailman/listinfo/opus
This sounds good to me, though I'm not active in the project right now. On Mon, Jan 29, 2018 at 2:41 PM, Jan Stary <hans at stare.cz> wrote:> Dear authors of Opus, > > currently, the manpages that come with opus-tools > 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 plaintext, html, pdf, or ps > (or even into markdown, with mandoc(1)). > > 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 opusrtp.1 and opusinfo.1 > as an example of what I have in mind. > > Please let me know if you are interested. > (PS: Should I rather prepare a github pull request?) > > Jan > > > > .Dd January 29, 2018 > .Dt OPUSRTP 1 > .Os > .Sh NAME > .Nm opusrtp > .Nd Opus audio in RTP > .Sh SYNOPSIS > .Nm > .Op Fl hV > .Op Fl -sniff > .Ar file.opus > .Op Ar ... > .Sh DESCRIPTION > .Nm > sends and receives Opus audio data in RTP, > used for interactive applications on the internet. > By default, Opus audio from each given file is sent as an RTP stream. > .Pp > The options are as follows: > .Pp > .Bl -tag -compact -width versionxxxxx > .It Fl h Fl -help > Print a help message and exit. > .It Fl V Fl -version > Display version information and exit. > .It Fl -quiet > Suppresses program output. > .It Fl -sniff > Sniff the network for active RTP sessions and save them to Opus files. > This can be useful for debugging other Opus RTP implementations. > For this function to work, the program must be run with superuser privileges. > .El > .Sh SEE ALSO > .Xr opusdec 1 , > .Xr opusenc 1 , > .Xr opusinfo 1 > .Sh AUTHORS > .An Ralph Giles Aq Mt giles at thaumas.net > .Sh BUGS > Only the sniff mode is implemented; > the tool should do normal unicast and multicast send/receive. > The sniff mode should allow specifying the device, host, port > and payload type to limit capture; all that is hard-coded. > > > > .Dd January 29, 2018 > .Dt OPUSINFO 1 > .Os > .Sh NAME > .Nm opusinfo > .Nd information about Opus files and extensive validity checking > .Sh SYNOPSIS > .Nm > .Op Fl hqvV > .Ar file.opus > .Op Ar ... > .Sh DESCRIPTION > .Nm > reads one or more Opus 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 Opus streams. > .Pp > For all stream types, > .Nm > will print the filename being processed, the stream serial numbers, > and various common error conditions. > For Opus streams, information including the version used for encoding, > number of channels and other header information, the bitrate > and playback length, the contents of the comment header, > and general statistics about the stream are printed. > .Pp > There are many kinds of errored, invalid, non-normative, > or otherwise unwise stream constructions which > .Nm > will not produce warnings on. > Passing > .Nm > with flying colors is not certification of the correctness of a stream. > Future versions may detect more error conditions. > .Pp > The options are as follows: > .Pp > .Bl -tag -compact -width Ds > .It Fl h > Show a help message and exit. > .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. > .It Fl V > Show version info and exit. > .El > .Sh SEE ALSO > .Xr opusdec 1 , > .Xr opusenc 1 > .Sh AUTHORS > .An Michael Smith Aq Mt msmith at xiph.org > .An Gregory Maxwell Aq Mt greg at xiph.org