Re: DOCBOOK: DocBook-XML and conditional sections

[Norman Walsh <ndw at nwalsh dot com>]

/ Stephane Bortzmeyer <bortzmeyer@debian.org> was heard to say:
| [Please Cc: me replies, the turnaround time of the list is a bit slow for me.]

[What sorts of delays are you experiencing? Turnaround time should be
no more than 12-24 hours. --mod]

| 1) A non-SGML solution: Using a preprocessor like M4. This will make 
| operations like validation more complicated and it will certainly confuse 
| Emacs' SGML mode.

Or you could use an SGML solution :-), as opposed to an XML
solution, and use conditional sections. Just preprocess the
"XML" documents before distributing them. Since you're using
Jade, I don't think you'd actually have any trouble.

| 2) A DocBook-customization solution: Creating new elements <version2.1> and 
| <version2.2> and write a custom stylesheet (I use DSSSL) which will 
| (process-children) or not, depending on a variable I give. The problem is that 
| I would like to have them in many places, because I want to "conditionalize" 
| entire sections, paragraphs, bits of paragraphs, etc. I tried to write a 
| custom DTD with such elements and it is far from obvious.

This would be really, really hard.

| 3) Adding an attribute to the elements I want to conditionalize (many!). 
| 
| <sect2 id="booting" version="version2.2">
| 
| and customize the stylesheet to use it. I never added attributes in DocBook, 
| but it seems simple by defining local.common.attrib.

There are already about five attributes for this purpose. You might get
away with using one of them: Arch, Conformance, OS, UserLevel, and Vendor.
DocBook 3.2 will add Condition and Security.

| Advices? Experiences?

The biggest problem with using conditional sections is that the
"ignored" parts are not seen by the parser, so you can't
validate them.

The biggest problem with using attributes is that the "ignored"
parts are seen by the parser, so you can't (easily) duplicate
required structures like title. Instead you have to do yucky
things like:

  <title><phrase arch="X86">Frobbing your X86 Processor</phrase>
    <phrase arch="PPC">Frobbing your PowerPC Processor</phrase>
  </title>

I think your best bet for XML is to use the effectivity
attributes, although it's a far from perfect solution,
clearly. You may want a customization layer that makes them
enumerated lists, however, rather than CDATA so that you can
validate that you haven't made any typos.

                                        Cheers,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Fast. Cheap. Well. Pick two.
http://www.oasis-open.org/docbook/ | 
Member, DocBook Editorial Board    |