discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: Yuri Pankov <yuripv@gmx.com>
Cc: discuss@mandoc.bsd.lv
Subject: Re: text wrapping in Bl -column
Date: Thu, 29 Jun 2017 17:40:46 +0200	[thread overview]
Message-ID: <20170629154046.GA5328@athene.usta.de> (raw)
In-Reply-To: <fe0ede47-453d-37cb-0f4d-ee15aa24c412@gmx.com>

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

      reply	other threads:[~2017-06-29 15:40 UTC|newest]

Thread overview: 2+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-06-28 22:01 Yuri Pankov
2017-06-29 15:40 ` Ingo Schwarze [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20170629154046.GA5328@athene.usta.de \
    --to=schwarze@usta.de \
    --cc=discuss@mandoc.bsd.lv \
    --cc=yuripv@gmx.com \
    --subject='Re: text wrapping in Bl -column' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).