Re: man(7), hyphen, and minus

[Ingo Schwarze]

Hi,

Russ Allbery wrote on Sat, Dec 24, 2022 at 02:43:44PM -0800:
> "G. Branden Robinson" <g.branden.robinson@gmail.com> writes:
>> At 2022-12-23T12:49:15-0800, Russ Allbery wrote:

>>> I've been curious: how much use do you see of groff outside
>>> of man pages?

I use it for the slides of all my conference presentations,
and it happened more than once to me that other speakers
approached me at conferences saying, "by the way, thanks for
documenting in the source code of your slides to the *foobar*
conference how to make slides with groff.  I tried it and it
works great for me."

All the same, i admit relatively few speakers do that.

[...]
> for instance, I still use Usenet).

Even though i have to admit that i stopped using Usenet long ago,
probably more than 20 years ago, i'd still like to thank you for
the work you did on Usenet.  I had a lot of fun with it during
the mid-90ies.

[...]
>> Heirloom Doctools is a descendant of AT&T troff; among other things, it
>> provides its own man(7) implementation, a lineal descendant of Doug
>> McIlroy's 1979 original.  It _can_ and _does_ render man pages.  Whether
>> any *nix distribution ("platform"?) ships Heirloom as its sole or
>> preferred *roff, I don't know.  I wouldn't be surprised if at least one
>> BSD does, for the usual reasons of GPL antipathy[2].
>> [2] The CDDL is way _more_ free than the GNU GPL, you see, because it is
>>     a copyleft _and_ has a choice-of-law clause, and someday the BSDs
>>     will have an island microstate nullifying all copyleft licenses.

I would be very surprised if there were any BSD system using Heirloom
roff "as its sole or preferred *roff", for two reasons:

 1. The UC Berkeley Computer Systems Research Group gradually switched
    from Kernighan's device independent troff to GNU troff as the
    preferred *roff around 4.4BSD times, supporting both in parallel
    for some time.  The switch was completed by removing the non-free
    AT&T code from 4.4BSD-Lite.  Consequently, all BSDs after the CSRG
    originally used groff as their preferred *roff.  If any would now
    use Heirloom, that would have required switching from groff to
    Heirloom at a time later than 4.4BSD-Lite2, which i would regard
    as very astonishing.

 2. The list of existing BSD systems is a few orders of magnitude shorter
    than the list of existing Linux distributions.  Basically, here
    is a complete list, chronologically by project start:

     - NetBSD: provides groff (1.19.2) and mandoc, prefers mandoc for man(1)
     - FreeBSD: provides mandoc only in base,
                at least groff and Heirloom in ports
     - OpenBSD: provides mandoc only in base,
                groff and Heirloom and Plan9 as ports
     - DragonFly: provides mandoc only in base,
                  at least groff and Heirloom in ports
     - various FreeBSD derivatives; these frequently sync with FreeBSD
       and generally follow FreeBSD in most respects.  I would be quite
       surprised if any of them made major decisions regarding manual
       pages and/or typesetting software.

    That's it, basically.  Yes, there may be a few obscure one-man
    thingies, but calling any of those a "BSD project" would be a bit
    of a stretch.  For example, http://www.mirbsd.org/ starts with:
     "MirBSD is mirabilos' Open Source playground."
    So it doesn't even claim to be an operating system project, and
    i'm not going to try and do research on projects of that size.

So i'm convinced *BSD is firmly in the "groff and mandoc" camp as
far as "preferred" goes - of course you can use Heirloom on any *BSD,
and there may be good reasons to, occasionally - but certainly not
for manual pages, that would be a really dumb idea.

The license question isn't really relevant here, not even in OpenBSD.
Even OpenBSD kept GPLv2 groff in base as long as it was needed there -
even though OpenBSD is probably the most strict among the BSD projects
when it comes to rejecting non-free licenses like GPL and CDDL.
Hell, OpenBSD even includes CLANG even though it is non-free software
(under Apache 2 license - not quite as horrific as any version of the
GPL or CDDL, but still bad enough).  When there is no choice,
compromises need to be made, unfortunately.

> I am sad that currently Pod::Man is one of the impediments to good
> rendering of manual pages in other formats, since I make use of more of
> the *roff language (mostly to work around bugs) than those tools often
> understand.

Actually, pod2man(1) is by far the best man(7) code generator i have
seen so far.  Getting it supported was among the first things i did
in mandoc, about ten years ago, and it was not terribly difficult.

> So I have an incentive to want to simplify the output as much
> as I can, consistent with remaining portable.

Yes, if you can make it even cleaner, that will certainly be worthwhile
and welcome, but don't fall prey to the misconception that pod2man(1)
were somehow bad and/or a significant origin of trouble.

About 90% of trouble in practice comes from the abomination known
by the name of DocBook, and the remaining 10% from fringe generators
like reStructuredText, pandoc, scdoc, ronn, etc. etc.  By contrast,
i think the last time perlpod(1) was in any way implicated im some
kind of noticeable trouble was significantly longer than five years
ago, unless i am forgetting something.

Yours,
  Ingo