befuddled by .Xo/.Xc

befuddled by .Xo/.Xc

[Evan Silberman]

Hi all,

I just sent the below to tech@openbsd with a patch (snipped).

Evan Silberman <evan@jklol.net> wrote:
> .Xo/.Xc outside an .It header or a block-partial-implicit macro body seems to
> be a no-op on present mandoc and is not a documented use-case. ascii and
> html output are identical before and after.
> 
> If I'm wrong about the above in some way I will appreciate correction,
> as I am working on an mdoc(7) parser in another setting, and naturally
> mandoc(1) is my reference implementation and the OpenBSD manuals are my
> reference corpus.

I am crossposting here because I'm realizing that I don't actually
understand mdoc(7)'s documentation of what .Xo/.Xc are meant to do
outside the limited case of the .It header, and it seems more
appropriate to ask here.

mdoc(7) reads:

> Extend … the body of a partial-implicit block macro beyond the end of
> the input line.

My interpretation of this sentence was that these two snippets of markup
should be equivalent:
   
   .Dq hello, world

   .Dq hello, Xo
   world
   .Xc

It can easily be verified that this isn't true.

I can find no instances of .Xo outside of .It in OpenBSD's installed
manuals that really explain this usage to me. There are the cases where
.Xo (on a line by itself)/.Xc just wrap some other stuff, that as far as
I could tell were a no-op. The only other examples are from ksh.1, which
differ only in that .Xo comes at the end of a control line with some
other stuff in it. It seems to be a no-op there too. And it still
doesn't clearly demonstrate a particular association with a
block-partial-implicit macro.

   .Sm off
   .Ao Ar var Ac Xo
   .Aq Ar op
   .No = Aq Ar expr
   .Xc
   .Sm on

Finally, .Xo/.Xc is used in a couple mdoc regress tests for (it appears)
artificial reasons, to enclose an empty Fl macro with a block that
doesn't print anything special.

I searched for .Xo in the discuss@ archives and was not particularly
enlightened, beyond some evidence that .Xo/.Xc had some special
attention paid to it during mandoc's early days.

So, I am left with the question: what, if anything, is .Xo/.Xc meant to
do outside of an .It header? In mandoc, does it still actually do what
it's meant to do?

And either way, can a reasonably-accurate mdoc(7) parser just treat it
as a no-op?

thanks,
Evan Silberman
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv