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: 13577 bytes --]

Hi Branden,

> Date: 2026-10-19 08:02:35-0500
> From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
>
> 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.
> 
> 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.

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

> lB lB lB cB lB l
> l  l  l  c  l  l.
> Function	Type	Result	Msg?	errno	\&
> 
> (In the meantime, I'll try and see if the leading double quote before
> the file name in tbl(1)'s diagnostic is due to groff 1.24/1.25 version
> skew in my environment, or a bug in 1.25 I need to fix before final
> release.  It looks like the former.
> 
> $ ~/groff-HEAD/bin/groff -tz -man -T utf8 man/man3/matherr.3
> tbl:man/man3/matherr.3:204: warning: ignoring excess table entry at row 5, column 6: "\" retval is 0.0/0.0"
> tbl:man/man3/matherr.3:205: warning: ignoring excess table entry at row 6, column 6: "\" retval is 0.0/0.0"
> tbl:man/man3/matherr.3:206: warning: ignoring excess table entry at row 7, column 6: "\" retval is x/0.0"
> tbl:man/man3/matherr.3:241: warning: ignoring excess table entry at row 42, column 6: "\" different from log()"
> tbl:man/man3/matherr.3:242: warning: ignoring excess table entry at row 43, column 6: "\" different from log()"
> tbl:man/man3/matherr.3:249: warning: ignoring excess table entry at row 50, column 6: "\" +0 and -0"
> tbl:man/man3/matherr.3:257: warning: ignoring excess table entry at row 58, column 6: "\" retval is 0.0/0.0"
> )
> 
> > > 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.
> 
> Here's the table as formatted using groff 1.25 defaults (same as 1.24),
> with the preceding paragraph for context and to make the location of the
> right margin clear.
> 
>      It accepts ESC ] (OSC) for the setting of certain resources.   In  addition
>      to  the ECMA‐48 string terminator (ST), xterm(1) accepts a BEL to terminate
>      an OSC string.  These are a few of the OSC control sequences recognized  by
>      xterm(1):
> 
>      ESC ] 0 ; txt ST           Set icon name and window title to txt.
>      ESC ] 1 ; txt ST           Set icon name to txt.
>      ESC ] 2 ; txt ST           Set window title to txt.
>      ESC ] 4 ; num ; txt ST     Set color num (0‐255) to txt.
>      ESC ] 5 ; 0 ; txt ST       Set the color for bold substitution to txt.
>      ESC ] 5 ; 1 ; txt ST       Set the color for underline substitution to txt.
>      ESC ] 5 ; 2 ; txt ST       Set the color for blinking substitution to txt.
>      ESC ] 5 ; 3 ; txt ST       Set the color for reverse substitution to txt.
>      ESC ] 5 ; 4 ; txt ST       Set the color for italic substitution to txt.
>      ESC ] 6 ; 0 ; val ST       Toggle bold rendition: 0=bold, 1=substitute by color.
>      ESC ] 6 ; 1 ; val ST       Toggle underscore rendition: 0=underscore, 1=color.
>      ESC ] 6 ; 2 ; val ST       Toggle blinking rendition: 0=blinking, 1=color.
>      ESC ] 6 ; 3 ; val ST       Toggle reverse rendition: 0=reverse, 1=color.
>      ESC ] 6 ; 4 ; val ST       Toggle italic rendition: 0=italic, 1=color.
>      ESC ] 10 ; txt ST          Set the foreground text color to txt.
>      ESC ] 11 ; txt ST          Set the background color to txt.
>      ESC ] 12 ; txt ST          Set the text cursor color to txt.
>      ESC ] 13 ; txt ST          Set the mouse cursor foreground color to txt.
>      ESC ] 14 ; txt ST          Set the mouse cursor background color to txt.
>      ESC ] 15 ; txt ST          Set the Tektronix foreground color to txt.
>      ESC ] 16 ; txt ST          Set the Tektronix background color to txt.
>      ESC ] 17 ; txt ST          Set  the  background  text color for highlighted (se‐
>                                 lected) text to txt.
>      ESC ] 18 ; txt ST          Set the Tektronix cursor color to txt.
>      ESC ] 19 ; txt ST          Set the foreground text color  for  highlighted  (se‐
>                                 lected) text to txt.
>      ESC ] 46 ; name ST         Change  log file to name (normally disabled by a com‐
>                                 pile‐time option).
>      ESC ] 50 ; fn ST           Set font to fn (the escape code is normally disabled;
>                                 see "allowFontOps" in xterm(1)).
>      ESC ] 104 ; num ST         Reset color for mode 4;num
>      ESC ] 105 ; num ST         Reset color for mode 5;num
>      ESC ] 106 ; num ; val ST   Exactly equal to 6;num;val.  (no "reset" logic)
>      ESC ] 110 ST               Reset color for mode 10.  Codes 111‐119 map to reset‐
>                                 ting modes 11‐19, respectively.
>      ESC ] mode ; ? ST          Query  the  respective  property/color/etc.    (modes
>                                 4,5,10‐19,50)
> 
> We can see that this line is troublesome:
> 
>      ESC ] 6 ; 0 ; val ST       Toggle bold rendition: 0=bold, 1=substitute by color.
> 
> My hunch is that the rightmost column is not set in a text block when it
> should be.  What's a text block, you ask?
> 
> tbl(1):
>    Text blocks
>      An ordinary table entry’s contents can make a column, and therefore
>      the table, too wide; the table then exceeds the line length of the
>      page, and becomes ugly or is exposed to truncation by the output
>      device.  When a table entry requires more conventional typesetting,
>      breaking across more than one output line (and thereby increasing
>      the height of its row), it can be placed within a text block.
> 
>      tbl interprets a table entry of “T{” at the end of an input line
>      specially, as a token starting a text block.  Similarly, an entry
>      “T}” at the start of an input line ends a text block.  Text block
>      tokens can share an input line with other table data (preceding T{
>      and following T}).  Input lines between these tokens are formatted
>      in a diversion by troff.  Text blocks cannot be nested.  Multiple
>      text blocks can occur in a table row.
> ...
> 
> So let's check the page source.
> 
> $ sed -n 748,762p man/man4/console_codes.4
> .TS
> l l.
> ESC ] 0 ; \f[I]txt\f[] ST       T{
> Set icon name and window title to
> .IR txt .
> T}
> ESC ] 1 ; \f[I]txt\f[] ST       Set icon name to \f[I]txt\f[].
> ESC ] 2 ; \f[I]txt\f[] ST       Set window title to \f[I]txt\f[].
> ESC ] 4 ; \f[I]num\f[] ; \f[I]txt\f[] ST        Set color \f[I]num\f[] (0-255) to \f[I]txt\f[].
> ESC ] 5 ; 0 ; \f[I]txt\f[] ST   Set the color for bold substitution to \f[I]txt\f[].
> ESC ] 5 ; 1 ; \f[I]txt\f[] ST   Set the color for underline substitution to \f[I]txt\f[].
> ESC ] 5 ; 2 ; \f[I]txt\f[] ST   Set the color for blinking substitution to \f[I]txt\f[].
> ESC ] 5 ; 3 ; \f[I]txt\f[] ST   Set the color for reverse substitution to \f[I]txt\f[].
> ESC ] 5 ; 4 ; \f[I]txt\f[] ST   Set the color for italic substitution to \f[I]txt\f[].
> ESC ] 6 ; 0 ; \f[I]val\f[] ST   Toggle bold rendition: 0=bold, 1=substitute by color.
> 
> Yup.
> 
> 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

