Text embedded in Bl

Text embedded in Bl

[Anthony J. Bentley]

Hi,

Consider the following, based on an example from gnugk(1):

.Bl -tag -width Ds
This is an opening paragraph.
.It Fl a
Perform behavior foo.
...
.El

Mandoc refuses to display the page:
FATAL: child violates parent syntax

Groff, on the other hand, displays it (I'm not sure of the specifics, but
my guess is it treats the first part as a Pp):

     This is an opening paragraph.

     -a      Perform behavior foo.

To me, this is obviously wrong. To realize why, just think of the case
where you want two paragraphs. (Or the case where the Bl only contains a
single paragraph with no items--which also appeared in this manpage!)
Based on this reasoning, I sent a fixed manpage to upstream, who committed
it.

But now I wonder. Should mandoc mimic groff here? I think no, but maybe
someone else will have a different opinion.

-- 
Anthony J. Bentley
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Text embedded in Bl

[Ingo Schwarze]

Hi Anthony,

Anthony J. Bentley wrote on Sun, Sep 22, 2013 at 04:33:21PM -0600:

> Consider the following, based on an example from gnugk(1):

I saw the commit message on ports-changes@ and thought, "ugh, this
looks fishy, i should probably look into it" but wasn't sure to find
the time.  Thank you for looking so carefully into mandoc matters.
This is really helpful.

> .Bl -tag -width Ds
> This is an opening paragraph.
> .It Fl a
> Perform behavior foo.
> ...
> .El
> 
> Mandoc refuses to display the page:
> FATAL: child violates parent syntax

Oh dear.
Right, that crash is still in the code.
Now that you talk about it, i see that it's not even listed as a bug.

That one went right to the top of the TODO list, i consider it the
worst bug currently known, as it's a needless crash.

> Groff, on the other hand, displays it (I'm not sure of the specifics,
> but my guess is it treats the first part as a Pp):
> 
>      This is an opening paragraph.
> 
>      -a      Perform behavior foo.
> 
> To me, this is obviously wrong. To realize why, just think of the case
> where you want two paragraphs. (Or the case where the Bl only contains a
> single paragraph with no items--which also appeared in this manpage!)
> Based on this reasoning, I sent a fixed manpage to upstream, who committed
> it.

Yes, sure it's a syntax error, and sure it should be fixed upstream,
thank you for having upstream fix the mdoc(7) syntax error.

> But now I wonder.  Should mandoc mimic groff here?  I think no,
> but maybe someone else will have a different opinion.

Of course it should.
The aim is that mandoc be bug-compatible with groff.

Well, unless it is terribly difficult to implement, or clobbers the
code with a ton of spaghetti, or groff is so blatantly broken that
i prefer to go and fix groff.  But the case at hand, what groff does
is quite reasonable:  When the markup makes no sense whatsoever,
just show the text without the markup.

In any case, mandoc mustn't crash, but keep going.

Yours,
  Ingo


 ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >8 -----

Date: Sun, 22 Sep 2013 19:21:23 -0400 (EDT)
From: schwarze@mdocml.bsd.lv
To: source@mdocml.bsd.lv
Subject: mdocml: Throwing FATAL MANDOCERR_SYNTCHILD on non-.It children of .Bl 

Log Message:
-----------
Throwing FATAL MANDOCERR_SYNTCHILD on non-.It children of .Bl
feels so 2008-ish, one of the last remnants of the
Kristaps-doesnt-like-syntax-errors-so-lets-just-give-up--Era.

Modified Files:
--------------
    mdocml:
        TODO

Revision Data
-------------
Index: TODO
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/TODO,v
retrieving revision 1.155
retrieving revision 1.156
diff -LTODO -LTODO -u -p -r1.155 -r1.156
--- TODO
+++ TODO
@@ -7,7 +7,13 @@
 * crashes
 ************************************************************************
 
-None known right now.
+- .Bl -tag followed by a text node preceding the first .It should not
+  throw a FATAL error, but only a normal ERROR.  Putting this into the
+  HEAD of an implicit .It might be cleanest, inserting an implicit .Pp
+  or just dumping the orphan stuff directly into the BODY of the .Bl
+  might be easier to implement, and all options can no doubt be made
+  to yield correct (i.e. groff bug-compatible) rendering.
+  Anthony J. Bentley on discuss@  Sun, 22 Sep 2013 16:33:21 -0600
 
 ************************************************************************
 * missing features
--
 To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv