This is the mail archive of the mailing list for the DocBook project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [docbook] Future DocBook Ruminations - Modular Source Files & XInclude

Hi Robert,

You wrote:

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

But DocBook itself doesn't currently provide any means at all for
marking up what you're suggesting (referenced file inclusions).

It seems like what you want is a class of markup that DocBook itself, by
design and for good reasons, doesn't currently provide at all: a way to
mark up the physical file-organization of your content, instead of just
the logical content.

Don't the already-standardized ways that we have for marking up the
physical file-organization of document content -- using Xinclude and
general entities -- exist to prevent the need for what you're proposing
(adding markup for physical structure the grammar/schema level)?

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

You haven't really described what problems your proposal is meant to
solve -- what the intended goal is. It seems like it's mainly to avoid
the need to use general entities, and to work around the fact that most
validating editors will treat Xinclude elements as invalid unless
they're declared in the grammar. Is that right?

If you and the authors on your team were using editing and processing
apps that could process Xincludes correctly (that is, without them
needing to be declared in the grammar), would you still think it was
necessary or worthwhile to make this change to DocBook?

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

I probably don't need to tell you that a lot of users might consider
doubling the number of block-level elements to be a bit of an
ease-of-use concern.


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

But the scheme still depends on you having some mechanism for resolving
the Xincludes, right? If that's the case, you'd be just as well off if
you had a bare Xinclude (without the <included-section> wrapper in
there), right? I can't see that this scheme is gaining you anything as
far as validation is concerned, unless you've got an app somewhere in
your toolchain that doesn't understand Xinclude. If that's the case, it
seems like the better solution would be to either add Xinclude support
to that app, or replace it with an Xinclude-aware app.

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

What other such standards are there, and why would anybody need them if
they had Xinclude support? Regardless, whatever there might be, wouldn't
it make a lote more sense to add such include support at the application
level instead of trying to add it to DocBook?

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

Huh? How would it give any more guidance then they would get from any
application that provided a mechanism for easily specifying a file
reference (e.g., a menu item the opens up Browse for File dialog that
lets them choose the file the Xinclude element should reference)?

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

I can see some value in that. But attempting to provide a means for
defining contraints on the physical file-organization content has never
been something DocBook was intended to do. It's for logical markup.

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

Doubling the number of block-level elements might also be a seen as a
bit of a disadvantage.

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

What's wrong with using Xinclude instead of entities? Are you saying
that entities enable some higher level of physical modularity than what
Xinclude provides?

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

What kind of workarounds, and what deficiencies were they meant to work
around? It doesn't seem like they could be workarounds for shortcomings
in DocBook itself, because it's intended by design to be used for adding
logical markup to your content, not for specifying anything about
physical file-organization.

If your workarounds are to deal problems with the way your current
applications handle entities and Xincludes, it really seems like it'd
make a lot more sense to fix your applications instead of trying to
build workarounds into the schema you use.

> 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 

Attachment: pgp00000.pgp
Description: PGP signature

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]