Re: table layout in console_codes.4 (was: `make -R check` fails due to futex_waitv.2 and console_codes.4 being too wide)

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 10350 bytes --]

Hi Branden,

> Date: 2026-10-23 15:32:16-0500
> From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
>
[...]
> 
> > > > I'd love a formal patch, especially with a good commit message.
> > > > :)
> > > 
> > > I'm sure.  But I'm dealing with yet another late-release-cycle fire
> > > drill in groff right now, unfortunately.
> > 
> > I'm patient.  MR.sed made me learn.  :p
> 
> I learned from it too.
> 
> Some news on that front.  Would you be willing to stage the roll-out
> of this transition?

Certainly!  One major problem from your script was that it was huge and
difficult to understand.  Partial scripts will be significantly simpler.

>  The syscalls(2) page is what broke us before--you
> wanted extensive annotations to my sed scripts.

Actually, I would have preferred a pipeline of one-liner commands,
without having to be a sed(1) expert to understand it.  Something like
the implementation of sortman(1) would be great.

>  (Not unreasonable, but
> demanding of further effort on my part.)  The rest seemed easy.  Maybe
> if we can migrate:
> 
> 1.  everything but syscalls(2) first; then

Sure; as long as the commit message says something like "we're leaving
syscalls(2) --and only syscalls(2)-- out of this transition, because
it's way more complex than the rest", I'd take it.

> 2.  migrate syscalls(2) in multiple passes, each of 1 sed script, each
>     showing no change in the formatting of rendered text.

Yup.

> I think users and readers will enjoy (and could have been enjoying) a
> major benefit to their man page browsing experience even with only step
> 1 done.  Now that GNU less has its own OSC 8 interpreter and
> appropriately equipped versions are making it into distributions, the
> power of man page hyperlinking is easy to see.  Literally, even, with
> even more recent changes to apply underlining to hyperlinked character
> cells.  The latest version of less, v712, released this past week, even
> defaults to "less -R".[0]  A future I dreamed of in 2018 is finally
> arriving.
> 
> In other news, Oracle finally did a thing I once thought they had done
> in Solaris 11, then had to correct my understanding about, and then had
> to re-correct myself again.
> 
> About 2½ years ago, in SRU66 (a kind of service pack), an update to
> Solaris 11.4, Oracle completely discarded their AT&T System V troff.
> It's _gone_.  What replaced it?  groff 1.23.0--which supports groff
> man's `MR` macro.[1]

Wow!  :-)

> 
> They kept some auxiliary stuff like checkeq(1) and checkmm(1) (neither
> of which GNU eqn or groff mm need, since they internally implement more
> generous diagnostics than their AT&T implementations).  And they
> implemented a bunch of wrappers to force preconv(1) into execution
> pipelines.
> 
> So between groff >= 1.23.0 and, well, the _next_ release of mandoc(1)--
> any day now, it's to be hoped--support for `MR` will be nearly
> universal.

Very please CC Ingo in that patch.  :)

> I didn't ever expect mandoc's release cadence to become slower than
> groff's!

Heh!

