[opus] opus manpages

[Jan Stary]

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