WARNING: blocks badly nested: Oc breaks Op

WARNING: blocks badly nested: Oc breaks Op

[Jason McIntyre]

hi. pfctl(8) contains this snippet:

	.Xo
	.Oo Fl t Ar table
	.Fl T Ar command
	.Op Ar address ... Oc
	.Xc

mandoc is not happy about having a ".Op ... Oc" line and warns:

	pfctl.8:56:20: WARNING: blocks badly nested: Oc breaks Op

but is that fair? of course i can move the Oc to a separate line, but
why should i?

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

Re: WARNING: blocks badly nested: Oc breaks Op

[Ingo Schwarze]

Hi Jason,

Jason McIntyre wrote on Sat, Sep 11, 2010 at 08:46:00AM +0100:

> hi. pfctl(8) contains this snippet:
> 
> 	.Xo
> 	.Oo Fl t Ar table
> 	.Fl T Ar command
> 	.Op Ar address ... Oc
> 	.Xc
> 
> mandoc is not happy about having a ".Op ... Oc" line and warns:
> 
> 	pfctl.8:56:20: WARNING: blocks badly nested: Oc breaks Op
> 
> but is that fair?

Yes, i implemented that warning on purpose, and i consider it fair.

The scope of the .Op macro is defined to extend to the end of the line.
So, the code cited above
 - first opens .Oo
 - then opens .Op
 - then closes .Oo (breaking .Op)

In XML, it would look like this:  <Oo> <Op> </Oo> </Op>

When the two enclosures are different, it does even matter
with respect to rendering:

  .Oo Fl t Ar table
  .Fl T Ar command
  .Pq Ar address ... Oc

produces

  [-t table -T command (address ...])

in both old and new groff, and also in mandoc.

> of course i can move the Oc to a separate line, but
> why should i?

Because then you get nice nesting:
Then the Op is completely contained in the Oo.

I admit groff doesn't warn about bad nesting,
but then again, groff issues very few warnings at all.

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

Re: WARNING: blocks badly nested: Oc breaks Op

[Jason McIntyre]

On Thu, Sep 16, 2010 at 11:23:33PM +0200, Ingo Schwarze wrote:
> Hi Jason,
> 
> Jason McIntyre wrote on Sat, Sep 11, 2010 at 08:46:00AM +0100:
> 
> > hi. pfctl(8) contains this snippet:
> > 
> > 	.Xo
> > 	.Oo Fl t Ar table
> > 	.Fl T Ar command
> > 	.Op Ar address ... Oc
> > 	.Xc
> > 
> > mandoc is not happy about having a ".Op ... Oc" line and warns:
> > 
> > 	pfctl.8:56:20: WARNING: blocks badly nested: Oc breaks Op
> > 
> > but is that fair?
> 
> Yes, i implemented that warning on purpose, and i consider it fair.
> 
> The scope of the .Op macro is defined to extend to the end of the line.
> So, the code cited above
>  - first opens .Oo
>  - then opens .Op
>  - then closes .Oo (breaking .Op)
> 
> In XML, it would look like this:  <Oo> <Op> </Oo> </Op>
> 
> When the two enclosures are different, it does even matter
> with respect to rendering:
> 
>   .Oo Fl t Ar table
>   .Fl T Ar command
>   .Pq Ar address ... Oc
> 
> produces
> 
>   [-t table -T command (address ...])
> 
> in both old and new groff, and also in mandoc.
> 
> > of course i can move the Oc to a separate line, but
> > why should i?
> 
> Because then you get nice nesting:
> Then the Op is completely contained in the Oo.
> 
> I admit groff doesn't warn about bad nesting,
> but then again, groff issues very few warnings at all.
> 
> Yours,
>   Ingo

i don;t totally understand. Oo/Oc need not happen on the same line, so i
consider it fair game that i can stick Oc on the end of an Op line.

are you saying it's a limit of the parser and i shouldn;t do it?
not only does groff not warn about it, it also renders it correctly (as
does mandoc). hence my confusion that it generates a warning.

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

Re: WARNING: blocks badly nested: Oc breaks Op

[Joerg Sonnenberger]

On Thu, Sep 16, 2010 at 11:27:23PM +0100, Jason McIntyre wrote:
> i don;t totally understand. Oo/Oc need not happen on the same line, so i
> consider it fair game that i can stick Oc on the end of an Op line.

Your example did not put the Oc on a separate line from the Op. So yes,
there is a difference between

.Oo
.Op ...
.Oc

and

.Oo
.Op .. Oc

and as Ingo mentioned, as soon as you replace .Op with .Sq for example,
it becomes obvious.

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

Re: WARNING: blocks badly nested: Oc breaks Op

[Jason McIntyre]

On Fri, Sep 17, 2010 at 12:50:11PM +0200, Joerg Sonnenberger wrote:
> On Thu, Sep 16, 2010 at 11:27:23PM +0100, Jason McIntyre wrote:
> > i don;t totally understand. Oo/Oc need not happen on the same line, so i
> > consider it fair game that i can stick Oc on the end of an Op line.
> 
> Your example did not put the Oc on a separate line from the Op. So yes,
> there is a difference between
> 
> .Oo
> .Op ...
> .Oc
> 
> and
> 
> .Oo
> .Op .. Oc
> 
> and as Ingo mentioned, as soon as you replace .Op with .Sq for example,
> it becomes obvious.
> 

so i should not do it. fair enough.

in that case the diff you (ingo) mailed me for pfctl.8 is ok me.

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