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


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

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

Subject: having good success with xinclude's and building modular manuals

  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.


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