report trailing delimiters after macros where they are usually a mistake;

the idea came up in a discussion with Thomas Klausner <wiz at NetBSD>

4 files changed, 109 insertions, 59 deletions

diff --git a/usr.bin/mandoc/mandoc.1 b/usr.bin/mandoc/mandoc.1
index d73611dadba..26e2cf4a20c 100644
--- a/usr.bin/mandoc/mandoc.1
+++ b/usr.bin/mandoc/mandoc.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mandoc.1,v 1.136 2017/07/03 13:40:00 schwarze Exp $
+.\"	$OpenBSD: mandoc.1,v 1.137 2017/07/03 17:33:01 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2012, 2014-2017 Ingo Schwarze <schwarze@openbsd.org>
@@ -905,11 +905,15 @@ list contains two consecutive
 entries describing the same
 .Ic \&Er
 number.
-.It Sy "description line ends with a full stop"
+.It Sy "trailing delimiter"
 .Pq mdoc
-Do not use punctuation at the end of an
-.Ic \&Nd
-block.
+The last argument of an
+.Ic \&Ex , \&Fo , \&Nd , \&Nm , \&Os , \&Sh , \&Ss , \&St ,
+or
+.Ic \&Sx
+macro ends with a trailing delimiter.
+This is usually bad style and often indicates typos.
+Most likely, the delimiter can be removed.
 .It Sy "no blank before trailing delimiter"
 .Pq mdoc
 The last argument of a macro that supports trailing delimiter
diff --git a/usr.bin/mandoc/mandoc.h b/usr.bin/mandoc/mandoc.h
index 4fa2e6241eb..4226e9fb61d 100644
--- a/usr.bin/mandoc/mandoc.h
+++ b/usr.bin/mandoc/mandoc.h
@@ -1,4 +1,4 @@
-/*	$OpenBSD: mandoc.h,v 1.182 2017/07/03 13:40:00 schwarze Exp $ */
+/*	$OpenBSD: mandoc.h,v 1.183 2017/07/03 17:33:01 schwarze Exp $ */
 /*
  * Copyright (c) 2010, 2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2010-2017 Ingo Schwarze <schwarze@openbsd.org>
@@ -62,8 +62,8 @@ enum	mandocerr {
 	MANDOCERR_BX, /* consider using OS macro: macro */
 	MANDOCERR_ER_ORDER, /* errnos out of order: Er ... */
 	MANDOCERR_ER_REP, /* duplicate errno: Er ... */
-	MANDOCERR_ND_DOT, /* description line ends with a full stop */
-	MANDOCERR_DELIM, /* no blank before trailing delimiter: macro ... */
+	MANDOCERR_DELIM, /* trailing delimiter: macro ... */
+	MANDOCERR_DELIM_NB, /* no blank before trailing delimiter: macro ... */
 	MANDOCERR_FUNC, /* function name without markup: name() */
 
 	MANDOCERR_WARNING, /* ===== start of warnings ===== */
diff --git a/usr.bin/mandoc/mdoc_validate.c b/usr.bin/mandoc/mdoc_validate.c
index a8ec7038967..7ab0b9508cc 100644
--- a/usr.bin/mandoc/mdoc_validate.c
+++ b/usr.bin/mandoc/mdoc_validate.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: mdoc_validate.c,v 1.262 2017/07/02 15:31:48 schwarze Exp $ */
+/*	$OpenBSD: mdoc_validate.c,v 1.263 2017/07/03 17:33:01 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2012 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2010-2017 Ingo Schwarze <schwarze@openbsd.org>
@@ -76,6 +76,7 @@ static	void	 post_defaults(POST_ARGS);
 static	void	 post_display(POST_ARGS);
 static	void	 post_dd(POST_ARGS);
 static	void	 post_delim(POST_ARGS);
+static	void	 post_delim_nb(POST_ARGS);
 static	void	 post_dt(POST_ARGS);
 static	void	 post_en(POST_ARGS);
 static	void	 post_es(POST_ARGS);
@@ -107,6 +108,7 @@ static	void	 post_sh_authors(POST_ARGS);
 static	void	 post_sm(POST_ARGS);
 static	void	 post_st(POST_ARGS);
 static	void	 post_std(POST_ARGS);
+static	void	 post_sx(POST_ARGS);
 static	void	 post_useless(POST_ARGS);
 static	void	 post_xr(POST_ARGS);
 static	void	 post_xx(POST_ARGS);
@@ -125,33 +127,33 @@ static	const v_post __mdoc_valids[MDOC_MAX - MDOC_Dd] = {
 	post_bl,	/* Bl */
 	NULL,		/* El */
 	post_it,	/* It */
