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

[Alejandro Colomar (man-pages)]

Hi Branden,

On Tue, Feb 21, 2023, 10:19 G. Branden Robinson <
g.branden.robinson@gmail.com> wrote:

> 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


Michael last updated man7.org back in September 2021 (AFAIR).  Did it
really affect your groff pages?  Was MR already implemented back then?

Cheers,

Alex


>
>     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.)
>