Hi Michael and Alex,
A bit of my narrative about adjustment was unclear, and a bit of it was
wrong.
At 2021-01-29T07:57:34+1100, G. Branden Robinson wrote:
> (1) In the groff man pages we do _not_ encourage wrapping tables with
> .na/.ad pairs. (I do notice you said ".ad l/.ad" instead--I'll return
> to that.) Quoting a commit to our tbl(1) man page from September[1]:
>
> Stop advising people to use adjustment-altering requests to bracket
> tables to cheaply set the alignment of text blocks ("T{", "T}") in
> table entries. This is bad advice for man pages (it was overriding
> -dAD=l to force full justification on after a table in groff_ms(7)).
> Adjustment requests can be embedded inside text blocks anyway, and you
> don't even have to remember to undo them.
>
> The problem with .na before a table, which is the more popular
> approach, and which you probably already discovered given that you're
> recommending ".ad l" instead, is that people who have found a way to
> force adjustment off already will be angry with man pages taking your
s/your/that/
> advice because "full" adjustment (to both margins) will spring to life
> after the table.
> People who _do_ like adjustment to both margins will also be angry
> with your man pages because ".ad l" configures the adjustment mode to
> be ragged-right, which means ".ad" afterwards is a no-op.
The above is false. The .ad request aggrieves me badly because of the
non-orthogonal implementation of adjustment mode and its enablement.
.ad restores the previous adjustment mode, _unless_ that mode was left
adjustment (set by ".ad l"), in which case it starts adjusting at both
margins again.
My _advice_ is unaffected by these details; I think it is better to
advise man page authors to disable adjustment and hyphenation in tables
as needed on a per-text block basis.
On the portability front, it may also be worth noting that Heirloom
Doctools's man macros not only disable hyphenation and set left
adjustment, but delete requests so that these settings can't be altered
afterward.
Heirloom Doctools tbl also does not seem to correctly support the "x"
column modifier to expand the column until the line length is reached;
this seems to be a bug, as it's the only GNU tbl extension documented as
supported in its tbl(1) man page. (I'm using version 191015.)
mandoc 1.14.1 forces left adjustment and disables hyphenation in all
circumstances, but _does_ correctly support "x" in tables.
I apologize for the error above. I'm attaching another man page that
demonstrates the above behaviors.
Regards,
Branden
Attachment:
man-table-demo.man
Description: Unix manual page
Attachment:
signature.asc
Description: PGP signature
