[TYPO3-doc] About DocBook 5 Customization

[Thomas Schraitle]

Hi Typo3 Doc Team,

thanks to François I've got involved somehow in the DocBook migration for 
Typo3. :) As most people probably don't know me let me give you a short 
introduction: I'm a writer and stylesheet developer for the openSUSE manuals 
and work with DocBook for some years now.

I've read some of the meeting minutes and other material but probably not 
enough to get a complete overview. So please bear with me if I'll write about 
something that is already clear to you. :)

I've got the impression there is a need to customize the DocBook5 schema. This 
is fine and I would like to add some points to the whole picture.  I thought, 
it might be a good idea to summarize some of the benefits and drawbacks 
enriched with some experiences:

Advantages of Customizing DocBook
 - Content modells can be simplified or restricted
 - New elements can be introduced
 - Attribut values can have default values or values which make more sense
 - Other schemas can be incorporated (MathML, SVG, ...)
 - Customizing of RELAX NG is simple and fun! ;)

Disadvantages of Customizing DocBook
 - If you change DocBook, it’s not DocBook anymore
 - New elements needs to be adressed in the stylesheets too
 - Sharing of documents could be more difficult as the recipient needs also
   the customization file
 - Tools support

The points above may be more or less important for you. Before I customize 
DocBook, I follow these rules when adding a new element:

 1. Do I really need it?
 2. If yes, is there a similar DocBook element already available? 
    Maybe a class or role attribute can be (ab)used for this task.
    For example, a report element can be addressed as article with
    class="report".
    - Advantage:  No customization layer for the DocBook stylesheets needed
    - Disadvantage: There might be situations where you really want a 
      report element, for example, you want a complete other handling
      and the DocBook stylesheets would interfere here
 3. If yes and there is no similar DocBook element, I'll add it.

I think, one of the bigger disadvantages is the need to implement templates 
for new elements in the stylesheets. Depending on what you've changed this 
task can be challenging -- especially if you want to support different output 
formats. Think of maintaining it. 

Another issue, not necessarily a problem of DocBook customization itself, is 
the tension between simplicity and flexibility. Let me give you a short 
example which can also be problematic when removing elements. DocBook supports 
two types of section elements:

 * sect1, sect2, sect3, ...
 * section (recursively nested)

Let's assume you only allow the first type (sectX). This is "simple" for your 
authors as they directly see the level of your nested structure. 

On the other side, there is a need for flexibility. For example, one author 
wants to reuse a section into another book. How can this be achieved if the 
subsection starts as sect2, but a sect1 level is needed? Our author would need 
a section element for this task as they can be nested.

So the question is here: how does my document structure looks like? What 
section types do I need here? Which levels want I allow? How can I restrict 
these rules?

Maybe this example looks a bit artifical for you. Nevertheless I hope I could 
demonstrate some problems that goes beyond simple DocBook customization. My 
intention was not to make your job more complicated but just to give you 
something to think for your customization task. :)



Thanks,
  Tom