From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-02.scc.kit.edu (scc-mailout-kit-02.scc.kit.edu [129.13.231.82]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 7561fbb3 for ; Thu, 29 Jun 2017 10:40:50 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1dQbYl-00072P-Mg; Thu, 29 Jun 2017 17:40:49 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1dQbYl-0001jj-18; Thu, 29 Jun 2017 17:40:47 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1dQbYk-0005YT-Hm; Thu, 29 Jun 2017 17:40:46 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 29e19133; Thu, 29 Jun 2017 17:40:46 +0200 (CEST) Date: Thu, 29 Jun 2017 17:40:46 +0200 From: Ingo Schwarze To: Yuri Pankov Cc: discuss@mandoc.bsd.lv Subject: Re: text wrapping in Bl -column Message-ID: <20170629154046.GA5328@athene.usta.de> References: X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable In-Reply-To: User-Agent: Mutt/1.6.2 (2016-07-01) 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 >=20 > renders as (mandoc 1.14.1 with -Owidth=3D72): >=20 > TEST(1) User Commands TEST(1) >=20 > NAME > test b >=20 > 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 >=20 > 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;=20 triggered by a question from Yuri Pankov (illumos). Modified Files: -------------- mandoc: mdoc.7 Revision Data ------------- Index: mdoc.7 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 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=20 .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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 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) =20 assert(nit->head->child =3D=3D NULL); =20 - i =3D 0; - for (nch =3D nit->child; nch !=3D NULL; nch =3D nch->next) - if (nch->type =3D=3D ROFFT_BODY) - i++; + if (nit->head->next->child =3D=3D NULL && + nit->head->next->next =3D=3D NULL) { + mandoc_msg(MANDOCERR_MACRO_EMPTY, mdoc->parse, + nit->line, nit->pos, "It"); + roff_node_delete(mdoc, nit); + break; + } =20 + i =3D 0; + for (nch =3D nit->child; nch !=3D NULL; nch =3D nch->next) { + if (nch->type !=3D 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 !=3D 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 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_NOGROF= F(1) + +N=08NA=08AM=08ME=08E + B=08Bl=08l-=08-c=08co=08ol=08lu=08um=08mn=08n_=08_n=08no=08og=08gr=08= ro=08of=08ff=08f - column lists mishandled by groff + +D=08DE=08ES=08SC=08CR=08RI=08IP=08PT=08TI=08IO=08ON=08N + Item macro without arguments: + + text macro after tab + + Tab macro at the beginning of a line: + + aa bb + +OpenBSD June 29, 2017 Ope= nBSD Index: column.in =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 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 -r= 1.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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 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 Ope= nBSD (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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 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 $ =20 REGRESS_TARGETS =3D item inset diag ohang bullet dash enum hang tag -REGRESS_TARGETS +=3D column colNoIt extend nested offset secstart +REGRESS_TARGETS +=3D column column_nogroff colNoIt +REGRESS_TARGETS +=3D extend nested offset secstart =20 REGRESS_TARGETS +=3D notype multitype badargs REGRESS_TARGETS +=3D empty noIt emptyhead emptytag emptyitem multitag @@ -9,7 +10,7 @@ REGRESS_TARGETS +=3D bareIt bareTa unclose =20 UTF8_TARGETS =3D dash =20 -LINT_TARGETS =3D column notype badargs tag +LINT_TARGETS =3D column column_nogroff notype badargs tag LINT_TARGETS +=3D empty noIt emptyhead emptytag emptyitem LINT_TARGETS +=3D bareIt bareTa break breakingIt broken =20 @@ -19,6 +20,8 @@ LINT_TARGETS +=3D bareIt bareTa break brea SKIP_GROFF ?=3D breakingTa =20 # 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 ?=3D breakingTa # - breaking a list aborts processing # - empty -tag item heads lose the blank line and the indentation =20 -SKIP_GROFF +=3D notype empty break breakingIt broken emptytag +SKIP_GROFF +=3D column_nogroff notype empty emptytag break breakingIt brok= en =20 SKIP_TMAN ?=3D column colNoIt multitype multitag bareTa break breakingTa b= roken =20 @@ -38,7 +41,7 @@ SKIP_TMAN +=3D tag =20 # Empty heads are still mishandled by -Tman. =20 -SKIP_TMAN +=3D emptyhead emptytag +SKIP_TMAN +=3D column_nogroff emptyhead emptytag =20 # mandoc -T markdown still has issues with badly nested lists =20 -- To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv