Hi Branden,

On Sun, Oct 05, 2025 at 07:45:45AM -0500, G. Branden Robinson wrote:

quoted

quoted

I would format the document with `MANWIDTH=65` and, for any line
that still oversets, stuff the descriptive table entry into a text
block.

I've done it with MANWIDTH=72 for the commit above.  However, if I go
down to 64, I see some cases where we're using text blocks, and
groff(1) still doesn't do a good job:

Well, first, I personally wouldn't ever take the MANWIDTH down below
65n, except to troubleshoot a macro package or the formatter itself.

A line length of 6.5 inches, or 65 ens on a typewriter using a "10
pitch" font, which amounts to the same thing, is about a 55-year-old
tradition in *roff.  Maybe longer, depending on what Jerry Salzer's
default for "RUNOFF" was.  It's pretty deep in cement, like the
presumption of U.S. letter paper size.  Of course these things are
configurable (and I'm sad that the U.S. doesn't use ISO paper sizes),
but due to inertia and the size of existing corpora of man pages,
pursuing good formatting at a narrower line length than that seems like
an unrewarding effort to me.

Setting matters of style and strategy aside, I have a technical question
to field.

Hmmm, I used 64 as it's the multiple of 8 that's closest to 65.  But
it's good to know that 65 is historically important.

quoted

	$ MANWIDTH=80 man ./console_codes.4 | grep '.\{81\}'
	$ MANWIDTH=72 man ./console_codes.4 | grep '.\{73\}'
	<standard input>:130: warning: table wider than line length minus indentation
	$ MANWIDTH=64 man ./console_codes.4 | grep '.\{65\}'
	<standard input>:130: warning: table wider than line length minus indentation
	     ESC Z     DECID    DEC private identification.  The kernel returns
				the string ESC [ ? 6 c, claiming that it is a
	     ESC 7     DECSC    Save current state (cursor coordinates, attrib‐
				utes, character sets pointed at by G0, G1).
	     ESC 8     DECRC    Restore state most recently saved by ESC 7.
	     ESC % @               Select default (ISO/IEC 646 / ISO/IEC 8859‐1)
	     ESC # 8   DECALN   DEC screen alignment test - fill screen with
	     ESC (              Start sequence defining G0 character set (fol‐
	     ESC ( U            Select null mapping - straight to character ROM.
	     ESC ( K            Select user mapping - the map that is loaded by
	     ESC )              Start sequence defining G1 (followed by one of
	     ESC ] P            Set palette, with parameter given in 7 hexadeci‐
				mal digits nrrggbb after the final P.  Here n is
				the color (0–15), and rrggbb indicates the

But if we check the source code for the first one, we see it's within
a text block:

	$ grep -C2 'kernel returns' console_codes.4
	ESC Z	DECID	T{
	DEC private identification.
	The kernel returns the string ESC [ ? 6 c,
	claiming that it is a VT102.
	T}

Why is that?

It's because of item 7 I mentioned:

quoted

quoted

7.  Stop using `\0` escape sequences to achieve indentation of table
    entries; favor `\ ` (an unbreakable space) instead.  We're not
    laying out numeric data, and both are universally portable.  We
    don't want to use groff's `\~` because we don't want these
    spaces to adjust.  Really, we shouldn't be using space to indent
    table entries at all.  That's what the `A` column classifier is
    for.  Using `A` brings the additional advantage that if a text
    block is in a column using that classifier, and it breaks,
    subsequent lines are indented the same as the first.  This
    advantage is unavailable with `\0` or `\ ` because you don't
    know in the document source what the width (line length) of the
    output device will be.  In fact, I'll attach a second version of
    the diff capturing that reform too.

The troublesome line is this:

$ sed -n 150p man4/console_codes.4
ESC % @         \0\0\0Select default (ISO/IEC\~646 / ISO/IEC\~8859-1)

Hmmm, thanks!

quoted

quoted

Consulting my Git checkout of `man-pages`, I see that while some
entries in this table use text blocks, others don't.

$ nroff -t -rLL=65n -man -P-cbou man4/console_codes.4 | grep -E '.{66}' | wc -l
man4/console_codes.4:130: warning: table wider than line length minus indentation
man4/console_codes.4:330: warning: table wider than line length minus indentation
29

Those warnings will be wanting attention.  Also, I noticed that some
of the table entries overset _even though_ they're already _in_ text
blocks.  How is this possible?

Yup.  I'm intrigued.  That explains why the entry right after the one
I fixed was oversetting, even though it was in a text block.

But I don't think it explains the ones I'm showing above.  At least
not so obviously.  The entry for 'ESC Z' is the first one that
oversets, and it's within a text block.  Would you mind explaining
that?

It's the same problem with the same explanation.  The "ESC % @" blows
out the table width, its column uses the `x` modifier, and that column
is shared with text blocks.  Thus those text blocks greedily use the
width of the "ESC % @" row.

quoted

quoted

Fixing up a couple of spots where text blocks should have been used
but weren't (diff attached), I get the following result.

The diff changes more than I'd expect.

To a man with a 10 kW clipper, everything looks like a yak...

quoted

quoted

$ nroff -t -rLL=65n -man -P-cbou man4/console_codes.4 | grep -E '.{66}'\
    | wc -l
0

I made several other changes to fix things that drive me crazy.  Most
are cosmetic.

1.  Stop using `ad` requests.  They don't do what people think.[3]
    However, _do_ use `na` requests _inside text blocks_ where
    necessary to defeat adjustment, because they work reliably
    there, and cannot damage the rest of the page.[5]

Would you mind suggesting a separate patch?

Sure, I figured.  :)

quoted

And why do we want .na sometimes?

If there's not a lot of real estate on the page/screen for a column
using a text block, adjustment can look ugly.

quoted

Why is it necessary to not adjust sometimes?

I don't know if it's ever _necessary_, but it can be appealing.

quoted

quoted

2.  Add paragraph macros before tables so that they set like
    typographical "displays".  This is common (if not universal)
    practice, sometimes done already in the Linux man-pages[6] and I
    think it looks better.

I'll do this globally.  Would you also do that for 'allbox' tables?
Or should I keep those as an exception?  (See man3 pages; section
ATTRIBUTES.)

I don't have an opinion there.  I _am_ pleased to report that you can
exercise either choice and groff 1.23 will not betray you.

https://savannah.gnu.org/bugs/?63749
https://lists.gnu.org/archive/html/groff-commit/2022-07/msg00134.html

[...]

quoted

quoted

5.  Remove trailing spaces from entries in the "Linux Console
    Private CSI Sequences" table.  This makes more efficient use of
    space and, for some screen widths, permits more table rows to
    fit on the line.

Trailing spaces?  I can't find any:

	$ grep -rn ' $'
	man7/bpf-helpers.7:37:.\" 
	man7/bpf-helpers.7:41:.\" 

They trail the _table entry_, not the input line.

Inspect the "ESC [ 8 ]", "ESC [ 13 ]", and "ESC [ 14 n ]" rows.

What you want to look for are spaces followed by tabs--assuming the
table uses tabs as its column separator in the data entries.

Ahh, now I see.  I've fixed those.

quoted

quoted

so let me know which of the enumerated items you want

Possibly all of them.  I'm not 100% sure, but please send them all.

Can do.

Cheers,
Alex

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).