man page width limit and example indentation (was: rseq(2) man page)

[G. Branden Robinson]

[formatting issues; CC list trimmed, added groff@]

At 2023-01-06T23:57:35+0100, Alejandro Colomar wrote:
> On 1/6/23 21:57, Mathieu Desnoyers wrote:
> The line above goes beyond column 80 in formatted output.  That's a
> hard limit for manual pages.

The hard limit should be thought of as somewhat lower--as low as 76--in
pages that use tbl(1).  This is due to a groff design issue that goes
back 30 years.[1]  I will try to resolve it for groff 1.24 but it might
be the biggest challenge I've yet undertaken with the codebase.  It will
require a redesign of how tbl(1) gets information through to the
terminal output driver, grotty(1).

(My former advice was 78 columns; I am revising that advice in a more
conservative direction having dug more deeply into tbl(1) behavior.)

Here are the details.  Some readers will want to skip to the "Practical
Advice for Man Page Authors" heading below.

1.  When a table is "boxed", meaning it uses any of the "box",
    "doublebox", or "allbox" region options, 3 extra character cells
    consumed by the leading | character and a trailing space and | at
    the end of the table row.  tbl(1) sets up a warning to be emitted at
    formatting time if this happens.  (In its role as a preprocessor,
    tbl itself doesn't know what the line length of the output device
    will be.)

2.  When a table row uses a vertical rule (|) as a column descriptor,
    tbl(1) is designed such it considers the rule as taking up
    effectively no space.  And on typesetting devices, this is true for
    practical purposes.  On terminals, though, they eat an entire
    character cell, and this matters.

    a.  _Interior_ vertical rules, as with a format of "L | L | L.", are
        not a problem in practice because the columns of the table are
        already separated by 3n of space by default.  So what usually
        happens is that the middle space of the 3 gets
        replaced/overstruck with the "|" and the table formats happily
        without getting any wider and causing problems.

    b.  However the amount of inter-column space is both
        user-configurable--you can suffix any column descriptor with a
        number to change the column separation.  Also, the "expand"
        region option will _compress_ (reduce) the amount of
        inter-column space if it has to to fit the table within the
        available line length.  Fortunately, "expand" is not that
        popular a region option; it doesn't expand _columns_, but only
        the separation between them.  What people usually want is the
        "x" modifier on a column descriptor, as with "L L Lx.".

    c.  But this means that an inter-column space amount of 0 is in
        conflict with the presence of a vertical rule in that place (on
        terminal devices).  So, on terminals, the smallest practical
        spacing after any column that contains a vertical rule is not 0,
        but 1.

3.  Another issue is related to these and I may tackle it in parallel.
    It is not possible in terminal output to direct the inclusion or
    exclusion of space adjacent to vertical rules.  Presently, their
    handling is inconsistent; a leading vertical rule as a column
    classifier gets no space after it, but a trailing vertical rule as a
    column classifier _does_ get space _before_ it.[2]

4.  In preparing the attached exhibit of all the above weirdness, I
    noticed two further bugs.

    a.  I need to revisit my fix for Savannah #63449;[3] I'm still
        seeing unnecessary drawing of vertical rules 1v above the top of
        the table in circumstances where that isn't warranted (i.e.,
        there is no intersection with a horizontal rule).  More cases
        for the regression test.

    b.  The third exhibit (line 17) overruns the line length but doesn't
        produce a warning.

I think that's all I have on tables for now.  I've fixed 19 bugs in tbl
for groff 1.23, but it's not enough.  :-|

Practical Advice for Man Page Authors
=====================================

A.  The 80-column limit on output line length for terminals is "safe" if
    tbl(1) is not used.

B.  If tbl(1) _is_ used, you're still safe if you avoid:

    i.    using boxed tables ("allbox", "box", "doublebox");
    ii.   placing vertical rules at the left and right edges of tables
          (in a row description); and
    iii.  reducing the column separation to zero before a vertical rule
          (in a row description).

C.  If you've read this far and your table is still overrunning the
    line, you may need to reduce your table's width by up to 3 character
    cells.  Since the default column separation is 3n, any table with
    more than 2 columns is guaranteed to have enough total column
    separation for 3 character cells to be "borrowed" from two of the
    columns while still having at least 1n of separation.

D.  If even that doesn't work out, or you have a two-column table that
    is overrunning the line, you need to either:

    i.   recast the content of the table to shorten it; or
    ii.  use text blocks ("T{ T}") to house some of the table entries.

> For code examples we use .in +4n rather than .RS.  I don't remember
> the exact reason, but it had some glitches in some cases.

There were no glitches that I recall, but Michael wanted the man(7)
source to be in a form where examples could be moved freely between
various contexts without needing any internal alteration.  The
discussion was in November 2020.  The following message and his reply
capture the boundaries of the problem.

https://lore.kernel.org/linux-man/20201113094755.bg6pl7g2s5h2w4mu@localhost.localdomain/

There is a limit to Michael's solution, but if the Linux man pages don't
go bonkers with deeply nested regions, it's workable.  (If they do, then
migrating examples may need to be reformatted due to changes in the
available line length; the more you indent, the less there is.)

It would please me to come up with a way, possibly a groff man(7)
extension (smaller than most, like recognition of a second argument to
the `RS` macro), that would enable "purer" man(7) input without recourse
to troff requests.

...but it might not be worth it.  If you relocate an example from a
heavily-indented region to a less-indented one, you _gain_ some line
length, and this is not an error condition.  Abbreviations or
compromises you made in an example's formatting might no longer be
necessary, and only an engaged human brain will detect the fact that the
example can be recast to leverage the added line capacity.

I don't think ChatGPT is to up that sort of thing.  Yet.

Regards,
Branden

[1] https://savannah.gnu.org/bugs/index.php?62471
[2] https://savannah.gnu.org/bugs/index.php?61597
[3] https://savannah.gnu.org/bugs/index.php?63449

table64.roff
Description: Text Data

signature.asc
Description: PGP signature