DOCBOOK-APPS: Re: Processing Instructions and structure

[Norman Walsh <ndw at nwalsh dot com>]

/ Bob Stayton <bobs@caldera.com> was heard to say:
| This scheme looks fine, but for me it
| raises a long-standing question I have about
| whether or how processing instructions fit into a
| document's structure.

They're just nodes.

| The XML Recommendation
| doesn't say anything out it.  If you look at your example:
|
|     <chapter>
|       <?dbhtml dir="chap1" filename="c.html"?>
|       <section>
|         <?dbhtml dir="sect1" filename="s.html"?>
|
| You have associated the PI dir="chap1" with <chapter> by
| putting it inside the chapter element.
| So the rule is that a PI applies to the element that
| contains it, I guess.  

There's no "XML rule" about PIs. They are semantically undefined. In
the DocBook stylesheets, I look for dbhtml and dbfo PIs as the direct
children of the elements on which they might be relevant.

| But that chapter PI is a sibling node of the <section> element,
| whose own PI dir="sect1" is expected to be "contained" in the previous
| PI to form the chap1/sect1/ path sequence.  That seems
| odd to me.

There's no contained relationship among the PIs, only among the
elements. The path components are now relative to "where you are"
rather than always being relative to the root of the tree.

So, processing the chapter effectively moves you into the "chap1"
directory. Subsequently processing the section, contained with in the
chapter, moves you into the "sect1" directory, relative to where the
chapter is, which means "chap1/sect1" relative to the root.

| So I guess the rule is that because <section>
| is contained in <chapter>, then the PIs in <section> are
| contained in the PIs of <chapter>.

Not in general, only for the "dir" psuedo-attribute. Basically, when
trying to figure out what dir to use, I walk back up the tree looking
at every dir at every level.

| I know, there is actually
| no such nesting of PIs in XML or SGML because they aren't
| part of the structure of elements, but effectively that is how
| you are forming the path, right?  

Right.

| Does the PI have to be at the beginning of the element
| to work, or can it be at the end?

As long as it's a child (I basically look for
./processing-instruction('dbhtml')), it doesn't matter.

| What happens when you have two PIs with different
| values for the same parameter in the same element?

The first one (in document order) that contains the psuedo-attribute
we're looking for is the one that gets used.

| This could happen by accident, and no validation
| process would catch it:

Right. At some point in the future, when SGML is long forgotten and everyone is
using fully namespace-aware scheme processors, it's going to make more sense
to use

  <chapter somenamespace:dir="chap1">

than a PI. But we aren't there yet.

| Does the first one win (like parameter entities)
| or the last one (like variables)?  Clearly the
| same chapter can't go into both places.

The first one. Just because I coded it that way, not again because
there's any sort of XML rule.

| Are the rules of PIs always set by the application
| (in this case, how the stylesheet interprests them)?

Yep.

| If that is the case, how do the DocBook stylesheets handle
| my perverse cases?

Badly? :-)

| I'm not raising these questions just to be frivolous.
| I've been tempted to use PIs for other purposes,
| but I've never quite understood how they apply
| within the structure of a document.   Any clarification
| you could provide would be appreciated.

They apply any way you decide to process them.

They were really hard to use in DSSSL because you couldn't match on
them. In XSLT, it's a lot easier.

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | More men become good through
http://www.oasis-open.org/docbook/ | practice than through
Chair, DocBook Technical Committee | nature.--Democritus of Abdera