help / color / mirror / Atom feed
From: Stephen Gregoratto <dev@sgregoratto.me>
To: discuss@mandoc.bsd.lv
Subject: Re: Mandoc for oil
Date: Fri, 14 Jun 2019 19:54:05 +1000	[thread overview]
Message-ID: <20190614095405.qtqxhqmu5yq6m3ib@BlackBox> (raw)
In-Reply-To: <CAAJ-tZJ=-8KHs4vOYhSZcaYA9tqLuOwUoLixHtZyekwDxjKb8w@mail.gmail.com>

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

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

  parent reply	other threads:[~2019-06-14  9:54 UTC|newest]

Thread overview: 13+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-06-14  8:16 Matthew Singletary
2019-06-14  8:43 ` Jan Stary
2019-06-14  8:54   ` Jan Stary
2019-06-14  9:24     ` Matthew Singletary
2019-06-14 11:40       ` Jan Stary
2019-06-14 12:29       ` Ingo Schwarze
2019-06-14 13:08         ` Jan Stary
2019-06-14 14:27         ` Jan Stary
2019-06-14 14:54           ` Ingo Schwarze
2019-06-16  2:39             ` Matthew Singletary
2019-06-16 17:08               ` Ingo Schwarze
2019-06-14  9:54 ` Stephen Gregoratto [this message]
2019-06-14 12:03   ` Jan Stary

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190614095405.qtqxhqmu5yq6m3ib@BlackBox \
    --to=dev@sgregoratto.me \
    --cc=discuss@mandoc.bsd.lv \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).