Re: [docbook-apps] having good success with xinclude's and building modular manuals

[Bob Stayton <bobs at sco dot com>]

On Tue, Sep 02, 2003 at 08:59:33AM -0400, Robert P. J. Day wrote:
> 
> 
>   based on the advice i've been getting here regarding using
> xinclude's to create modular manuals, things are going well --
> i've got a small, modular manual being pulled together nicely
> from modules in various subdirectories.  i haven't finished the
> entire processing sequence, but it's coming along.  so, for now,
> some observations and a couple of questions.
> 
>   first, since i'm writing the modules in my pidgin docbook, i
> don't even bother adding a DOCTYPE to those modules.  not much
> point since there's no DTD for that stuff.  what i do is pull
> together the modules in a single large document, *then* run
> it through a stylesheet to generate valid docbook, which i can
> validate later.  i'm assuming that there's no immediate drawback
> to this; in short, i'm using "xsltproc --xinclude" simply to 
> build a large single file out of the module files.  thoughts?
> 
>   also, since the module files themselves aren't validated,
> i can invent a new tag for those modules, so each of those
> files has a "module" document element, which is how i refer to
> them in the actual xinclude's.  i realize i had the flexibility
> to call them "section"s, but since those modules could potentially
> end up as chapters, that seemed possibly misleading.  calling them
> "module"s seemed suitably generic and, again, it's doable since
> i'm not doing any validation at that level, and the <module> tag
> will be transformed to the appropriate <chapter> or <section>
> tag long before validation, based on its inclusion in the document.
> 
>   finally, generating the single, large pidgin docbook file
> creates a file with the top-level <book> element with an
> "xmlns:xi" attribute (due to the use of xinclude), as well as
> numerous lower-level elements with the "xml:base" attribute.
> given that i'm interested only in treating the resulting file as
> one large text file from this point on, is there any value in
> keeping those attributes?  i could trivially strip them out
> in the first processing step, as i don't see what i would use
> them for later, at least at the moment.  (I'm not doing any
> linking between the modules, at least not yet.)  
> 
>   any thoughts on the above, given how egregiously i'm 
> violating most of the rules of proper processing? :-)  i realize
> i could do things more properly if i defined a DTD for my pidgin
> grammar, but at the moment, there doesn't seem to be a lot of
> value in that.

Just one comment.
Eliminating the xml:base attributes might be a 
problem if your modules use relative path references
to graphics or other inclusions.  The xml:base
attribute records where each module's base address
is so that such relative references can be resolved in the
main document (the stylesheet would have to take action
on the xml:base attribute to do so).

-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: bobs@sco.com

To unsubscribe from this list, send a post to docbook-apps-unsubscribe@lists.oasis-open.org.