Re: Summary of man-page formatting

[Robert Elz <kre%munnari.OZ.AU@localhost>]

    Date:        Sun, 15 Nov 2020 03:10:08 +0100
    From:        Kamil Rytarowski <kamil%netbsd.org@localhost>
    Message-ID:  <12f29556-2407-2f6f-de5c-67539bca6d66%netbsd.org@localhost>

  | 1. NetBSD base ships with two programs that can format manual pages from
  | base and most 3rd party software: BSD mandoc (newest) and GPLv2 groff
  | 1.19.2 (old, from 2005).

When discussing this, remember that there are more than manual pages
that need to be formatted - Martin mentioned the release docs, but there's
also (the sources for) /usr/share/doc (and while that is kind of sparsely
populated, we should be trying to fill in everything that we can that's
missing from the CSRG distributions, whether they're still highly useful
or not (they provide historic data on how we got to where we are now)
and also add anything else that might be useful.

mandoc isn't useful for any of that, and nor should it be, that's not
its purpose.

  | 3. There is no groff on the list above of not renderable pages, as the
  | newest version of groff gplv3 improved the manual page in terms of
  | end-user content and formatting, making it fully compatible with
  | mandoc(1) and more valuable to users.

And simultaneously made the licence much worse.   We should be avoiding
GPLv3 whenever there is any half way reasonable alternative.

  | 5. mandoc(1) is not a *roff generic purpose formatter, but only and
  | intentionally a replacement for "*roff -mandoc". This means that it
  | targets mostly manual-pages and not generic documents and avoids
  | features that are potentially insecure

Yes, that's known, and isn't surprising, I'm not sure what the point
of this is.

  | 6. Does it mean that mandoc(1) is not sufficient as a generic purpose
  | and universal formatter of the manual pages? What other BSDs do?
  |
  | FreeBSD tries to detect in runtime whether a manual page is unsupported
  | and fallbacks to groff.

That sounds difficult and error prone.

  | OpenBSD started to convert all OpenBSD ports manual pages, one by one
  | and preformat with groff the teeny number of leftover ones.

That sounds reasonable, until you realise that it will be a never
ending project, as those external projects keep updating their man
pages, which means they need converting over and over again, unless
we never plan on doing an upgrade.

  | 10. I've suggested a MANWIDTH patch, which looked fine for upstream, but
  | it is not guaranteed to land upstream at all or in that form.
  |
  | http://netbsd.org/~kamil/patch-00287-mandoc-MANWIDTH.txt

I have no problem adding a feature to mandoc in advance of perhaps something
similar appearing in a later release - when that happens (if that happens)
then either the local patch simply vanishes, if upstream's method is
adequate, or if not, then we adapt the local patch to complete it.

  | 11. For some reason we have got a rule for .me files in man.conf(5).

That is odd.   As I remember (may be wildly wrong here) -me started as
Eric Allman's thesis macros, and was then used for most CSRG generated
documentation - but not for man pages, for which it isn't really suited
(though of course, with a general purpose formatter, and a general use
macro package, almost any output form can be produced, so I would guess
that it would be possible using -me (or -mm or -ms) to produce something
that looks just like a manual page.   But given that -man (and later -mdoc)
exist, that would seem like a strange thing to do.

  | This format seems to be very rare and unless I am
  | wrong, nothing installs it into man/ dirs.

Not all that rare (except for man pages), but I expect you're right, it
isn't likely in any man page (if there were to have been one ever, I would
have guessed that it would have been for sendmail, since that's also an
Allman product, but the sendmail man page is -man so even that one doesn't
use -me ... the generic sendmail doc however probably does, but that isn't
a man page).

  | 12. I recall recurring discussions about phasing out gplv2 groff from
  | the base and introduction of something else.
  |
  | I can see the following options:
  |
  |  - do nothing, keep shipping gnu gplv2 groff

That's certainly reasonable, given that it seems to work OK.

  |  - upgrade to gplv3 groff

That isn't, unless it gives us something that we really need that
isn't available elsewhere.

  |  - defer general purpose formatting to software from pkgsrc

That breaks /usr/share/doc so isn't reasonable either.

  |  - switch to https://github.com/aligrudi/neatroff
  |  - switch to https://n-t-roff.github.io/heirloom/doctools.html

I don't know how full featured either of those is, nor how many
groffism's have crept into other docs.

  |  - switch to something else (anything else?)

Thierry, TeX is not an alternative.   As a general purpose doc
tool it is fine, and it doesn't take much arguing to convince people
that it produces better results than anything *roff can ever do,
but it doesn't format existing *roff docs.

Whether some version of that (KerTeX or another) should be in base
is an entirely unrelated discussion.

  | 13. Then, there is still gnu gplv2 info(1) in src/, that rots quicker
  | than gnu groff gplv2.

I'd be happy to see that one go, but unfortunately there is too much
doc that uses that to simply remove it (but this seems completely
unrelated to anything previously in this message).

  | 14. We still deliver vgrind(1) and some similar macros that use groff
  | internally.

Ugh.   That ugly csh script.   Decades ago I wrote a sh version that
worked better, and was only half the size (but that is lost most likely).
This is truly ancient, and I doubt that the vgrind macros have been
touched since before groff existed, so this should work with any *roff
compatible formatter.

But after all this, I'm not sure exactly what was the point of your
message - it summarises the state of man page formatting, but doesn't
actually claim that there's any real problem, nor does it suggest that
there's any real need to do anything - other than to perhaps add local
support for MANWIDTH to mandoc.

kre