> --- man/man4/console_codes.4.old        2026-10-19 07:40:06.562768271 -0500
> +++ man/man4/console_codes.4    2026-10-19 07:44:11.729514217 -0500
> @@ -759,8 +759,12 @@
>  ESC ] 5 ; 2 ; \f[I]txt\f[] ST  Set the color for blinking substitution to \f[I]txt\f[].
>  ESC ] 5 ; 3 ; \f[I]txt\f[] ST  Set the color for reverse substitution to \f[I]txt\f[].
>  ESC ] 5 ; 4 ; \f[I]txt\f[] ST  Set the color for italic substitution to \f[I]txt\f[].
> -ESC ] 6 ; 0 ; \f[I]val\f[] ST  Toggle bold rendition: 0=bold, 1=substitute by color.
> -ESC ] 6 ; 1 ; \f[I]val\f[] ST  Toggle underscore rendition: 0=underscore, 1=color.
> +ESC ] 6 ; 0 ; \f[I]val\f[] ST  T{
> +Toggle bold rendition: 0=bold, 1=substitute by color.
> +T}
> +ESC ] 6 ; 1 ; \f[I]val\f[] ST  T{
> +Toggle underscore rendition: 0=underscore, 1=color.
> +T}
>  ESC ] 6 ; 2 ; \f[I]val\f[] ST  Toggle blinking rendition: 0=blinking, 1=color.
>  ESC ] 6 ; 3 ; \f[I]val\f[] ST  Toggle reverse rendition: 0=reverse, 1=color.
>  ESC ] 6 ; 4 ; \f[I]val\f[] ST  Toggle italic rendition: 0=italic, 1=color.
> 
> I still got the warning about the table being too wide, spuriously.
> That appears to be due a workaround for old bugs in GNU tbl.[1]
> 
> $ git grep NROFF_LINE_LENGTH
> share/mk/configure/build-depends/groff-base/nroff.mk:ifndef NROFF_LINE_LENGTH
> share/mk/configure/build-depends/groff-base/nroff.mk:NROFF_LINE_LENGTH    ::= $(shell $(EXPR) $(MANWIDTH) - 2)
> share/mk/configure/build-depends/groff-base/nroff.mk:   -rLL=$(NROFF_LINE_LENGTH)n \
> 
> 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 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.  :)


Have a lovely night!
Alex

> 
> Regards,
> Branden
> 
> [1] https://savannah.gnu.org/bugs/?63749
>     https://savannah.gnu.org/bugs/?63640
>     https://savannah.gnu.org/bugs/?62471



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

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