-	post_delim,	/* Ad */
+	post_delim_nb,	/* Ad */
 	post_an,	/* An */
 	NULL,		/* Ap */
 	post_defaults,	/* Ar */
 	NULL,		/* Cd */
-	post_delim,	/* Cm */
-	post_delim,	/* Dv */
-	post_delim,	/* Er */
-	post_delim,	/* Ev */
+	post_delim_nb,	/* Cm */
+	post_delim_nb,	/* Dv */
+	post_delim_nb,	/* Er */
+	post_delim_nb,	/* Ev */
 	post_ex,	/* Ex */
 	post_fa,	/* Fa */
 	NULL,		/* Fd */
-	post_delim,	/* Fl */
+	post_delim_nb,	/* Fl */
 	post_fn,	/* Fn */
-	post_delim,	/* Ft */
-	post_delim,	/* Ic */
-	post_delim,	/* In */
+	post_delim_nb,	/* Ft */
+	post_delim_nb,	/* Ic */
+	post_delim_nb,	/* In */
 	post_defaults,	/* Li */
 	post_nd,	/* Nd */
 	post_nm,	/* Nm */
-	post_delim,	/* Op */
+	post_delim_nb,	/* Op */
 	post_obsolete,	/* Ot */
 	post_defaults,	/* Pa */
 	post_rv,	/* Rv */
 	post_st,	/* St */
-	post_delim,	/* Va */
-	post_delim,	/* Vt */
+	post_delim_nb,	/* Va */
+	post_delim_nb,	/* Vt */
 	post_xr,	/* Xr */
 	NULL,		/* %A */
 	post_hyph,	/* %B */ /* FIXME: can be used outside Rs/Re. */
