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.1: Type: text/plain, Size: 12666 bytes --]

Hi Alex & Hugo,

At 2026-10-19T18:55:32+0200, Alejandro Colomar wrote:
> > Date: 2026-10-19 08:02:35-0500
> > From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
> > At 2026-10-19T08:20:29+0200, Alejandro Colomar wrote:
> > > > Date: 2026-10-17 21:19:22+0200
> > > > From: Hugo Buddelmeijer <hugo@buddelmeijer.nl>
> > > > Running `make -R check` fails because the text in futex_waitv.2
> > > > and console_codes.4 is too wide.
> > [...]
> > 
> > I observe that the failure doesn't tell you why the "check" target
> > is failing.  It simply says "GREP" and then the output of grep
> > itself.  We are not informed what grep was looking for.
> > 
> > I also observe that setting `V=1` is useless to get these Makefiles
> > to tell us what they're actually doing.
> 
> Hmmm, this gave me a good idea.  I don't like this V variable, since
> it's unclear what it should do in each project, but I've played with
> this patch:
> 
> 	diff --git i/GNUmakefile w/GNUmakefile
> 	index 9f3ced6f461b..9b480fe5e52c 100644
> 	--- i/GNUmakefile
> 	+++ w/GNUmakefile
> 	@@ -16,6 +16,7 @@ endif
> 	 MAKEFLAGS += --no-builtin-rules
> 	 MAKEFLAGS += --no-builtin-variables
> 	 MAKEFLAGS += --warn-undefined-variables
> 	+MAKEFLAGS += --silent
> 	 
> 	 
> 	 ifndef srcdir
> 	@@ -66,5 +67,4 @@ help:
> 	 
> 	 
> 	 .DELETE_ON_ERROR:
> 	-.SILENT:
> 	 FORCE:
> 
> and it seems to work.  If you use --no-silent on the command line, it
> overrides the default.  I'll check better before committing.

Cool!

> > While attempting to reproduce Hugo's results, I also noticed the
> > following messages on stderr.
> > 
> > TBL             .tmp/man/man3/matherr.3.eqn
> > tbl:".tmp/man/man3/matherr.3:204: warning: ignoring excess table entry at row 5, column 6: "\" retval is 0.0/0.0"
> > tbl:".tmp/man/man3/matherr.3:205: warning: ignoring excess table entry at row 6, column 6: "\" retval is 0.0/0.0"
> > tbl:".tmp/man/man3/matherr.3:206: warning: ignoring excess table entry at row 7, column 6: "\" retval is x/0.0"
> > tbl:".tmp/man/man3/matherr.3:241: warning: ignoring excess table entry at row 42, column 6: "\" different from log()"
> > tbl:".tmp/man/man3/matherr.3:242: warning: ignoring excess table entry at row 43, column 6: "\" different from log()"
> > tbl:".tmp/man/man3/matherr.3:249: warning: ignoring excess table entry at row 50, column 6: "\" +0 and -0"
> > tbl:".tmp/man/man3/matherr.3:257: warning: ignoring excess table entry at row 58, column 6: "\" retval is 0.0/0.0"
> > 
> > (These diagnostic messages are new to the forthcoming groff 1.25.)
> > 
> > Inspecting the file:
> > 
> > $ sed -n 194,205p man/man3/matherr.3
> > .\" Details below from glibc 2.8's sysdeps/ieee754/k_standard.c
> > .\" A subset of cases were test by experimental programs.
> > .TS
> > lB lB lB cB lB
> > l l l c l.
> > Function        Type    Result  Msg?    errno
> > 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
> > 
> > This seems like a straightforward case of someone forgetting to
> > update the table format--much easier to neglect before I added the
> > new tbl diagnostic.  In lieu of a formal patch, here are some
> > replacement lines.
> 
> 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.

> > lB lB lB cB lB l
> > l  l  l  c  l  l.
> > Function	Type	Result	Msg?	errno	\&
[...]
> > > > Maybe you could device a better patch though, in particular for
> > > > console_codes.  The affected table is much narrower than similar
> > > > tables, so some lines that have to be truncated, would easily
> > > > fit in one of the other tables.  But I couldn't easily figure
> > > > out what determines the column widths, so I didn't fix that.
> > > 
> > > I think Branden might be better at that; I've added him to CC.
[...]
> > The fix is straightforward: put the table cell in a text block.  But
> > there is one other entry in this table that is too wide.
> > 
> > $ diff -u man/man4/console_codes.4{.old,}
> 
> No git-diff(1)?  :D

Nope; see above.

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.

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
 \      \       HUGE_VAL :
 \      \       \-HUGE_VAL
 cosh(fin) o/f  OVERFLOW        HUGE    n       ERANGE
@@ -237,15 +237,15 @@ .SS Math functions that employ matherr()
 \      \       HUGE_VAL,x)
 log(0) SING    \-HUGE  y       EDOM
 log(x<0)       DOMAIN  \-HUGE  y       EDOM
-log2(0)        SING    \-HUGE  n       EDOM    \" different from log()
-log2(x<0)      DOMAIN  \-HUGE  n       EDOM    \" different from log()
+log2(0)        SING    \-HUGE  n       EDOM\" different from log()
+log2(x<0)      DOMAIN  \-HUGE  n       EDOM\" different from log()
 log10(0)       SING    \-HUGE  y       EDOM
 log10(x<0)     DOMAIN  \-HUGE  y       EDOM
 pow(0.0,0.0)   DOMAIN  0.0     y       EDOM
 pow(x,y) o/f   OVERFLOW        HUGE    n       ERANGE
 pow(x,y) u/f   UNDERFLOW       0.0     n       ERANGE
 pow(NaN,0.0)   DOMAIN  x       n       EDOM
-0**neg DOMAIN  0.0     y       EDOM    \" +0 and -0
+0**neg DOMAIN  0.0     y       EDOM\" +0 and -0
 neg**non-int   DOMAIN  0.0     y       EDOM
 scalb() o/f    OVERFLOW        (x>0.0) ?       n       ERANGE
 \      \       HUGE_VAL :
@@ -253,7 +253,7 @@ .SS Math functions that employ matherr()
 scalb() u/f    UNDERFLOW       copysign(       n       ERANGE
 \      \       \ \ 0.0,x)
 fmod(x,0)      DOMAIN  x       y       EDOM
-remainder(x,0) DOMAIN  NAN     y       EDOM    \" retval is 0.0/0.0
+remainder(x,0) DOMAIN  NAN     y       EDOM\" retval is 0.0/0.0
 .TE
 .SH ATTRIBUTES
 For an explanation of the terms used in this section, see

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

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

> > I needed to override `NROFFFLAGS` because of a new warning category
> > in the forthcoming groff 1.25.
> > 
> > groff NEWS:
> > *  The formatter supports a new warning category, "style".  It is
> >    used to diagnose input that is non-idiomatic or likely to produce
> >    an unexpected result (or none at all), but is not invalid.
> > 
> > One of the things it warns about is failure to break an input line
> > after the end of a sentence is detected.  The Linux man-pages may
> > want to disable that warning category by default until those have
> > been cleaned up.  Enabling it will, of course, permit machine-driven
> > identification of sites requiring such cleanup, which has to date
> > been tedious, requiring manual inspection or application of regexes
> > that can be thwarted by the *roff language's context-dependent
> > grammar.
> 
> We'll see when it arrives.  :)

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.

$ git grep -n -B4 '[-]ww' share
share/mk/configure/build-depends/groff-base/nroff.mk-32-DEFAULT_NROFFFLAGS ::= \
share/mk/configure/build-depends/groff-base/nroff.mk-33-        -T$(NROFF_OUT_DEVICE) \
share/mk/configure/build-depends/groff-base/nroff.mk-34-        -rLL=$(NROFF_LINE_LENGTH)n \
share/mk/configure/build-depends/groff-base/nroff.mk-35-        -rCHECKSTYLE=$(NROFF_CHECKSTYLE_LVL) \
share/mk/configure/build-depends/groff-base/nroff.mk:36:        -ww

At 2026-10-19T20:32:27+0200, Hugo Buddelmeijer wrote:
> On 10/19/26 15:02, G. Branden Robinson wrote:
> > Hi Alex & Hugo,
> > 
> > At 2026-10-19T08:20:29+0200, Alejandro Colomar wrote:
> > > > Date: 2026-10-17 21:19:22+0200
> > > > From: Hugo Buddelmeijer <hugo@buddelmeijer.nl>
> > > > Running `make -R check` fails because the text in futex_waitv.2
> > > > and console_codes.4 is too wide.
> > [...]
> > I observe that the failure doesn't tell you why the "check" target
> > is failing.  It simply says "GREP" and then the output of grep
> > itself.  We are not informed what grep was looking for.
> 
> For me the output of `make -R check` was useful enough (using groff
> 1.24.0, should have included that):
> 
> .tmp/man/man4/console_codes.4:750: warning: table wider than line
> length minus indentation
> 
> It does not exactly say which line is too long, so I removed
> 'suspicious' lines until the test passed, then added them back one by
> one, adding a text block whenever TROFF complained.

