adjustment of text blocks in tables (was: long nroff tables)

[G. Branden Robinson]

Hi Bjarni,

You've changed the subject, so please change the Subject: when doing so.

At 2021-01-21T03:24:38+0000, Bjarni Ingi Gislason wrote:
>   Concerning the warning "cannot adjust line".
> 
>   It is caused by "troff" meddling with the line adjustment in at least
> text block columns ( T{...T} ).

I disagree with this characterization.  troff is not "meddling" with
anything at all.  It's adjusting the text in the table as it was outside
the table.

>   Happens when the adjustment mode is 'b' (adjust to both margins),
> which is the default mode.

Yes.  Text blocks are TEXT, so they get adjusted just like the TEXT that
preceded the table.

>   Temporary workaround is to put '.ad l' in front of the table,
> and restore the adjustment mode after the table,
> if needed.

That is one remedy, but not appropriate for man(7) and mdoc(7), within
which you should not be using low-level requests--at least not _outside_
the table region.  What non-roff man page renderers should be prepared
to accept within tbl regions is something of an open question[1].

Another remedy is to disable adjustment on a per-text-block basis, e.g.,

T{
.na
This is my text, which will have a ragged right margin if it's long
enough.
There is no need to restore adjustment with .ad.
T}

>   A permanent solution is to add '.na' (no line adjustment) to the
> '.TS' macro (bug #59798) and

I have rejected this patch for the reasons documented in the bug.

https://savannah.gnu.org/bugs/index.php?59798

> '.ad' (restore line adjustment) to the '.TE' macro (bug #59795).

I think you're wrong about this one, too, which changes the semantics of
the .ad request to differ from Heirloom Doctools troff.

I have invited further comment instead of closing it, however, and I
renew that call.

https://savannah.gnu.org/bugs/index.php?59795

Yet another solution to the text block adjustment issue might be use of
the "m" column specifier, which calls a macro on text blocks.  I haven't
tried it though, and it is a GNU extension.

The matter is inadequately documented, however.  Perhaps it always has
been.  Even the original tbl paper by Lesk doesn't satisfy me in this
regard.  Our own man page carelessly uses the word "adjustment" to refer
to what tbl does with cell contents, which is to _align_ them (to the
left, right, or center of the cell; to a decimal point; and so on).

I have an update to tbl(1) that I have not yet pushed.  I was going to
wait until I got at least one of Dorai's contributions integrated, but I
have 9 commits piled up and I guess I should just go ahead and get them
out.

commit 0a1eeea06a90f65657bcb2a0847ac2a6271be7aa
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Tue Jan 19 16:14:03 2021 +1100

    tbl(1): Update documentation of text blocks.
    
    src/preproc/tbl/tbl.1.man (Description/Overview/Table format
    specification): Tighten wording and stop referring to the alignment of
    the table cell contents as "adjustment" which only provokes confusion.
    (Description/Text blocks): Recast to be much clearer about how
    adjustment of text blocks persists from the foregoing document state.
    
    Prompted by <https://savannah.gnu.org/bugs/?59798>.

diff --git a/src/preproc/tbl/tbl.1.man b/src/preproc/tbl/tbl.1.man
index ea78c8e1..c0952dbf 100644
--- a/src/preproc/tbl/tbl.1.man
+++ b/src/preproc/tbl/tbl.1.man
@@ -10,7 +10,7 @@
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 1989-2020 Free Software Foundation, Inc.
+.\" Copyright (C) 1989-2021 Free Software Foundation, Inc.
 .\"
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
@@ -125,14 +125,18 @@ must always be finished by a
 .TP
 .I Table format specification
 .
-This part must be given, it is not optional.
+The table format specification is mandatory;
+it determines the number of columns in the table.
 .
-It determines the number of columns (cells) of the table.
+Each cell in a column is classified by being
+centered,
+left-aligned,
+numeric
+(aligned to a decimal point),
+and so on.
 .
-Moreover each cell is classified by being central, left adjusted, or
-numerical, etc.
-.
-This specification can have several lines, but must be finished by a
+This specification can have several lines,
+but must be finished by a
 .B dot .
 at the end of the last line.
 .
@@ -142,10 +146,9 @@ but that's optional.
 .
 .
 .P
-Cells are separated by a tab character by default.
+Cells in table data are separated by a tab character by default.
 .
-That can be changed by the
-.I global option
+That can be changed by the global option
 .BI tab( c )\c
 ,
 where
@@ -880,42 +883,73 @@ field immediately above spans downward over this row.
 A text block can be used to enter data as a single entry which would
 be too long as a simple string between tabs.
 .
-It is started with \[oq]T{\[cq] and closed with \[oq]T}\[cq].
+It is started with
+.RB \[lq] T{ \[rq]
+at the end of a line
+and finished with
+.RB \[lq] T} \[rq]
+at the start of a line.
 .
-The former must end a line, and the latter must start a line, probably
-followed by other data columns (separated with tabs or the character
-given with the
-.B tab
-global option).
+Further column data can follow the end of a text block on the same line.
 .
 .
 .LP
-By default, the text block is formatted with the settings which were
-active before entering the table, possibly overridden by the
-.BR m ,
-.BR v ,
+Text blocks are formatted as was the text prior to the table,
+modified as applicable by column specifiers.
+.
+Specifically,
+the key characters
+.RB \[lq] a \[rq],
+.RB \[lq] c \[rq],
+.RB \[lq] l \[rq],
+.RB \[lq] n \[rq],
 and
-.B w
-tbl specifiers.
+.RB \[lq] s \[rq]
+determine a text block's
+.I alignment
+within its cell,
+but not its
+.IR adjustment .
+.
+You can add an
+.B .na
+or
+.B .ad
+request to the beginning of a text block to alter its adjustment
+distinctly from other text in the document.
 .
 .
 .LP
-If either \[oq]w\[cq] or \[oq]x\[cq] specifiers are not given for
+If
+.RB \[lq] w \[rq]
+or
+.RB \[lq] x \[rq]
+column specifiers are not given for
 .I all
-columns of a text block span, the default length of the text block (to
-be more precise, the line length used to process the text block
-diversion) is computed as L\[tmu]C/(N+1), where \[oq]L\[cq] is the
-current line length, \[oq]C\[cq] the number of columns spanned by the
-text block, and \[oq]N\[cq] the total number of columns in the table.
-.
-Note, however, that the actual diversion width as returned in register
-.B \[rs]n[dl]
-is used eventually as the text block width.
-.
-If necessary, you can also control the text block width with a direct
-insertion of a
+columns of a text block span,
+the default length of the text block
+(to be more precise,
+the line length used to process the text block diversion)
+is computed as
+.IR L \[tmu] C /( N +1),
+where
+.I L
+is the current line length,
+.I C
+the number of columns spanned by the text block,
+and
+.I N
+the total number of columns in the table.
+.
+If necessary,
+you can also control the text block width by inserting an
 .B .ll
-request right after \[oq]T{\[cq].
+request right after
+.RB \[lq] T{ \[rq].
+.
+Because a diversion is used to format the text block,
+its width is subsequently available in the register
+.B \[rs]n[dl] .
 .
 .
 .\" ====================================================================

Regards,
Branden

[1] It would be really nice if tbl(1) could output HTML itself.  That
would render groff_hdbtl(7) unnecessary and enable us to kill off the
rather horrible hack that the groff HTML output driver uses for tables,
which is to render them to PostScript, convert that to an image, and
then inline the image.  This is horrible because the table contents
become not-text and stop being searchable page content.

signature.asc
Description: PGP signature