@@ -165,12 +167,12 @@ static	const v_post __mdoc_valids[MDOC_MAX - MDOC_Dd] = {
 	post_hyph,	/* %T */ /* FIXME: can be used outside Rs/Re. */
 	NULL,		/* %V */
 	NULL,		/* Ac */
-	post_delim,	/* Ao */
-	post_delim,	/* Aq */
+	post_delim_nb,	/* Ao */
+	post_delim_nb,	/* Aq */
 	post_at,	/* At */
 	NULL,		/* Bc */
 	post_bf,	/* Bf */
-	post_delim,	/* Bo */
+	post_delim_nb,	/* Bo */
 	NULL,		/* Bq */
 	post_xx,	/* Bsx */
 	post_bx,	/* Bx */
@@ -180,37 +182,37 @@ static	const v_post __mdoc_valids[MDOC_MAX - MDOC_Dd] = {
 	NULL,		/* Dq */
 	NULL,		/* Ec */
 	NULL,		/* Ef */
-	post_delim,	/* Em */
+	post_delim_nb,	/* Em */
 	NULL,		/* Eo */
 	post_xx,	/* Fx */
-	post_delim,	/* Ms */
+	post_delim_nb,	/* Ms */
 	NULL,		/* No */
 	post_ns,	/* Ns */
 	post_xx,	/* Nx */
 	post_xx,	/* Ox */
 	NULL,		/* Pc */
 	NULL,		/* Pf */
-	post_delim,	/* Po */
-	post_delim,	/* Pq */
+	post_delim_nb,	/* Po */
+	post_delim_nb,	/* Pq */
 	NULL,		/* Qc */
-	post_delim,	/* Ql */
-	post_delim,	/* Qo */
-	post_delim,	/* Qq */
+	post_delim_nb,	/* Ql */
+	post_delim_nb,	/* Qo */
+	post_delim_nb,	/* Qq */
 	NULL,		/* Re */
 	post_rs,	/* Rs */
 	NULL,		/* Sc */
-	post_delim,	/* So */
-	post_delim,	/* Sq */
+	post_delim_nb,	/* So */
+	post_delim_nb,	/* Sq */
 	post_sm,	/* Sm */
-	post_hyph,	/* Sx */
-	post_delim,	/* Sy */
+	post_sx,	/* Sx */
+	post_delim_nb,	/* Sy */
 	post_useless,	/* Tn */
 	post_xx,	/* Ux */
 	NULL,		/* Xc */
 	NULL,		/* Xo */
 	post_fo,	/* Fo */
 	NULL,		/* Fc */
-	post_delim,	/* Oo */
+	post_delim_nb,	/* Oo */
 	NULL,		/* Oc */
 	post_bk,	/* Bk */
 	NULL,		/* Ek */
@@ -220,10 +222,10 @@ static	const v_post __mdoc_valids[MDOC_MAX - MDOC_Dd] = {
 	post_eoln,	/* Ud */
 	post_lb,	/* Lb */
 	post_par,	/* Lp */
-	post_delim,	/* Lk */
+	post_delim_nb,	/* Lk */
 	post_defaults,	/* Mt */
-	post_delim,	/* Brq */
-	post_delim,	/* Bro */
+	post_delim_nb,	/* Brq */
+	post_delim_nb,	/* Bro */
 	NULL,		/* Brc */
 	NULL,		/* %C */
 	post_es,	/* Es */
@@ -429,6 +431,34 @@ static void
 post_delim(POST_ARGS)
 {
 	const struct roff_node	*nch;
+	const char		*lc;
+	enum mdelim		 delim;
+	enum roff_tok		 tok;
+
+	tok = mdoc->last->tok;
+	nch = mdoc->last->last;
+	if (nch == NULL || nch->type != ROFFT_TEXT)
+		return;
+	lc = strchr(nch->string, '\0') - 1;
+	if (lc < nch->string)
+		return;
+	delim = mdoc_isdelim(lc);
+	if (delim == DELIM_NONE || delim == DELIM_OPEN)
+		return;
+	if (*lc == ')' && (tok == MDOC_Nd || tok == MDOC_Sh ||
+	    tok == MDOC_Ss || tok == MDOC_Fo))
+		return;
+
+	mandoc_vmsg(MANDOCERR_DELIM, mdoc->parse,
+	    nch->line, nch->pos + (lc - nch->string),
+	    "%s%s %s", roff_name[tok],
+	    nch == mdoc->last->child ? "" : " ...", nch->string);
+}
+
+static void
+post_delim_nb(POST_ARGS)
+{
+	const struct roff_node	*nch;
 	const char		*lc, *cp;
 	int			 nw;
 	enum mdelim		 delim;
@@ -514,7 +544,7 @@ post_delim(POST_ARGS)
 		}
 	}
 
-	mandoc_vmsg(MANDOCERR_DELIM, mdoc->parse,
+	mandoc_vmsg(MANDOCERR_DELIM_NB, mdoc->parse,
 	    nch->line, nch->pos + (lc - nch->string),
 	    "%s%s %s", roff_name[tok],
 	    nch == mdoc->last->child ? "" : " ...", nch->string);
@@ -894,7 +924,7 @@ post_lb(POST_ARGS)
 {
 	struct roff_node	*n;
 
-	post_delim(mdoc);
+	post_delim_nb(mdoc);
 
 	n = mdoc->last;
 	assert(n->child->type == ROFFT_TEXT);
@@ -953,6 +983,8 @@ post_std(POST_ARGS)
 {
 	struct roff_node *n;
 
+	post_delim(mdoc);
+
 	n = mdoc->last;
 	if (n->args && n->args->argc == 1)
 		if (n->args->argv[0].arg == MDOC_Std)
@@ -1122,7 +1154,8 @@ post_fo(POST_ARGS)
 		    "Fo ... %s", n->child->next->string);
 		while (n->child != n->last)
 			roff_node_delete(mdoc, n->last);
-	}
+	} else
+		post_delim(mdoc);
 
 	post_fname(mdoc);
 }
@@ -1146,7 +1179,7 @@ post_fa(POST_ARGS)
 			break;
 		}
 	}
-	post_delim(mdoc);
+	post_delim_nb(mdoc);
 }
 
 static void
@@ -1174,11 +1207,18 @@ post_nm(POST_ARGS)
 		mandoc_msg(MANDOCERR_NM_NONAME, mdoc->parse,
 		    n->line, n->pos, "Nm");
 
-	if (n->type == ROFFT_ELEM)
+	switch (n->type) {
+	case ROFFT_ELEM:
+		post_delim_nb(mdoc);
+		break;
+	case ROFFT_HEAD:
 		post_delim(mdoc);
+		break;
+	default:
+		return;
+	}
 
-	if ((n->type != ROFFT_ELEM && n->type != ROFFT_HEAD) ||
-	    (n->child != NULL && n->child->type == ROFFT_TEXT) ||
+	if ((n->child != NULL && n->child->type == ROFFT_TEXT) ||
 	    mdoc->meta.name == NULL)
 		return;
 
@@ -1192,7 +1232,6 @@ static void
 post_nd(POST_ARGS)
 {
 	struct roff_node	*n;
-	size_t			 sz;
 
 	n = mdoc->last;
 
@@ -1206,11 +1245,8 @@ post_nd(POST_ARGS)
 	if (n->child == NULL)
 		mandoc_msg(MANDOCERR_ND_EMPTY, mdoc->parse,
 		    n->line, n->pos, "Nd");
-	else if (n->last->type == ROFFT_TEXT &&
-	    (sz = strlen(n->last->string)) != 0 &&
-	    n->last->string[sz - 1] == '.')
-		mandoc_msg(MANDOCERR_ND_DOT, mdoc->parse,
-		    n->last->line, n->last->pos + sz - 1, NULL);
+	else
+		post_delim(mdoc);
 
 	post_hyph(mdoc);
 }
@@ -1268,7 +1304,7 @@ post_defaults(POST_ARGS)
 	struct roff_node *nn;
 
 	if (mdoc->last->child != NULL) {
-		post_delim(mdoc);
+		post_delim_nb(mdoc);
 		return;
 	}
 
@@ -1343,7 +1379,7 @@ post_an(POST_ARGS)
 			mandoc_msg(MANDOCERR_MACRO_EMPTY, mdoc->parse,
 			    np->line, np->pos, "An");
 		else
-			post_delim(mdoc);
+			post_delim_nb(mdoc);
 	} else if (nch != NULL)
 		mandoc_vmsg(MANDOCERR_ARG_EXCESS, mdoc->parse,
 		    nch->line, nch->pos, "An ... %s", nch->string);
@@ -1372,7 +1408,7 @@ post_xx(POST_ARGS)
 	struct roff_node	*n;
 	const char		*os;
 
-	post_delim(mdoc);
+	post_delim_nb(mdoc);
 
 	n = mdoc->last;
 	switch (n->tok) {
@@ -2001,6 +2037,13 @@ post_ns(POST_ARGS)
 }
 
 static void
+post_sx(POST_ARGS)
+{
+	post_delim(mdoc);
+	post_hyph(mdoc);
+}
+
+static void
 post_sh(POST_ARGS)
 {
 
@@ -2337,7 +2380,7 @@ post_xr(POST_ARGS)
 			    nch->line, nch->pos, "Xr %s %s",
 			    nch->string, nch->next->string);
 	}
-	post_delim(mdoc);
+	post_delim_nb(mdoc);
 }
 
 static void
@@ -2350,6 +2393,7 @@ post_ignpar(POST_ARGS)
 		post_prevpar(mdoc);
 		return;
 	case ROFFT_HEAD:
+		post_delim(mdoc);
 		post_hyph(mdoc);
 		return;
 	case ROFFT_BODY:
@@ -2586,7 +2630,7 @@ post_bx(POST_ARGS)
 	struct roff_node	*n, *nch;
 	const char		*macro;
 
-	post_delim(mdoc);
+	post_delim_nb(mdoc);
 
 	n = mdoc->last;
 	nch = n->child;
@@ -2652,6 +2696,8 @@ post_os(POST_ARGS)
 		mandoc_msg(MANDOCERR_PROLOG_LATE, mdoc->parse,
 		    n->line, n->pos, "Os");
 
+	post_delim(mdoc);
+
 	/*
 	 * Set the operating system by way of the `Os' macro.
 	 * The order of precedence is:
diff --git a/usr.bin/mandoc/read.c b/usr.bin/mandoc/read.c
index 5c409947c49..6853493da5a 100644
--- a/usr.bin/mandoc/read.c
+++ b/usr.bin/mandoc/read.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: read.c,v 1.158 2017/07/03 13:40:00 schwarze Exp $ */
+/*	$OpenBSD: read.c,v 1.159 2017/07/03 17:33:01 schwarze Exp $ */
 /*
  * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2010-2017 Ingo Schwarze <schwarze@openbsd.org>
@@ -100,7 +100,7 @@ static	const char * const	mandocerrs[MANDOCERR_MAX] = {
 	"consider using OS macro",
 	"errnos out of order",
 	"duplicate errno",
-	"description line ends with a full stop",
+	"trailing delimiter",
 	"no blank before trailing delimiter",
 	"function name without markup",