[opus] opus manpages

[Gregory Maxwell]

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