DOCBOOK-APPS: Processing Instructions and structure

[Bob Stayton <bobs at caldera dot com>]

I'm branching the subject here, hence the new Subject line.

On Mon, Mar 25, 2002 at 04:34:52PM -0500, Norman Walsh wrote:
> / Jeff Beal <jeff.beal@ansys.com> was heard to say:
> | I was hoping I was missing some little trick that would make everything
> | magically work.  Alas . . .
> 
> If you're interested in this feature, please download 1.50.1-EXP and
> give it a try. I believe that I've fixed the code so that it will
> properly handle references across chunks in different directories.
> I also don't think I've broken anything :-)
> 
> The following restrictions apply:
> 
> 1. Directory levels are cumulative. Given:
> 
>    <book>
>    <?book filename="b.html"?>
>    <chapter>
>      <?dbhtml dir="chap1" filename="c.html"?>
>      <section>
>        <?dbhtml dir="sect1" filename="s.html"?>
>      ...
> 
>    b.html will go in the current directory
>    c.html will go in chap1/
>    s.html will go in chap1/sect1/
> 
> 2. You must not use absolute path names.
> 3. You must not use "../" in any path name.
 

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.  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.  

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.

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>.  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?  

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

    <chapter>
      ...
      <?dbhtml dir="chap1" filename="c.html"?>
    </chapter>

What happens when you have two PIs with different
values for the same parameter in the same element?
This could happen by accident, and no validation
process would catch it:

    <chapter>
      <?dbhtml dir="chap1" filename="c.html"?>
      <section>
        ...
      </section>
      <?dbhtml dir="chap2" filename="d.html"?>
      <section>
        ...
      </section>
    </chapter>

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

Are the rules of PIs always set by the application
(in this case, how the stylesheet interprests them)?
If that is the case, how do the DocBook stylesheets handle
my perverse cases?

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.


Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
Caldera International, Inc.                 fax:   (831) 429-1887
                                            email: bobs@caldera.com