Don't despair! (was: [groff] 06/23: [man pages]: Define page-local `MR` fallback.)

[G. Branden Robinson]

Hi Ingo,

Good to hear from you!

At 2023-02-24T09:56:29+0100, Ingo Schwarze wrote:
> sorry for being totally swamped right now and temporarily losing
> track of mandoc and groff stuff, but by some strange chance, this
> caught my eye:
> 
> > +.\" Define fallback for groff 1.23's MR macro if the system lacks it.
> > +.nr do-fallback 0
> > +.if !\n(.f           .nr do-fallback 1 \" mandoc
> > +.if  \n(.g .if !d MR .nr do-fallback 1 \" older groff
> > +.if !\n(.g           .nr do-fallback 1 \" non-groff *roff
> 
> This is excessively complicated.
[...]
> Besides, in general, using \n(.g is always an extremely bad idea.
> Capabilities of implementations (both groff and others) change
> over time, so never test for application names or version numbers,
> but always test for features.
[...]
> For example, mandoc supports vast swaths of groff features,
> and yet:
[...]
> What exactly is this aiming for?
[...]
> Looks like Heirloom does not need it.
[...]
> Looks like Heirloom blows up quite loudly with your
> new "compatibility" code.
[...]
> Admittedly, Plan 9 supports neither d nor !d.

I appreciate your attempt to write *roff feature tests in the style of
Autoconf, but I fear it has led you to excessively pessimistic
conclusions, and negative ones in the experimental sense.

My defense of the current implementation is that, under testing with
practical man pages, it _works_.  At least on my Debian system.

Let me take a small page that uses the `MR` macro and show you.

https://git.savannah.gnu.org/cgit/groff.git/tree/src/preproc/eqn/neqn.1.man

When built (groff requires sed-replacement of some man page content due
to variable configuration-time properties, like a command prefix), the
foregoing file produces a man page as shown in the attachment.

Now let us see what becomes of it with four renderers: groff 1.22.4,
mandoc 1.14.5, Heirloom Doctools troff, and groff 1.23.0.rc3 (all on my
Debian bullseye system).

$ groff -v | head -n 1
GNU groff version 1.22.4
$ groff -man -Tascii -P -cbou ~/tmp/neqn.1 | cat -s

neqn(1)                     General Commands Manual                    neqn(1)

Name
       neqn - format equations for character-cell terminal output

Synopsis
       neqn [eqn-options]

Description
       neqn invokes the eqn(1) command with the ascii output device.

       eqn  does not support low-resolution, typewriter-like devices, although
       it may work adequately for very simple input.

See also
       eqn(1)

groff 1.23.0.rc3.23-5712       24 February 2023                        neqn(1)
$ dpkg -l | grep mandoc | sed 's/ \+/ /g'
ii mandoc 1.14.5-1 amd64 BSD manpage compiler toolset
$ mandoc ~/tmp/neqn.1 | cat -s
neqn(1)                     General Commands Manual                    neqn(1)

Name
       neqn - format equations for character-cell terminal output

Synopsis
       neqn [eqn-options]

Description
       neqn invokes the eqn(1) command with the ascii output device.

       eqn does not support low-resolution, typewriter-like devices, although
       it may work adequately for very simple input.

See also
       eqn(1)

groff 1.23.0.rc3.23-5712       24 February 2023                        neqn(1)
$ cd ~/heirloom # built ca. 2020-02-05 from most recent tag 191015
$ ./bin/nroff -man ~/tmp/neqn.1 | cat -s
neqn(1)                     General Commands Manual                    neqn(1)

Name
       neqn - format equations for character-cell terminal output

Synopsis
       neqn [eqn-options]

Description
       neqn invokes the eqn(1) command with the ascii output device.

       eqn does not support low-resolution, typewriter-like devices, although
       it may work adequately for very simple input.

See also
       eqn(1)

groff 1.23.0.rc3.23-5712       24 February 2023                        neqn(1)
$ cd ~/src/GIT/groff
$ ./build/test-groff -man -Tascii -P -cbou ~/tmp/neqn.1
neqn(1)                     General Commands Manual                    neqn(1)

Name
       neqn - format equations for character-cell terminal output

Synopsis
       neqn [eqn-options]

Description
       neqn invokes the eqn(1) command with the ascii output device.

       eqn  does not support low-resolution, typewriter-like devices, although
       it may work adequately for very simple input.

See also
       eqn(1)

groff 1.23.0.rc3.23-5712       24 February 2023                        neqn(1)

Before pushing the commit to which you replied, I did not in fact test
neqn(1); I tested groff_man(7), a more demanding document.

> Admittedly, Plan 9 supports neither d nor !d.

Plan 9 from User Space (P9US) troff is much like DWB 3.3 troff; it does
not reliably render groff man pages and as far as I know it never has.
groff's man pages have used \[this_style] of special character escape
sequences for decades.[1]  I think that either interest or developer
energy is lacking to make P9US troff a "modern" troff, with rare
exceptions like `MR` in its man(7) macros to make its insular
environment more comfortable for its users.  I surmise that this is
because P9US isn't a "full-stack" solution (some form of Unix kernel is
used after all) and a POSIX-ish "host" environment is always available.
So I suppose they render only P9US man pages with P9US troff.

And if they're happy with it, that's as it should be.

> But your "compatibility" code does not work either:
[...]
> 
> I did warn you that .MR might land you in trouble...

It looked scary there for a moment, and I despaired, but I think we came
through in the end.  I thank Alexis and John Gardner again for their
assistance.

> I would have prefered being wrong, but here we are.  :-(

I think you are in fact wrong here, unless you refer only to the fact
that an unusual level of care is required.  The fallback logic is
assuredly not pretty, but it seems to work.

And in part of the commit message you did not quote, I emphasized that I
don't want to hang onto this ugly boilerplate forever.

  This definition is intended as a stopgap measure only.  I want to
  revert this after groff 1.23 is released and has spread to some
  reasonable degree.

How soon I can do this depends largely on packagers/distributors.  But I
think we're talking years rather than months.  I hope it is few enough
that only one hand is needed to count them.

I am happy to revisit the content of this fallback logic for elegance,
which it assuredly lacks at present, after groff 1.23.0 final.

Keith Marshall suggested that I might go ahead and use a CSTR #54-legal
register name in place of "do-fallback", and that's not a terrible idea.
I didn't make it short in the first place because I didn't need to to
get groff 1.23.0 man pages rendering on all the formatters of interest
(enumerated above), and other things being equal, I prefer communicative
variable names to inscrutable Ken Thompson digraphs.  If, say, P9US
adapts features as discussed in the footnote, that decision is worth
reconsidering to achieve greater page portability.

Regards,
Branden

[1] If P9US embraced groff's man(7) macro extensions (the ones in
    an-ext.tmac, which are licensed such that anyone, even
    copyleft-hostile projects, may use them), and added support for a
    handful of special character identifiers you and I documented in
    groff_man_style(7)'s "Portability" section, it might be worth
    reconsidering our P9US troff support story, at least as far as our
    man pages go.  (They'd need to implement support for `\:` as well,
    and that might be the hardest part, because it requires grubbing
    around down in the hyphenation code.)  It wouldn't be a big deal to
    rewrite those \[xx] escape sequences as \(xx.  In conversation with
    Keith Marshall recently, I went over common features of groff man
    pages as of groff 1.22.3 (November 2014) that are not portable to
    "CSTR #54 troff".

    https://savannah.gnu.org/bugs/index.php?63827#comment3

neqn.1
Description: Text document

signature.asc
Description: PGP signature