Re: rc3: groff man pages truncated by mandoc(1)

[G. Branden Robinson]

Hi Alexis,

At 2023-02-21T19:02:14+1100, Alexis wrote:
> i've just installed rc3 via the relevant Gentoo ebuild. My Gentoo
> system is mandoc-based, via the `system-man` USE flag.
> 
> Running `man` - actually the `mandoc` binary - still works fine
> overall, but not with the new groff man pages. For example, `man
> groff_man_style` produces this as the entirety of its output:
> 
> --- ✂ ---
> groff_man_style(7)     Miscellaneous Information Manual groff_man_style(7)
> 
> Name
>       groff_man_style - GNU roff man page tutorial and style       guide
> 
> groff 1.23.0.rc3               21 February 2023 groff_man_style(7)
> --- ✂ ---

I can reproduce this (with mandoc 1.14.5-1 in Debian bullseye).

> On the other hand, `groff -man -Tutf8 /usr/share/man/man7/groff_man_style.7`
> works just fine.

Yes.  (You'll want a "-t" in there too, for the tables.)

> Is there something in 1.23 that mandoc needs to be updated to support?

Yes.  And it's something mandoc maintainer Ingo Schwarze doesn't really
want to support.  Or, at least, my recollection is that he expressed
great reluctance about doing so the last time he participated in a
discussion of it on this list.  It's been some months since we've seen
him, sadly.  It was just about the time I started making edits to the
groff_mdoc(7) man page...

Ironically enough, it was a recent change (see below) taking into
account Ingo's advice for how to proceed with what he considered an
ill-advised new macro (MR) that has caused the groff man pages to
malfunction so badly with mandoc(1).

A sufficiently enthusiastic mandoc partisan may consider this a feature,
not a bug, if it drives people away from using groff at all...

> Or, more likely, am i just doing something wrong, or not doing
> something right?

Nope, you did nothing wrong.

You can take out the following material from groff man pages:

.\" Define fallback for groff 1.23's MR macro if the system lacks it.
.de @@
.  de MR
.    ie \n(.$=1 \
.      I %\$1
.    el \
.      IR %\$1 (\$2)\$3
.  \\.
..
.if  \n(.g .if !d MR .@@
.if !\n(.g .@@
.rm @@

(*roff experts: yes, there is a stupid mistake in the above[1].  I will
fix it.)

...and a lot more will render, but crucially, the man page cross
references will be gone, which is why I put in the above hack in the
first place (on 3 February[2]), and which I would like to dispose of for
groff 1.24 or so.

While I'm unhappy to see mandoc(1) doing this, I think it's preferable
to the _subtle_ omission of man page cross references.  With the
severely truncated output you're seeing, it is at least obvious to the
user that something is wrong.

mandoc is not a true *roff language interpreter, so I am not aware of
anything I can do in the groff man pages to work around mandoc's lack of
support for this feature.

If I could do something like the following:

.if \n[.mandoc] .als MR IR

...in groff's man pages to accommodate mandoc(1), I would, happily.  But
mandoc, to the best of my knowledge, simply isn't designed to do things
like alias macros.

Incidentally, I don't blame mandoc(1) for not being able to parse that
stuff I pasted up there.

This is a problem, and I don't think it can be resolved without help
from mandoc(1).  The alternative--ripping out what I consider to be
groff 1.23 man(7)'s signature feature--is not something I am willing to
do (see the "News" item in the RC3 announcement for why I think `MR` is
important).

There is a set of people who feel that man pages should be composed only
in mdoc(7) and rendered only with mandoc(1).  I am not one of them.

The easiest thing for mandoc(1) to do is to treat `MR` as a near synonym
of `IR` (or `BR`), slapping parentheses around the second argument.  It
does not have to do any of the hyperlinking or OSC 8 stuff that groff's
implementation does.  I have no problem working on (and, if successful,
contributing) a patch for this, but I have two major tasks in my queue
_after_ groff 1.23.0 final to take care of first.

Thank you very much for raising this issue before the final release;
this is an important matter that needs to be warned about in the
announcement.

If you'd like to share your/a surname, I can credit you by your full
name as a contributor in the release announcement (as you saw in the rc3
email).  By bringing this matter to my attention, you have spared me
embarrassment.[1 again]  Otherwise, like Gene in the same credits, you
can remain mononymous, if potentially ambiguous.  :)

Regards,
Branden

[1] You may have noticed the startling paucity of backslashes in the
    macro definition.  I tested my change, but forgot that I had a
    fallback definition of `MR` in my /etc/groff/man.local, so the
    alternative definition within the man page was never interpreted.

    I _hate_ working under deadline pressure.  You may see why I try to
    avoid doing so.  This is why I would prefer to have someone else
    serving as groff release engineer who can say, "it's good enough to
    ship".  They can catch me in a lull, not a frenzy.  And I will
    seldom feel frenzied if I don't have to meet a deadline.

[2] The backslash quantity didn't look stupid when I was writing the
    change, because I wrote it in sed.

    
https://git.savannah.gnu.org/cgit/groff.git/commit/?id=18d708e489758636ff9e168eee2592591755eb61

    The quantity of backslashes in the fix is going to be truly
    dizzying.  I know--I'll just temporarily change the escape
    character.  Surely Ingo won't buy a plane ticket and fly overseas
    just to kill me.  ;-)

    (No, I won't change the escape character in our man pages.)

signature.asc
Description: PGP signature