That's a good approach.  Because of the way the tbl preprocessor and the
formatter (troff) interact, it's hard to emit a precise diagnostic here;
the information isn't just lying around to be abstracted.  There might
be a way we can enhance tbl to keep track of which table cell was
responsible for causing the table to extend to its maximum width,
however.[1]  That width _is_ tracked, in the register `TW`.

tbl(1):
   roff interface
     The register TW stores the width of the table region in basic
     units; it can’t be used within the region itself, but is defined
     before the .TE token is output so that a troff macro named TE can
     make use of it.  ...

> 5 lines were to wide for the table.
> 
> The result looks rather unsatisfactory, see attached screenshot, which
> shows the affected table and the one above it.  The top one is much
> broader.

Yes.  tbl uses a formula to compute the default width of text blocks.

tbl(1):
   Text blocks
...
     If w or x modifiers are not specified for all columns of a text
     block’s span, the default length of the text block (more precisely,
     the line length used to process the text block’s diversion) is
     computed as L×C/(N+1), where L is the current line length, C the
     number of columns spanned by the text block, and N the number of
     columns in the table.  ...

> I investigated a bit deeper, and believe that the table is so narrow
> because it uses column specification "l l."; replacing that with "l
> lx." makes the table wider (probably requiring less text blocks).
> This was just cargo-culted from other tables though.

That's a good fix.  It's orthogonal to the use of text blocks, though;
on a wide terminal, applying the 'x' column modifier will quieten the
warning, but won't make the table format better on narrower terminals.
Those will still get the warning, and worse, the table will overset.

Regards,
Branden

[1] In fact, that's a good enough idea that I'll file a Savannah ticket
    for it after I have a URL for a publicly archived form of this
    message I can cross-reference.

[-- Attachment #1.2: matherr.3.diff --]
[-- Type: text/x-diff, Size: 1739 bytes --]

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
 \ 	\ 	HUGE_VAL :
 \ 	\ 	\-HUGE_VAL
 cosh(fin) o/f	OVERFLOW	HUGE	n	ERANGE
@@ -237,15 +237,15 @@ .SS Math functions that employ matherr()
 \ 	\ 	HUGE_VAL,x)
 log(0)	SING	\-HUGE	y	EDOM
 log(x<0)	DOMAIN	\-HUGE	y	EDOM
-log2(0)	SING	\-HUGE	n	EDOM	\" different from log()
-log2(x<0)	DOMAIN	\-HUGE	n	EDOM	\" different from log()
+log2(0)	SING	\-HUGE	n	EDOM\" different from log()
+log2(x<0)	DOMAIN	\-HUGE	n	EDOM\" different from log()
 log10(0)	SING	\-HUGE	y	EDOM
 log10(x<0)	DOMAIN	\-HUGE	y	EDOM
 pow(0.0,0.0)	DOMAIN	0.0	y	EDOM
 pow(x,y) o/f	OVERFLOW	HUGE	n	ERANGE
 pow(x,y) u/f	UNDERFLOW	0.0	n	ERANGE
 pow(NaN,0.0)	DOMAIN	x	n	EDOM
-0**neg	DOMAIN	0.0	y	EDOM	\" +0 and -0
+0**neg	DOMAIN	0.0	y	EDOM\" +0 and -0
 neg**non-int	DOMAIN	0.0	y	EDOM
 scalb() o/f	OVERFLOW	(x>0.0) ?	n	ERANGE
 \ 	\ 	HUGE_VAL :
@@ -253,7 +253,7 @@ .SS Math functions that employ matherr()
 scalb() u/f	UNDERFLOW	copysign(	n	ERANGE
 \ 	\ 	\ \ 0.0,x)
 fmod(x,0)	DOMAIN	x	y	EDOM
-remainder(x,0)	DOMAIN	NAN	y	EDOM	\" retval is 0.0/0.0
+remainder(x,0)	DOMAIN	NAN	y	EDOM\" retval is 0.0/0.0
 .TE
 .SH ATTRIBUTES
 For an explanation of the terms used in this section, see

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