Hi Michael!
At 2021-02-02T14:14:33+0100, Michael Kerrisk (man-pages) wrote:
> Hello Branden,
>
> {I've also seen you reply to this mail.]
Cool. Sorry for the delay in replying; I was hopeful that we'd get
groff 1.23.0, or at least a release candidate, into Debian bullseye but
that is looking less likely. Ah well.
> I think I'm okay with everything you say in this patch/mail, but I
> have one concern
[my own stuff snipped]
> So, I understand much better now. I guess my one concern is that
> sometimes there are tables with a lot of T{ / T} blocks.
Yes. Since you last wrote I encountered and dealt with just such a
page, groff_ms(7), and I think it reveals how poorly understood (and
likely, to date, how poorly documented) tbl(1) text blocks really are.
I was able to kill off nearly every instance of T{/T} in the groff_ms(7)
page[1] because it simply wasn't necessary in most cases[2].
There may be more esoteric uses, but from what I've seen in man pages,
you need tbl text blocks in exactly one scenario: when you require a
line break in a table cell. You might not care exactly where it
happens (use the .br request if you do), but you know you're going to
need it.
Therefore, if you know your table row is going to fit in the available
space without breaking (78 columns in nroff mode for the Linux man pages
project), you don't need to mess with text blocks. You already know
this, but for the benefit of the wider audience, a good first resort
before reaching for text blocks is, if possible, to have one table
column which is expected to be the widest, and give its column
specification the "x" modifier. This GNU tbl extension tells tbl to
expand the table width to the full available line length and give all
the slack space to the designated column.
Here's a real-world example.
.LP
.TS
cb s s s
cb cb cb cb
lfCR lx l lfCR.
Margin settings
Parameter Definition Effective Default
_
\[rs]n[PO] Page offset (left margin) next page 1i
\[rs]n[LL] Line length next paragraph 6i
\[rs]n[LT] Header/footer length next paragraph 6i
\[rs]n[HM] Top (header) margin next page 1i
\[rs]n[FM] Bottom (footer) margin next page 1i
_
.TE
In the above, the "Definition" column will expand to fill all available
space on the line. (If you're cutting and pasting, you'll need to
sed 's/ \+/\\t/g' the rows of table data.)
Admittedly, this strategy will fail if you want your document's layout
to be _completely_ independent of the line length. On the bright side,
you will get warnings when rendering your document if the table grows
too wide to fit the line length of the output device.
In practice, I think the authors of most practical documents have a
minimum line length they are prepared to support.
> What you are saying is that I'd need to add .na and/or .nh in each
> such block. That's kind of burdensome. (In practice, maybe it is not
> as bad as I think, since a quick grep suggests that there are less 50
> such pages.)
I hope the above observation brings that count down some. If it were
me, I'd probably sed-automate the conversion away from text blocks[3],
render all the altered pages, and let the pages themselves tell me when
the lines overran.
Here's an example of such a change, to clone(2), just as a specimen.
diff --git a/man2/clone.2 b/man2/clone.2
index 11eb6c622..f4af93549 100644
--- a/man2/clone.2
+++ b/man2/clone.2
@@ -257,9 +257,7 @@ l l l
li li l.
clone() clone3() Notes
\fIcl_args\fP field
-flags & \(ti0xff flags T{
-For most flags; details below
-T}
+flags & \(ti0xff flags For most flags; details below
parent_tid pidfd See CLONE_PIDFD
child_tid child_tid See CLONE_CHILD_SETTID
parent_tid parent_tid See CLONE_PARENT_SETTID
> What would be nice is a way of saying in the table preamble
> that a particular column should not be hyphenated or should be
> left adjusted. Is there a way to do that? I'm aware of the tbl(1)
> 'm' modifier:
>
> m,M This is a GNU tbl extension. Either of these specifiers
> may be followed by a macro name (either one or two charac‐
> ters long), or long name in parentheses. A one-letter
> macro name must be separated by one or more blanks from
> whatever follows. The macro which name can be specified
> here must be defined before creating the table. It is
> called just before the table's cell text is output. As im‐
> plemented currently, this macro is only called if block in‐
> put is used, that is, text between ‘T{’ and ‘T}’. The
> macro should contain only simple troff requests to change
> the text block formatting, like text adjustment, hyphena‐
> tion, size, or font. The macro is called after other cell
> modifications like b, f or v are output. Thus the macro
> can overwrite other modification specifiers.
>
> But that seems to be usable for only one macro. In other words,
> doing something like
>
> lmnhmna
>
> to disable hyphenation and adjustment in the T{ / T} blocks in a
> particular column of a table doesn't work. More precisely, if
> there's a series of 'm' requests attached to a column in the
> table preamble, it looks like only the last one is honored.
You're right. It had never occurred to me to give the "m" modifier the
name of a _request_ for the "macro" before, but doing so is perfectly
consistent with *roff design principles since Ossanna first wrote nroff.
To answer your question, I'm not aware of a way, no--and what's worse,
not only is "m" yet another GNU extension[4], but one remedy you suggest
requires the definition of a page-private macro, which makes life
difficult for maintainers of non-roff man page interpreters.
The other remedy, extending the "m" modifier to build a queue of macros
(or requests) to call when processing a text block in the corresponding
column is an interesting idea. It'll probably be up to me to implement
it if it proves necessary.
As a minor point, since "m" is a GNU extension already, I think if you
used this approach, it would be more readable to use the GNU tbl
long-name syntax for the macro name. So instead of:
lmnhmna
you could:
lm(nh)m(na)
...but again, at present, _multiple_ "m" modifier specifications will
not work; only the last one will be honored.
Regards,
Branden
[1] https://git.savannah.gnu.org/cgit/groff.git/commit/?id=cd5e94235339edaa0af44f2c3b0bcf1dee1f841f
[2] I killed off 11; 2 remain. Even those two may not be necessary, but
revising that part of the page was outside the scope of the work I
was doing at the time.
[3] Since this would, I think, involve using the hold space, it could be
a fun exercise.
[4] As noted earlier in the thread, while "x" is a GNU extension, the
Heirloom Doctools troff developers considered it appealing enough to
document support for it, even if in the Heirloom tbl version that I
use for testing, that support doesn't work.
Attachment:
signature.asc
Description: PGP signature
