discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: "Dag-Erling Smørgrav" <des@des.no>
Cc: discuss@mdocml.bsd.lv
Subject: Re: Dashes and strange markup
Date: Mon, 6 Mar 2017 18:34:05 +0100	[thread overview]
Message-ID: <20170306173405.GD58385@athene.usta.de> (raw)
In-Reply-To: <86h936pdes.fsf@desk.des.no>

Hi,

Dag-Erling Smoergrav wrote on Mon, Mar 06, 2017 at 05:39:55PM +0100:
> Ingo Schwarze <schwarze@usta.de> writes:

>> Well, abusing .Nd outside NAME is so bizarre that being forgiving
>> about it would be a bad idea.

> Technically, mandoc *is* forgiving about it: it renders it the way the
> author (incorrectly) expected instead of throwing an error, which is
> probably why it has gone unnoticed until now.

Good point!

Now, mandoc(1) never errors out, which is an important feature.

But it should indeed throw a warning.

I just committed the patch below, implementing the missing warning.

>> Anthony correctly answered the rest, so my impression is that no
>> code or documentation changes are required.

> I asked for advice, not changes.

Fair enough.

Then again, when intelligent people ask for advice, there is often
something that can be improved.  :)

Thanks for the report,
  Ingo


Log Message:
-----------
Using .Nd only makes sense in the NAME section.
Warn if that macro occurs elsewhere.
Triggered by a question from Dag-Erling Smoergrav <des @ FreeBSD>.

Modified Files:
--------------
    mdocml:
        mandoc.1
        mandoc.h
        mdoc_validate.c
        read.c
    mdocml/regress/mdoc/Nd:
        broken.out_lint

Revision Data
-------------
Index: mandoc.1
===================================================================
RCS file: /home/cvs/mdocml/mdocml/mandoc.1,v
retrieving revision 1.176
retrieving revision 1.177
diff -Lmandoc.1 -Lmandoc.1 -u -p -r1.176 -r1.177
--- mandoc.1
+++ mandoc.1
@@ -908,6 +908,14 @@ The
 .Ic \&Nd
 macro lacks the required argument.
 The title line of the manual will end after the dash.
+.It Sy "description line outside NAME section"
+.Pq mdoc
+An
+.Ic \&Nd
+macro appears outside the NAME section.
+The arguments are printed anyway and the following text is used for
+.Xr apropos 1 ,
+but none of that behaviour is portable.
 .It Sy "sections out of conventional order"
 .Pq mdoc
 A standard section occurs after another section it usually precedes.
Index: read.c
===================================================================
RCS file: /home/cvs/mdocml/mdocml/read.c,v
retrieving revision 1.161
retrieving revision 1.162
diff -Lread.c -Lread.c -u -p -r1.161 -r1.162
--- read.c
+++ read.c
@@ -113,6 +113,7 @@ static	const char * const	mandocerrs[MAN
 	"bad NAME section content",
 	"missing comma before name",
 	"missing description line, using \"\"",
+	"description line outside NAME section",
 	"sections out of conventional order",
 	"duplicate section title",
 	"unexpected section",
Index: mandoc.h
===================================================================
RCS file: /home/cvs/mdocml/mdocml/mandoc.h,v
retrieving revision 1.214
retrieving revision 1.215
diff -Lmandoc.h -Lmandoc.h -u -p -r1.214 -r1.215
--- mandoc.h
+++ mandoc.h
@@ -71,6 +71,7 @@ enum	mandocerr {
 	MANDOCERR_NAMESEC_BAD, /* bad NAME section content: macro */
 	MANDOCERR_NAMESEC_PUNCT, /* missing comma before name: Nm name */
 	MANDOCERR_ND_EMPTY, /* missing description line, using "" */
+	MANDOCERR_ND_LATE, /* description line outside NAME section */
 	MANDOCERR_SEC_ORDER, /* sections out of conventional order: Sh title */
 	MANDOCERR_SEC_REP, /* duplicate section title: Sh title */
 	MANDOCERR_SEC_MSEC, /* unexpected section: Sh title for ... only */
Index: mdoc_validate.c
===================================================================
RCS file: /home/cvs/mdocml/mdocml/mdoc_validate.c,v
retrieving revision 1.318
retrieving revision 1.319
diff -Lmdoc_validate.c -Lmdoc_validate.c -u -p -r1.318 -r1.319
--- mdoc_validate.c
+++ mdoc_validate.c
@@ -1035,6 +1035,10 @@ post_nd(POST_ARGS)
 	if (n->type != ROFFT_BODY)
 		return;
 
+	if (n->sec != SEC_NAME)
+		mandoc_msg(MANDOCERR_ND_LATE, mdoc->parse,
+		    n->line, n->pos, "Nd");
+
 	if (n->child == NULL)
 		mandoc_msg(MANDOCERR_ND_EMPTY, mdoc->parse,
 		    n->line, n->pos, "Nd");
Index: broken.out_lint
===================================================================
RCS file: /home/cvs/mdocml/mdocml/regress/mdoc/Nd/broken.out_lint,v
retrieving revision 1.2
retrieving revision 1.3
diff -Lregress/mdoc/Nd/broken.out_lint -Lregress/mdoc/Nd/broken.out_lint -u -p -r1.2 -r1.3
--- regress/mdoc/Nd/broken.out_lint
+++ regress/mdoc/Nd/broken.out_lint
@@ -3,5 +3,7 @@ mandoc: broken.in:5:2: WARNING: bad NAME
 mandoc: broken.in:9:1: WARNING: bad NAME section content: text
 mandoc: broken.in:4:2: WARNING: NAME section without Nm before Nd
 mandoc: broken.in:4:2: WARNING: NAME section without description
+mandoc: broken.in:16:2: WARNING: description line outside NAME section: Nd
 mandoc: broken.in:13:2: WARNING: moving content out of list: Bl
 mandoc: broken.in:18:1: WARNING: moving content out of list: text
+mandoc: broken.in:27:2: WARNING: description line outside NAME section: Nd
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

      reply	other threads:[~2017-03-06 17:34 UTC|newest]

Thread overview: 6+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-03-06 11:17 Dag-Erling Smørgrav
2017-03-06 14:55 ` Anthony J. Bentley
2017-03-06 16:52   ` Dag-Erling Smørgrav
2017-03-06 15:57 ` Ingo Schwarze
2017-03-06 16:39   ` Dag-Erling Smørgrav
2017-03-06 17:34     ` 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=20170306173405.GD58385@athene.usta.de \
    --to=schwarze@usta.de \
    --cc=des@des.no \
    --cc=discuss@mdocml.bsd.lv \
    --subject='Re: Dashes and strange markup' \
    /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).