Geraint North wrote: > (slightly off-topic as far as XXE goes - please let me know if there's > somewhere else more appropriate for discussions such as this) > > As I start to use Docbook in anger, there are a couple of things that I > miss in the spec that I've had to add myself, including two seemingly > generic ones: > > - Directory Tree Representations > > We often want to include example directory trees in our documentation. > I've added the obvious tags (directory, disk, file) that can nest in the > obvious way and include 'name' and 'description' tags. I've modified > the Docbook XSL stylesheets to produce, (IMVHO) stunningly beautiful > PDFs. :-) > > http://geraintnorth.com/docbook_directories.pdf
Gorgeous! > This seems too generic and useful to waste - how much hassle is it > likely to be for me to try and get these rolled into docbook? No idea. I've never customized DocBook 5 (and would not even attempt to customize DocBook 4). > - A profiling container for a set of para elements. > > Our product ships in a number of different platforms, and thus our > (mostly common) documentation uses profiling (with the arch attribute) > so that we can build each variant as required. Often, whole sections > are different (e.g. installation instructions vary between Linux and > Solaris versions of our product). > > Now, we can't do this: > > <section xml:id="Installation" arch = "Linux"> > <title>Installation</title> > <para>...</para> > <para>...</para> > <para>...</para> > </section> > > <section xml:id="Installation" arch = "Solaris"> > <title>Installation</title> > <para>...</para> > <para>...</para> > <para>...</para> > </section> > > ...because you can't have two elements with the same xml:id, but we need > the xml:id to be consistent so that our cross-references work cleanly. > > What I want to do is this: > > <section xml:id="Installation"> > <title>Installation</title> > <contentgroup arch = "Linux"> > <para>...</para> > <para>...</para> > <para>...</para> > </contentgroup> > > <contentgroup arch = "Solaris"> > <para>...</para> > <para>...</para> > <para>...</para> > </contentgroup> > </section> > > But as far as I can see, there is no <contentgroup> equivalent, so it > looks like we'll have to do this: > > <section xml:id="Installation"> > <title>Installation</title> > <para arch = "Linux">...</para> > <para arch = "Linux">...</para> > <para arch = "Linux">...</para> > <para arch = "Solaris">...</para> > <para arch = "Solaris">...</para> > <para arch = "Solaris">...</para> > </section> > > Which is cumbersome and likely to be bug-prone over time. Am I missing > anything in the docbook spec, or is there really nothing that fulfils > the requirements of my contentgroup? How do other people work around this? May be simplesect? http://www.docbook.org/tdg5/en/html/simplesect.html <section xml:id="Installation"> <simplesect arch = "Linux"> <title>Installation</title> <para>...</para> <para>...</para> <para>...</para> </simplesect> <simplesect arch = "Solaris"> <title>Installation</title> <para>...</para> <para>...</para> <para>...</para> </simplesect> </section>