> > > And on second thought it occurs to me that you may not want that
> > > column in the table after all, since they are all *roff comments
> > > intended (I think) only for inspection by the document maintainer,
> > > not by the reader.  In that case what you want to do is not add a
> > > column, but stop supplying excess table entries--in other words,
> > > discard the tab character before the `\"` comment escape sequence.
> > 
> > Yes, and no.
> > 
> > > diff --git a/man/man3/matherr.3 b/man/man3/matherr.3
> > > index 2e179e358..8711ee3cd 100644
> > > --- a/man/man3/matherr.3
> > > +++ b/man/man3/matherr.3
> > > @@ -200,9 +200,9 @@ .SS Math functions that employ matherr()
> > >  acos(|x|>1)    DOMAIN  HUGE    y       EDOM
> > >  asin(|x|>1)    DOMAIN  HUGE    y       EDOM
> > >  atan2(0,0)     DOMAIN  HUGE    y       EDOM
> > > -acosh(x<1)     DOMAIN  NAN     y       EDOM    \" retval is 0.0/0.0
> > > -atanh(|x|>1)   DOMAIN  NAN     y       EDOM    \" retval is 0.0/0.0
> > > -atanh(|x|==1)  SING    (x>0.0)?        y       EDOM    \" retval is x/0.0
> > > +acosh(x<1)     DOMAIN  NAN     y       EDOM\" retval is 0.0/0.0
> > > +atanh(|x|>1)   DOMAIN  NAN     y       EDOM\" retval is 0.0/0.0
> > > +atanh(|x|==1)  SING    (x>0.0)?        y       EDOM\" retval is x/0.0
> > 
> > It was certainly more readable with the tab.  Would a couple of spaces
> > be okay?  Or will they produce spurious space too that might fail?
> 
> The problem is that you'll still have a comment escape sequence in a
> table entry.  Since groff 1.24.0, GNU tbl warns about that (unless the
> comment escape sequence occurs in a text block, where these escape
> sequenced don't cause problems).  Unfortunately groff 1.24.x produce an
> extra warning diagnostic in this case that is not helpful.  I just
> discovered that while composing this email and have scheduled a fix for
> groff 1.25.0.[2]

We can wait for 1.25.0.

> $ ./build/test-groff -tz -W style -m an -T utf8 ../man-pages/man3/matherr.3
> tbl:../man-pages/man3/matherr.3:240: warning: comment escape sequence '\"' in entry "EDOM\" different from log()"
> tbl:../man-pages/man3/matherr.3:241: warning: comment escape sequence '\"' in entry "EDOM\" different from log()"
> tbl:../man-pages/man3/matherr.3:248: warning: comment escape sequence '\"' in entry "EDOM\" +0 and -0"
> troff:../man-pages/man3/matherr.3:203: warning: missing closing delimiter in width computation escape sequence; expected special character or class 'tbl', got a newline [-w delim]
> troff:../man-pages/man3/matherr.3:204: warning: missing closing delimiter in width computation escape sequence; expected special character or class 'tbl', got a newline [-w delim]
> troff:../man-pages/man3/matherr.3:205: warning: missing closing delimiter in width computation escape sequence; expected special character or class 'tbl', got a newline [-w delim]
> troff:../man-pages/man3/matherr.3:240: warning: missing closing delimiter in width computation escape sequence; expected special character or class 'tbl', got a newline [-w delim]
> troff:../man-pages/man3/matherr.3:241: warning: missing closing delimiter in width computation escape sequence; expected special character or class 'tbl', got a newline [-w delim]
> troff:../man-pages/man3/matherr.3:248: warning: missing closing delimiter in width computation escape sequence; expected special character or class 'tbl', got a newline [-w delim]
> troff:../man-pages/man3/matherr.3:256: warning: missing closing delimiter in width computation escape sequence; expected special character or class 'tbl', got a newline [-w delim]
> ../man-pages/man3/matherr.3:199: warning: table wider than line length minus indentation
> 
> The riot of delimiter warnings is the havoc that use of a comment escape
> sequence in a (non-text-block) table entry creates.
> 
> I added that warning in groff 1.24.0 because without it, a user is
> unlikely to comprehend what is supposed to be wrong with their table.
> 
> Or they would have been uncomprehending, had they enabled warnings in
> category "delim", which were not on by default.  In groff 1.25.0, they
> will be.

I trust you to send me your best patch, because I don't know what to do
with it.  If you think the best thing is to juts remove the tabs, I
guess I could live with it.

> 
> > [...]
> > > 
> > > (Also attached.)
> > > 
> > > If the foregoing looks ugly, bear in mind that you're wandering a
> > > bit off the path with these comments.
> > > 
> > > tbl(1):
> > > Limitations
> > >      Within a tbl region (except in text blocks or on roff control
> > >      lines), avoid escape sequences that read the rest of the input
> > >      line, as \" and \! do.
> > 
> > Hmmm.
> 
> This is a consequence of how tbl works.  It generates *roff `\w` escape
> sequences bracketing the table entry contents so that the formatter can
> compute their rendered widths.  Without font metrics, tbl cannot do that
> itself.
> 
> My recommendation is to move these "inline" comments to precede what
> they document.
> 
> -acosh(x<1)     DOMAIN  NAN     y       EDOM    \" retval is 0.0/0.0
> +.\" retval is 0.0/0.0
> +acosh(x<1)     DOMAIN  NAN     y       EDOM

Not a fan of this.  Maybe just remove the tabs.  Or maybe we want to
print these in the table as a new column?

> > > > > I was able to get a complete, successful check with the
> > > > > following command.
> > > > > 
> > > > > $ make -R check NROFF_LINE_LENGTH=80 NROFFFLAGS=-Wstyle
> > > > 
> > > > Thanks!  Would you mind sending a formal patch set?  =)
> > > 
> > > I'll need a reminder when I feel less swamped (after groff 1.25.0,
> > > likely), or someone else can steal my fixes.  :)
> > 
> > Okay.  Do you have an estimate of when I should poke you?  As in maybe
> > one month or two?
> 
> Say, two weeks after groff 1.25.0 final, which I'll announce here as
> usual.  By then I should know if the release was a triumph, a disaster
> (and therefore will be keeping me busy), or met with the usual stony
> indifference.

Ok.

> > > Yeah, I wouldn't want to fool with it before it lands in an official
> > > release, either.  But this _does_ mean that the Linux man-pages
> > > documents will appear to "regress" suddenly when the host system
> > > upgrades to groff 1.25.0, because you use `-ww` to turn on all
> > > warnings.
> > 
> > If you're willing to spend some time on helping me address the
> > diagnostics by improving the pages, that's fine.  :)
> 
> I don't doubt it.  I have a lot of irons in man page fires!

:-)


Have a lovely night!
Alex

> 
> Regards,
> Branden
> 
> [0] https://github.com/gwsw/less/commit/7f46e9ff46216f3e560cd1f41ddf3b36b11eec0e
> [1] https://blogs.oracle.com/solaris/whats-new-in-oracle-solaris-114-sru-66
> 
>     That blog entry doesn't make any _note_ of this change, but it's
>     there.  I have been able to examine it at cfarm.net.
> 
>     Also, there's this evidence:
> 
>     http://pkg.oracle.com/solaris/release/en/search.shtml?token=groff&action=Search
> 
> [2] https://savannah.gnu.org/bugs/?68825



-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]