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

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

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

Hi Alex,

At 2026-10-23T20:06:01+0200, Alejandro Colomar wrote:
> > Date: 2026-10-19 17:41:45-0500
> > From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
> > > If you use --no-silent on the command line, it overrides the
> > > default.  I'll check better before committing.
> > 
> > Cool!
> 
> Committed and released.  :-)

Good stuff!

> > > 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?  The syscalls(2) page is what broke us before--you
wanted extensive annotations to my sed scripts.  (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
2.  migrate syscalls(2) in multiple passes, each of 1 sed script, each
    showing no change in the formatting of rendered text.

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]

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.

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

> > 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]

$ ./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.

> [...]
> > 
> > (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

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

> > 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!

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

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