* Re: text wrapping in Bl -column
2017-06-28 22:01 text wrapping in Bl -column Yuri Pankov
@ 2017-06-29 15:40 ` Ingo Schwarze
0 siblings, 0 replies; 2+ messages in thread
From: Ingo Schwarze @ 2017-06-29 15:40 UTC (permalink / raw)
To: Yuri Pankov; +Cc: discuss
Hi Yuri,
Yuri Pankov wrote on Thu, Jun 29, 2017 at 01:01:44AM +0300:
> I'm trying to replace a table with "Bl -column",
In general, that is a good idea, as .Bl -column is less fragile
than tbl(7). If possible, reorganize the information in a way
such that .Bl -column is sufficient to nicely present it.
Given that tbl(7) has several features that .Bl -column does not
provide, there may be exceptional cases where the result of the
replacement is not satisfactory and tbl(7) is the best solution
available - even though it may cause grief: For example, in portable
manuals, misformatting on misconfigured systems that don't provide
tbl(1) or don't properly call it in the roff pipeline, or trouble
when trying to convert mdoc(7) containing tbl(7) to man(7) with
mandoc -Tman.
Typical examples where tbl(7) may, all the same, be adequate are
when boxes and separating lines, horizontal spans, or horizontal
alignment of data within cells are crucial for making the table
understandable.
> and have a problem with text not being wrapped at the column length
> (example below). Am I missing something here, or is that just how
> the "Bl -column" works?
Exactly, .Bl -column *never* wraps text inside columns at all.
The tbl(7) implementation in mandoc(1) supports wrapping text
inside columns since June 12, 2017 (two weeks ago), and that new
feature will be contained in mandoc 1.14.2. But again, if you
can rearrange the information to nicely present it without tbl(7),
that is likely preferable, for the reasons stated above.
In addition to that, i did not include "wrapping inside columns"
in the list of plausible reasons for using tbl(7) because the result
often looks ugly because columns tend to get narrow, and there are
often better ways to present the information, for example using
tagged lists instead of tables. The vast majority of real-world
manuals using wrapping inside columns look very ugly - but if used
with great care, using the feature might occasionally be acceptable,
even though i still wouldn't recommend it.
> BTW, the following sentence in mdoc(7) doesn't seem to be correct,
> at least I'm seeing that it works in example below:
The mandoc(1) implementation of mdoc(7) is very lenient and produces
intelligible formatting for many kinds of input, even for some that
misformat with groff.
> "Ta is only recognised as a macro when called by other macros,
> not as the first macro on a line."
Admittedly, that was misleading. While mandoc(1) copes with .Ta
as a line macro, groff(1) misbehaves in that case. So i changed
the text to read as follows:
The tab cell delimiter may only be used within the It line
itself; on following lines, only the Ta macro can be used to
delimit cells, and portability requires that Ta is called by
other macros: some parsers do not recognize it when it appears
as the first macro on a line.
See the first commit below.
> .Dd June 29, 2017
> .Dt TEST 1
> .Os
> .Sh NAME
> .Nm test
> .Nd test
> .Sh DESCRIPTION
> .Bl -column "widthforthecolumn" "widthforthecolumn" "widthforthecolumn"
> .It MESSAGE Ta DESCRIPTION Ta NOTES
> .It
> Some text for the first column that should be wrapped
> .Ta
> Some text for the second column that should be wrapped
> .Ta
> Some text for the third column that should be wrapped
> .El
>
> renders as (mandoc 1.14.1 with -Owidth=72):
>
> TEST(1) User Commands TEST(1)
>
> NAME
> test b
>
> DESCRIPTION
> MESSAGE DESCRIPTION NOTES
> Some text for the first column that should be wrapped
> Some text for the second column that should be
> wrapped Some text for the third
> column that should be
> wrapped
>
> illumos June 29, 2017 illumos
Not what you intended, but almost readable...
Try rendering that with
groff -mdoc -Tascii -P -c tmp | less
At least with the latest groff release (1.22.3), that puts all the
text to the extreme right, beyond the third column.
To warn people that two of the idioms in your example are not
portable, mandoc -Tlint now warns as follows, see the second
commit below:
mandoc: tmp:12:2: WARNING: first macro on line: Ta
mandoc: tmp:14:2: WARNING: first macro on line: Ta
mandoc: tmp:10:2: WARNING: missing argument, using next line: Bl -column It
Log Message:
-----------
Clarify that .Ta as a line macro is a portability problem,
even though mandoc(1) handles it;
triggered by a question from Yuri Pankov (illumos).
Modified Files:
--------------
mandoc:
mdoc.7
Revision Data
-------------
Index: mdoc.7
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mdoc.7,v
retrieving revision 1.266
retrieving revision 1.267
diff -Lmdoc.7 -Lmdoc.7 -u -p -r1.266 -r1.267
--- mdoc.7
+++ mdoc.7
@@ -1850,10 +1850,10 @@ The tab cell delimiter may only be used
.Sx \&It
line itself; on following lines, only the
.Sx \&Ta
-macro can be used to delimit cells, and
+macro can be used to delimit cells, and portability requires that
.Sx \&Ta
-is only recognised as a macro when called by other macros,
-not as the first macro on a line.
+is called by other macros: some parsers do not recognize it when
+it appears as the first macro on a line.
.Pp
Note that quoted strings may span tab-delimited cells on an
.Sx \&It
Log Message:
-----------
warn about some non-portable idioms in .Bl -column;
triggered by a question from Yuri Pankov (illumos)
Modified Files:
--------------
mandoc:
mandoc.1
mandoc.h
mdoc_validate.c
read.c
mandoc/regress/mdoc/Bl:
Makefile
column.in
column.out_lint
Added Files:
-----------
mandoc/regress/mdoc/Bl:
column_nogroff.in
column_nogroff.out_ascii
column_nogroff.out_lint
column_nogroff.out_markdown
Revision Data
-------------
Index: read.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/read.c,v
retrieving revision 1.182
retrieving revision 1.183
diff -Lread.c -Lread.c -u -p -r1.182 -r1.183
--- read.c
+++ read.c
@@ -151,6 +151,7 @@ static const char * const mandocerrs[MAN
"blocks badly nested",
"nested displays are not portable",
"moving content out of list",
+ "first macro on line",
"fill mode already enabled, skipping",
"fill mode already disabled, skipping",
"line scope broken",
@@ -169,6 +170,7 @@ static const char * const mandocerrs[MAN
"missing function name, using \"\"",
"empty head in list item",
"empty list item",
+ "missing argument, using next line",
"missing font type, using \\fR",
"unknown font type, using \\fR",
"nothing follows prefix",
Index: mandoc.1
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mandoc.1,v
retrieving revision 1.208
retrieving revision 1.209
diff -Lmandoc.1 -Lmandoc.1 -u -p -r1.208 -r1.209
--- mandoc.1
+++ mandoc.1
@@ -1218,6 +1218,12 @@ list block contains text or macros befor
.Ic \&It
macro.
The offending children are moved before the beginning of the list.
+.It Sy "first macro on line"
+Inside a
+.Ic \&Bl Fl column
+list, a
+.Ic \&Ta
+macro occurs as the first macro on a line, which is not portable.
.It Sy "fill mode already enabled, skipping"
.Pq man
A
@@ -1363,6 +1369,17 @@ list, an
.Ic \&It
block is empty.
An empty list item is shown.
+.It Sy "missing argument, using next line"
+.Pq mdoc
+An
+.Ic \&It
+macro in a
+.Ic \&Bd Fl column
+list has no arguments.
+While
+.Nm
+uses the text or macros of the following line, if any, for the cell,
+other formatters may misformat the list.
.It Sy "missing font type, using \efR"
.Pq mdoc
A
Index: mdoc_validate.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mdoc_validate.c,v
retrieving revision 1.344
retrieving revision 1.345
diff -Lmdoc_validate.c -Lmdoc_validate.c -u -p -r1.344 -r1.345
--- mdoc_validate.c
+++ mdoc_validate.c
@@ -1460,15 +1460,30 @@ post_it(POST_ARGS)
assert(nit->head->child == NULL);
- i = 0;
- for (nch = nit->child; nch != NULL; nch = nch->next)
- if (nch->type == ROFFT_BODY)
- i++;
+ if (nit->head->next->child == NULL &&
+ nit->head->next->next == NULL) {
+ mandoc_msg(MANDOCERR_MACRO_EMPTY, mdoc->parse,
+ nit->line, nit->pos, "It");
+ roff_node_delete(mdoc, nit);
+ break;
+ }
+ i = 0;
+ for (nch = nit->child; nch != NULL; nch = nch->next) {
+ if (nch->type != ROFFT_BODY)
+ continue;
+ if (i++ && nch->flags & NODE_LINE)
+ mandoc_msg(MANDOCERR_TA_LINE, mdoc->parse,
+ nch->line, nch->pos, "Ta");
+ }
if (i < cols || i > cols + 1)
mandoc_vmsg(MANDOCERR_BL_COL,
mdoc->parse, nit->line, nit->pos,
"%d columns, %d cells", cols, i);
+ else if (nit->head->next->child != NULL &&
+ nit->head->next->child->line > nit->line)
+ mandoc_msg(MANDOCERR_IT_NOARG, mdoc->parse,
+ nit->line, nit->pos, "Bl -column It");
break;
default:
abort();
Index: mandoc.h
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mandoc.h,v
retrieving revision 1.236
retrieving revision 1.237
diff -Lmandoc.h -Lmandoc.h -u -p -r1.236 -r1.237
--- mandoc.h
+++ mandoc.h
@@ -109,6 +109,7 @@ enum mandocerr {
MANDOCERR_BLK_NEST, /* blocks badly nested: macro ... */
MANDOCERR_BD_NEST, /* nested displays are not portable: macro ... */
MANDOCERR_BL_MOVE, /* moving content out of list: macro */
+ MANDOCERR_TA_LINE, /* first macro on line: Ta */
MANDOCERR_FI_SKIP, /* fill mode already enabled, skipping: fi */
MANDOCERR_NF_SKIP, /* fill mode already disabled, skipping: nf */
MANDOCERR_BLK_LINE, /* line scope broken: macro breaks macro */
@@ -127,6 +128,7 @@ enum mandocerr {
MANDOCERR_FO_NOHEAD, /* missing function name, using "": Fo */
MANDOCERR_IT_NOHEAD, /* empty head in list item: Bl -type It */
MANDOCERR_IT_NOBODY, /* empty list item: Bl -type It */
+ MANDOCERR_IT_NOARG, /* missing argument, using next line: Bl -c It */
MANDOCERR_BF_NOFONT, /* missing font type, using \fR: Bf */
MANDOCERR_BF_BADFONT, /* unknown font type, using \fR: Bf font */
MANDOCERR_PF_SKIP, /* nothing follows prefix: Pf arg */
--- /dev/null
+++ regress/mdoc/Bl/column_nogroff.in
@@ -0,0 +1,19 @@
+.Dd June 29, 2017
+.Dt BL-COLUMN_NOGROFF 1
+.Os OpenBSD
+.Sh NAME
+.Nm Bl-column_nogroff
+.Nd column lists mishandled by groff
+.Sh DESCRIPTION
+Item macro without arguments:
+.Bl -column "first column" "second column"
+.It
+text
+.No macro Ta after tab
+.El
+.Pp
+Tab macro at the beginning of a line:
+.Bl -column "aa" "bb"
+.It aa
+.Ta bb
+.El
--- /dev/null
+++ regress/mdoc/Bl/column_nogroff.out_ascii
@@ -0,0 +1,15 @@
+BL-COLUMN_NOGROFF(1) General Commands Manual BL-COLUMN_NOGROFF(1)
+
+N\bNA\bAM\bME\bE
+ B\bBl\bl-\b-c\bco\bol\blu\bum\bmn\bn_\b_n\bno\bog\bgr\bro\bof\bff\bf - column lists mishandled by groff
+
+D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
+ Item macro without arguments:
+
+ text macro after tab
+
+ Tab macro at the beginning of a line:
+
+ aa bb
+
+OpenBSD June 29, 2017 OpenBSD
Index: column.in
===================================================================
RCS file: /home/cvs/mandoc/mandoc/regress/mdoc/Bl/column.in,v
retrieving revision 1.1
retrieving revision 1.2
diff -Lregress/mdoc/Bl/column.in -Lregress/mdoc/Bl/column.in -u -p -r1.1 -r1.2
--- regress/mdoc/Bl/column.in
+++ regress/mdoc/Bl/column.in
@@ -68,11 +68,14 @@
.El
.\" Wrong number of columns.
.Bl -column "a" "b"
+.It
.It "a"
.It "a" Ta "b"
+.It
.It "a" Ta "b" Ta "c"
.It "a" Ta "b" Ta "c" Ta "d"
.It "a" Ta "b" Ta "c" Ta "d" Ta "e"
+.It
.El
.\" Mixed tab and Ta
.Bl -column a b c d
--- /dev/null
+++ regress/mdoc/Bl/column_nogroff.out_lint
@@ -0,0 +1,5 @@
+mandoc: column_nogroff.in:3:5: BASE: operating system explicitly specified: Os OpenBSD (OpenBSD)
+mandoc: column_nogroff.in:1:5: BASE: Mdocdate missing: Dd June (OpenBSD)
+mandoc: column_nogroff.in:10:2: WARNING: missing argument, using next line: Bl -column It
+mandoc: column_nogroff.in:18:2: WARNING: first macro on line: Ta
+mandoc: column_nogroff.in: BASE: RCS id missing: (OpenBSD)
--- /dev/null
+++ regress/mdoc/Bl/column_nogroff.out_markdown
@@ -0,0 +1,18 @@
+BL-COLUMN\_NOGROFF(1) - General Commands Manual
+
+# NAME
+
+**Bl-column\_nogroff** - column lists mishandled by groff
+
+# DESCRIPTION
+
+Item macro without arguments:
+
+ text
+ macro after tab
+
+Tab macro at the beginning of a line:
+
+ aa bb
+
+OpenBSD - June 29, 2017
Index: column.out_lint
===================================================================
RCS file: /home/cvs/mandoc/mandoc/regress/mdoc/Bl/column.out_lint,v
retrieving revision 1.4
retrieving revision 1.5
diff -Lregress/mdoc/Bl/column.out_lint -Lregress/mdoc/Bl/column.out_lint -u -p -r1.4 -r1.5
--- regress/mdoc/Bl/column.out_lint
+++ regress/mdoc/Bl/column.out_lint
@@ -1,7 +1,10 @@
mandoc: column.in:3:5: BASE: operating system explicitly specified: Os OpenBSD (OpenBSD)
mandoc: column.in:1:5: BASE: Mdocdate missing: Dd October (OpenBSD)
-mandoc: column.in:71:2: WARNING: wrong number of cells: 2 columns, 1 cells
-mandoc: column.in:74:2: WARNING: wrong number of cells: 2 columns, 4 cells
-mandoc: column.in:75:2: WARNING: wrong number of cells: 2 columns, 5 cells
-mandoc: column.in:103:18: WARNING: skipping -width argument: Bl -column
+mandoc: column.in:71:2: WARNING: skipping empty macro: It
+mandoc: column.in:72:2: WARNING: wrong number of cells: 2 columns, 1 cells
+mandoc: column.in:74:2: WARNING: skipping empty macro: It
+mandoc: column.in:76:2: WARNING: wrong number of cells: 2 columns, 4 cells
+mandoc: column.in:77:2: WARNING: wrong number of cells: 2 columns, 5 cells
+mandoc: column.in:78:2: WARNING: skipping empty macro: It
+mandoc: column.in:106:18: WARNING: skipping -width argument: Bl -column
mandoc: column.in: BASE: RCS id missing: (OpenBSD)
Index: Makefile
===================================================================
RCS file: /home/cvs/mandoc/mandoc/regress/mdoc/Bl/Makefile,v
retrieving revision 1.7
retrieving revision 1.8
diff -Lregress/mdoc/Bl/Makefile -Lregress/mdoc/Bl/Makefile -u -p -r1.7 -r1.8
--- regress/mdoc/Bl/Makefile
+++ regress/mdoc/Bl/Makefile
@@ -1,7 +1,8 @@
# $OpenBSD: Makefile,v 1.31 2016/10/17 19:00:16 schwarze Exp $
REGRESS_TARGETS = item inset diag ohang bullet dash enum hang tag
-REGRESS_TARGETS += column colNoIt extend nested offset secstart
+REGRESS_TARGETS += column column_nogroff colNoIt
+REGRESS_TARGETS += extend nested offset secstart
REGRESS_TARGETS += notype multitype badargs
REGRESS_TARGETS += empty noIt emptyhead emptytag emptyitem multitag
@@ -9,7 +10,7 @@ REGRESS_TARGETS += bareIt bareTa unclose
UTF8_TARGETS = dash
-LINT_TARGETS = column notype badargs tag
+LINT_TARGETS = column column_nogroff notype badargs tag
LINT_TARGETS += empty noIt emptyhead emptytag emptyitem
LINT_TARGETS += bareIt bareTa break breakingIt broken
@@ -19,6 +20,8 @@ LINT_TARGETS += bareIt bareTa break brea
SKIP_GROFF ?= breakingTa
# groff-1.22.3 defects:
+# - column list items with no args but multiple lines cause bogus breaks
+# - in column lists, the tab macro cannot be a line macro
# - lists with missing or late type ruin indentation
# - empty lists ruin indentation and sometimes cause empty lines
# - breaking lists continue indefinitely
@@ -26,7 +29,7 @@ SKIP_GROFF ?= breakingTa
# - breaking a list aborts processing
# - empty -tag item heads lose the blank line and the indentation
-SKIP_GROFF += notype empty break breakingIt broken emptytag
+SKIP_GROFF += column_nogroff notype empty emptytag break breakingIt broken
SKIP_TMAN ?= column colNoIt multitype multitag bareTa break breakingTa broken
@@ -38,7 +41,7 @@ SKIP_TMAN += tag
# Empty heads are still mishandled by -Tman.
-SKIP_TMAN += emptyhead emptytag
+SKIP_TMAN += column_nogroff emptyhead emptytag
# mandoc -T markdown still has issues with badly nested lists
--
To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv
^ permalink raw reply [flat|nested] 2+ messages in thread