Re: Mandoc for oil

[Stephen Gregoratto <dev@sgregoratto.me>]

On 2019-06-14 04:16, Matthew Singletary wrote:
> After seeing mandoc mentioned in the past, I thought I would look into
> writing a man page for the Oil shell (http://www.oilshell.org/). I've
> never written a man page before but thought I'd try to use some decent
> tools to start with.

I'd be interested in helping you out with that. There is some prior art
in this area that you can draw on, namely sh(1)[1], ksh(1)[2] and
csh(1)[3]. Given that Oil is a subset of bash, I'm sure you could use of
of these as a basis and expand where needed.
 
> I'm a little confused about distribution/workflow for distributing man
> pages (in general). If osh.1 is an mdoc flavored file, would that be
> used (with mandoc -T man) to output a man page that could then be
> setup when Osh is installed? Then how do you distinguish those? Oil
> uses autoconf for some things, would that get tied into
> generating/installing the man pages on the manpath?

Jan's reply has all the details you need for the above. But lets suppose
you wanted to install manpages in the right format.  One solution would
be to convert the mdoc(7) sources to man(7) - using mandoc -Tman foo.1 -
when creating a release tarball. Then, in your configure script you can
check if there is a manpage formatter available that can read mdoc.
If true, install the mdoc sources, else install the man sources.

This is what openssh-portable does with their manpages in their
configure script[4] and Makefile[5]. In your case, you would probably
just check for mandoc "$(command -v mandoc)" or if {g,n}roff -mdoc
doesn't throw an error.

Honestly though, mdoc support is pretty widespread. mandoc and groff are
the two major manpage formatters used in modern systems today, and both
fully support rendering mdoc documents.  I'm not sure when groff did,
but I imagine it was at least a decade ago. Thus you could probably get
away with just shipping mdoc documents.

> Sorry if these are dumb questions, but I'm not even sure what kind of
> documentation I need to look through yet.

A manpage is just the application of technical writing within a
template. An mdoc manpage is the same, except that the template is
different and the text is structured semantically.

The best resources are the mdoc(7) manpage (my goto) and the mdoc
tutorial[7] listed at the end of that page (highly recommended).  mandoc
also comes with a linter (mandoc -Tlint foo.1) that checks semantics and
structure, which I use all the time when writing.  There's another mdoc
linter called igor[8] that adds another level of proofreading. If you
use Arch Linux, I've packaged it for the AUR. Ingo has done the same for
OpenBSD.

Finally, don't be afraid to ask here. We don't bite ;).
 
[1] https://man.openbsd.org/sh.1
[2] https://man.openbsd.org/ksh.1
[3] https://man.openbsd.org/csh.1
[4] https://github.com/openssh/openssh-portable/blob/master/configure.ac
[5] https://github.com/openssh/openssh-portable/blob/master/Makefile.in#L209
[6] https://man.openbsd.org/mdoc.7
[7] http://mandoc.bsd.lv/mdoc/
[8] http://docscripts.glenbarber.us/tags/igor
-- 
Stephen Gregoratto
PGP: 3FC6 3D0E 2801 C348 1C44 2D34 A80C 0F8E 8BAB EC8B
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv