From: schwarze Date: Mon, 3 Jul 2017 17:33:01 +0000 (+0000) Subject: report trailing delimiters after macros where they are usually a mistake; X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=fe8e59eddb2304f08b119d60734bfe1f97a032fb;p=openbsd report trailing delimiters after macros where they are usually a mistake; the idea came up in a discussion with Thomas Klausner --- 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 .\" Copyright (c) 2012, 2014-2017 Ingo Schwarze @@ -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 * Copyright (c) 2010-2017 Ingo Schwarze @@ -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 * Copyright (c) 2010-2017 Ingo Schwarze @@ -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 */ @@ -427,6 +429,34 @@ check_toptext(struct roff_man *mdoc, int ln, int pos, const char *p) 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; @@ -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) { @@ -2000,6 +2036,13 @@ post_ns(POST_ARGS) n->line, n->pos, NULL); } +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 * Copyright (c) 2010-2017 Ingo Schwarze @@ -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",