From 294cf32a27d430922b8f008f10b766ddce477cf6 Mon Sep 17 00:00:00 2001 From: Ingo Schwarze Date: Thu, 29 Jun 2017 15:22:17 +0000 Subject: [PATCH] warn about some non-portable idioms in .Bl -column; triggered by a question from Yuri Pankov (illumos) --- mandoc.1 | 21 +++++++++++++++-- mandoc.h | 4 +++- mdoc_validate.c | 25 ++++++++++++++++----- read.c | 4 +++- regress/mdoc/Bl/Makefile | 11 +++++---- regress/mdoc/Bl/column.in | 3 +++ regress/mdoc/Bl/column.out_lint | 11 +++++---- regress/mdoc/Bl/column_nogroff.in | 19 ++++++++++++++++ regress/mdoc/Bl/column_nogroff.out_ascii | 15 +++++++++++++ regress/mdoc/Bl/column_nogroff.out_lint | 5 +++++ regress/mdoc/Bl/column_nogroff.out_markdown | 18 +++++++++++++++ 11 files changed, 119 insertions(+), 17 deletions(-) create mode 100644 regress/mdoc/Bl/column_nogroff.in create mode 100644 regress/mdoc/Bl/column_nogroff.out_ascii create mode 100644 regress/mdoc/Bl/column_nogroff.out_lint create mode 100644 regress/mdoc/Bl/column_nogroff.out_markdown diff --git a/mandoc.1 b/mandoc.1 index 7ac89ed9..5d59ba4f 100644 --- a/mandoc.1 +++ b/mandoc.1 @@ -1,4 +1,4 @@ -.\" $Id: mandoc.1,v 1.208 2017/06/27 12:18:00 schwarze Exp $ +.\" $Id: mandoc.1,v 1.209 2017/06/29 15:22:17 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons .\" Copyright (c) 2012, 2014-2017 Ingo Schwarze @@ -15,7 +15,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: June 27 2017 $ +.Dd $Mdocdate: June 29 2017 $ .Dt MANDOC 1 .Os .Sh NAME @@ -1218,6 +1218,12 @@ list block contains text or macros before the first .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 diff --git a/mandoc.h b/mandoc.h index 8e7ddf44..94a5f2fb 100644 --- a/mandoc.h +++ b/mandoc.h @@ -1,4 +1,4 @@ -/* $Id: mandoc.h,v 1.236 2017/06/25 17:43:45 schwarze Exp $ */ +/* $Id: mandoc.h,v 1.237 2017/06/29 15:22:17 schwarze Exp $ */ /* * Copyright (c) 2010, 2011, 2014 Kristaps Dzonsons * Copyright (c) 2010-2017 Ingo Schwarze @@ -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 */ diff --git a/mdoc_validate.c b/mdoc_validate.c index a7d91ec0..73493155 100644 --- a/mdoc_validate.c +++ b/mdoc_validate.c @@ -1,4 +1,4 @@ -/* $Id: mdoc_validate.c,v 1.344 2017/06/27 12:18:00 schwarze Exp $ */ +/* $Id: mdoc_validate.c,v 1.345 2017/06/29 15:22:17 schwarze Exp $ */ /* * Copyright (c) 2008-2012 Kristaps Dzonsons * Copyright (c) 2010-2017 Ingo Schwarze @@ -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(); diff --git a/read.c b/read.c index f1c14c1d..ab390334 100644 --- a/read.c +++ b/read.c @@ -1,4 +1,4 @@ -/* $Id: read.c,v 1.182 2017/06/25 17:43:45 schwarze Exp $ */ +/* $Id: read.c,v 1.183 2017/06/29 15:22:17 schwarze Exp $ */ /* * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons * Copyright (c) 2010-2017 Ingo Schwarze @@ -151,6 +151,7 @@ static const char * const mandocerrs[MANDOCERR_MAX] = { "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[MANDOCERR_MAX] = { "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", diff --git a/regress/mdoc/Bl/Makefile b/regress/mdoc/Bl/Makefile index 01c45ed1..7ac8d729 100644 --- a/regress/mdoc/Bl/Makefile +++ b/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 unclosed break breakingIt breakingTa broken 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 breakingIt broken 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 diff --git a/regress/mdoc/Bl/column.in b/regress/mdoc/Bl/column.in index be6ccdca..5f059a8c 100644 --- a/regress/mdoc/Bl/column.in +++ b/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 diff --git a/regress/mdoc/Bl/column.out_lint b/regress/mdoc/Bl/column.out_lint index d335550c..dea3ec79 100644 --- a/regress/mdoc/Bl/column.out_lint +++ b/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) diff --git a/regress/mdoc/Bl/column_nogroff.in b/regress/mdoc/Bl/column_nogroff.in new file mode 100644 index 00000000..43f332fa --- /dev/null +++ b/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 diff --git a/regress/mdoc/Bl/column_nogroff.out_ascii b/regress/mdoc/Bl/column_nogroff.out_ascii new file mode 100644 index 00000000..f86d4d4f --- /dev/null +++ b/regress/mdoc/Bl/column_nogroff.out_ascii @@ -0,0 +1,15 @@ +BL-COLUMN_NOGROFF(1) General Commands Manual BL-COLUMN_NOGROFF(1) + +NNAAMMEE + BBll--ccoolluummnn__nnooggrrooffff - column lists mishandled by groff + +DDEESSCCRRIIPPTTIIOONN + Item macro without arguments: + + text macro after tab + + Tab macro at the beginning of a line: + + aa bb + +OpenBSD June 29, 2017 OpenBSD diff --git a/regress/mdoc/Bl/column_nogroff.out_lint b/regress/mdoc/Bl/column_nogroff.out_lint new file mode 100644 index 00000000..df15cf1b --- /dev/null +++ b/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) diff --git a/regress/mdoc/Bl/column_nogroff.out_markdown b/regress/mdoc/Bl/column_nogroff.out_markdown new file mode 100644 index 00000000..595236fb --- /dev/null +++ b/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 -- 2.47.1