RE: invalid doc, but why?

Hi Barton,

That is one great explanation and gave me a laugh or two this morning. Thanks.

I had always wondered what the deal was with those underscored elements in the documentation, figuring that it was important but not understanding how. It would be good to see more documentation on those.

In any case, I don't have many of these corner cases like optional:phrase:optional or option:phrase:inlineequation

So I'll take care of postprocessing these in a separate, somewhat messy, subroutine.

thanks for your fantastic explanation. friggin' phrase wildnesses!

--Tim Arnold

From: Barton Wright [mailto:bwright@streambase.com]
Sent: Tuesday, October 12, 2010 11:50 PM
To: Tim Arnold; docbook@lists.oasis-open.org
Subject: RE: invalid doc, but why?

Remember that the XSD version of the DocBook 5 schema is not normative. It does its best, but it can’t convey all the subtleties of the RELAX NG schema, and the RNG schema is the only one that’s normative.

My hazy understanding is that <phrase> has two lives in DB 5. In its day job, <phrase> is a taxpaying citizen whose full name is db.phrase, and it has rights and responsibilities. But there is another <phrase> who goes by db._phrase, and this is the wild one who goes out at night with a shadowy underground group that call themselves the nearly ubiquitous inlines.

When the RNG schema allows:

it is acknowledging <db.phrase> as a full citizen, and <optional> as a full citizen member of the Technical Inlines group. Everything’s on the up and up.

But when the RNG schema allows:

</optional>

it is only because <db._phrase> showed a fake ID at the door, and pretended to be ubiquitous. And in this context, it is ubiquitous enough.

However, when you (ahem) relax your standards and go all whatever on us, you start trying out such wildnesses as:

<optional>Our goal is world domination</optional>

</phrase>

</optional>

Well now. That’s when the RNG schema puts it badge back on and starts checking IDs and taking names. In the ensuing round-up, it discovers that <db._phrase> isn’t all that ubiquitous and isn’t always allowed in the <optional> door – especially not carrying that <optional> suitcase. Wait, is that suitcase ticking?

Don’t you wish you’d taken that blue pill now?

[Late night silliness aside, I would love to read an accurate and somewhat saner description of why some ubiquitous inlines aren’t always ubiquitous. The phrase “ubiquitous inlines” is dropped onto the page without definition or comment in the DB 5 TDG, and it is clearly a source of confusion. And yes, I did actually buy paper, PDF, and Kindle versions of the book from O’Reilly.]

From: Tim Arnold [mailto:Tim.Arnold@sas.com]
Sent: Tuesday, October 12, 2010 3:33 PM
To: docbook@lists.oasis-open.org
Subject: [docbook] invalid doc, but why?

Hi,

I have the following V5.0 docbook document and any validator tells me that the inner <optional> element is invalid. But where does that info come from? All I can see from the xsd file is that a <phrase> is legal inside an <optional> and an <optional> is legal inside a <phrase>.

Not questioning the validity, just trying to figure out where the rule is located.

thanks,

--Tim Arnold

<chapter xmlns="http://docbook.org/ns/docbook"

xml:id="test" version="5.0">

<info><title>my title</title></info>

<info><title>my section</title></info>

<para>

<optional><phrase><optional>maybe</optional></phrase>

</optional>

</para>

</section>

</chapter>

docbook message