OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Future DocBook Ruminations - Modular Source Files & XInclude



In the new DocBook can we find a more standardized and reliable way of
linking source files?

Here is my proposal for anyone interested to shoot at, with apologies if
someone has already suggested something similar which I haven't seen on the
list.

P1. All block-level elements except the topmost ('topmost' = <article>,
<book> etc.) have new companion elements defined with names like
<included-XXX>, e.g. <included-section>, <included-figure> etc.

P2. Grammar is changed such that wherever <XXX> is valid, <included-XXX> is
also valid.

P3. Grammar of each <included-XXX> element is defined to allow exactly one
child element which can be either the 'real' <XXX> element or an
<xs:include> element (or by virtue of P2 a nested <included-XXX>), e.g. in
DTD-like-syntax:

!ELEMENT included-section (section | xs:include | included-section)
!ELEMENT included-para (para | xs:include | included-para)
...

Here is an example which omits namespace declarations for clarity. File
section1.xml is in a subdirectory.

File section1.xml:
  <section>
    <title>Section 2</title>
    <para>...</para>
  </section>

File main.xml before XInclude expansion:
  <article>
    <section>
      <title>Section 1</title>
      <para>...</para>
    </section>
    <included-section>
      <xi:include href="section2.xml"/>
    </included-section>
  </article>
  
File main.xml after XInclude expansion:
  <article>
    <section>
      <title>Section 1</title>
      <para>...</para>
    </section>
    <included-section xml:base="subdir">
      <section>
        <title>Section 2</title>
        <para>...</para>
      </section>
    </included-section>
  </article>

The main advantages of this scheme which I see are:

A1. A validating parser will be happy with section1.xml by itself, main.xml
by itself AND main.xml after the XInclude has been expanded without any loss
of 'rigor' in the grammar constraints.

A2. All details about XInclude mechanics, e.g. xml:base attribute are
contained in the <included-XXX> elements and do not impact the main DocBook
grammar. Perhaps we can support other file linking standards here as well as
XInclude?

A3. Because the file linking mechanism is now explicit in the DocBook
grammar, users of syntax-directed editors will get some guidance about how
to put it in their documents.

A4. Customizing the grammar by removing certain <included-XXX> elements
permits a group of authors to constrain where in their documents' structure
"file breaks" are allowed, e.g. just for <section>s and <appendix>s.

Disadvantages are:

D1. Not all XML tools support XInclude.

D2. Stylesheets have to ignore any <included-XXX> elements they encounter
(apart from the xml:base attributes).

Modified Proposal

By weakening the grammar slightly this could also support more flexible
distribution of source material between files.

P3a. As P3, but change the definition of the <included-XXX> elements to
allow multiple children, e.g.

!ELEMENT included-section (section | xs:include | included-section)+
!ELEMENT included-para (para | xs:include | included-para)+
...

So now, this example would work:

File sections.xml:
  <included-section>
    <section>
      <title>Section 2</title>
      <para>...</para>
    </section>
    <section>
      <title>Section 3</title>
      <para>...</para>
    </section>
  </included-section>

File main.xml before XInclude expansion:
  <article>
    <section>
      <title>Section 1</title>
      <para>...</para>
    </section>
    <included-section>
      <xi:include href="sections.xml"/>
    </included-section>
  </article>
  
If you were being especially pedantic (which I'm not) you might now want to
rename the new element <included-section(s)>. AFAIK the only way to achieve
this sort of modularity with current DocBook is to use entities, which
presents all sorts of other problems. It's something I've been asked for
several times by authors on my team, although we've always managed to find
some sort of workaround. This modification weakens the grammar constraints
though, since for example the construction

  <included-XXX>
    <XXX/>
    <XXX/>
  </included-XXX>
  
allows multiple <XXX> elements to now occur where a maximum of one was
previously allowed.

Any thoughts?

Thanks,
Rob 



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]