[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]