[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
.ll 64n .nf 1234567890123456789012345678901234567890123456789012345678901234 .fi .TS L L L L L. abandoning babysitter cablecasts dachshunds earmarkingX .TE . .TS | L L L L L. abandoning babysitter cablecasts dachshunds earmarkingX .TE . .TS L L L L L |. abandoning babysitter cablecasts dachshunds earmarkingX .TE . . .TS | L L L L L |. abandoning babysitter cablecasts dachshunds earmarkingX .TE . .TS doublebox; L L L L L. abandoning babysitter cablecasts dachshunds earmarkingX .TE
Attachment:
signature.asc
Description: PGP signature
