tweak message "scope open on exit"

tweak message "scope open on exit"

[Ingo Schwarze]

Hi,

in mdoc(7), if an explicit scope is still open at the end of an input
file, that's FATAL.  I really don't see why, it's trivial to just
close out the block and proceed to rendering the file.

On the other hand, in man(7), if an explicit scope is still open at
the end of an input file, that's merely a WARNING.  I regard that
as dangerous, because an unclosed block probably means that either:

 - some input text is missing, resulting in incomplete output
 - or closure of a block is missing, probably resulting in
   garbled document structure from that point onwards.

As i see it, that's a typical case of a non-fatal ERROR:
We can render, but probably infomation is missing or the
structure is seriously mangled.

Besides, why not use the same error type for mdoc(7) and man(7)?

And finally, since we do know that the error is non-fatal,
there is no need to check the return value of the msg function.

Fishing for OKs...  :)

Yours,
  Ingo


Index: main.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/main.c,v
retrieving revision 1.46
diff -u -p -r1.46 main.c
--- main.c	20 Aug 2010 08:13:03 -0000	1.46
+++ main.c	23 Sep 2010 22:41:04 -0000
@@ -124,7 +124,6 @@ static	const char * const	mandocerrs[MAN
 	"section not in conventional manual section",
 	"end of line whitespace",
 	"blocks badly nested",
-	"scope open on exit",
 
 	"generic error",
 
@@ -150,6 +149,7 @@ static	const char * const	mandocerrs[MAN
 	"argument count wrong",
 	"request scope close w/none open",
 	"scope already open",
+	"scope open on exit",
 	"macro requires line argument(s)",
 	"macro requires body argument(s)",
 	"macro requires argument(s)",
@@ -167,7 +167,6 @@ static	const char * const	mandocerrs[MAN
 	"unsupported display type",
 	"blocks badly nested",
 	"no such block is open",
-	"scope broken, syntax violated",
 	"line scope broken, syntax violated",
 	"argument count wrong, violates syntax",
 	"child violates parent syntax",
Index: mandoc.h
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mandoc.h,v
retrieving revision 1.12
diff -u -p -r1.12 mandoc.h
--- mandoc.h	20 Aug 2010 00:53:35 -0000	1.12
+++ mandoc.h	23 Sep 2010 22:41:04 -0000
@@ -63,7 +63,6 @@ enum	mandocerr {
 	MANDOCERR_SECMSEC, /* section not in conventional manual section */
 	MANDOCERR_EOLNSPACE, /* end of line whitespace */
 	MANDOCERR_SCOPENEST, /* blocks badly nested */
-	MANDOCERR_SCOPEEXIT, /* scope open on exit */
 
 	MANDOCERR_ERROR, /* ===== end of errors ===== */
 
@@ -89,6 +88,7 @@ enum	mandocerr {
 	MANDOCERR_ARGCOUNT, /* argument count wrong */
 	MANDOCERR_NOSCOPE, /* no such block is open */
 	MANDOCERR_SCOPEREP, /* scope already open */
+	MANDOCERR_SCOPEEXIT, /* scope open on exit */
 	/* FIXME: merge following with MANDOCERR_ARGCOUNT */
 	MANDOCERR_NOARGS, /* macro requires line argument(s) */
 	MANDOCERR_NOBODY, /* macro requires body argument(s) */
@@ -108,7 +108,6 @@ enum	mandocerr {
 	MANDOCERR_BADDISP, /* unsupported display type */
 	MANDOCERR_SCOPEFATAL, /* blocks badly nested */
 	MANDOCERR_SYNTNOSCOPE, /* no scope to rewind: syntax violated */
-	MANDOCERR_SYNTSCOPE, /* scope broken, syntax violated */
 	MANDOCERR_SYNTLINESCOPE, /* line scope broken, syntax violated */
 	MANDOCERR_SYNTARGVCOUNT, /* argument count wrong, violates syntax */
 	MANDOCERR_SYNTCHILD, /* child violates parent syntax */
Index: mdoc_macro.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/mdoc_macro.c,v
retrieving revision 1.55
diff -u -p -r1.55 mdoc_macro.c
--- mdoc_macro.c	16 Jul 2010 00:34:33 -0000	1.55
+++ mdoc_macro.c	23 Sep 2010 22:41:10 -0000
@@ -203,14 +203,10 @@ mdoc_macroend(struct mdoc *m)
 
 	n = MDOC_VALID & m->last->flags ?  m->last->parent : m->last;
 
-	for ( ; n; n = n->parent) {
-		if (MDOC_BLOCK != n->type)
-			continue;
-		if ( ! (MDOC_EXPLICIT & mdoc_macros[n->tok].flags))
-			continue;
-		mdoc_nmsg(m, n, MANDOCERR_SYNTSCOPE);
-		return(0);
-	}
+	for ( ; n; n = n->parent)
+		if (MDOC_BLOCK == n->type &&
+		    MDOC_EXPLICIT & mdoc_macros[n->tok].flags)
+			mdoc_nmsg(m, n, MANDOCERR_SCOPEEXIT);
 
 	/* Rewind to the first. */

--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: tweak message "scope open on exit"

[Kristaps Dzonsons]

> in mdoc(7), if an explicit scope is still open at the end of an input
> file, that's FATAL.  I really don't see why, it's trivial to just
> close out the block and proceed to rendering the file.
> 
> On the other hand, in man(7), if an explicit scope is still open at
> the end of an input file, that's merely a WARNING.  I regard that
> as dangerous, because an unclosed block probably means that either:
> 
>  - some input text is missing, resulting in incomplete output
>  - or closure of a block is missing, probably resulting in
>    garbled document structure from that point onwards.
> 
> As i see it, that's a typical case of a non-fatal ERROR:
> We can render, but probably infomation is missing or the
> structure is seriously mangled.
> 
> Besides, why not use the same error type for mdoc(7) and man(7)?
> 
> And finally, since we do know that the error is non-fatal,
> there is no need to check the return value of the msg function.

Ingo, this looks good.  At first I dithered for a while about returning 
0 to mdoc_endparse(), but because the error is non-fatal, your reasoning 
is sound and I agree.

Can you fix up the WARNING->ERROR logic in libman, too?

Thanks,

Kristaps
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: tweak message "scope open on exit"

[Ingo Schwarze]

Hi Kristaps,

Kristaps Dzonsons wrote on Sun, Sep 26, 2010 at 11:13:05AM +0200:
> Ingo Schwarze wrote:

>> in mdoc(7), if an explicit scope is still open at the end of an input
>> file, that's FATAL.  I really don't see why, it's trivial to just
>> close out the block and proceed to rendering the file.
>>
>> On the other hand, in man(7), if an explicit scope is still open at
>> the end of an input file, that's merely a WARNING.  I regard that
>> as dangerous, because an unclosed block probably means that either:
[...]
>>
>> As i see it, that's a typical case of a non-fatal ERROR:
>> We can render, but probably infomation is missing or the
>> structure is seriously mangled.
>>
>> Besides, why not use the same error type for mdoc(7) and man(7)?
>>
>> And finally, since we do know that the error is non-fatal,
>> there is no need to check the return value of the msg function.

> Ingo, this looks good.  At first I dithered for a while about
> returning 0 to mdoc_endparse(), but because the error is non-fatal,
> your reasoning is sound and I agree.

Right, that is the good news about mdoc_nmsg() and friends,
basically about all messaging functions based on main.c, function
mmsg():  These functions now cannot fail any more, and we know
the return value beforehand, so in the long run, we can drop
all the return value tests and finally make mmsg() void.
That will shorten much of the code and make it easier on the eye.

I don't see the pressing need for big churn right now and rather
plan to simplify what needs to be touched anyway, as we go.

> Can you fix up the WARNING->ERROR logic in libman, too?

I don't think anything more needs to be done, in particular
i can't think of anything to change in man*.c.
As far as i understand, just moving the entry in the lists
in mandoc.h and main.c does the trick for man.

Or am i missing anything?

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv