[TYPO3-doc] Explaining Customization for TYPO3 DocBook Schema

[Thomas Schraitle]

Hi,

after contemplating about an answer for Francois' last post, I thought I write 
my ideas better in another post. Unfortunately, this post got a bit longer 
than expected. My intention was to give you some background information what 
this fuzz is all about. ;)

1. Background
As you know, DocBook 5 is pretty big (around 350 elements). DocBook started 
with a small set and as time went by, the DocBook committee added more and 
more elements. These elements cover a broad set of different purposes. In most 
cases, this is enough to cover what you need for good software or hardware 
documentation.


2. Flexibility vs. Consistency
As DocBook 5 is very flexible, as documentation must be very flexible. DocBook 
offers sometimes different methods to use it. Think of the sect1 versus 
section discussion. Both methods are ok and both have their advantages and 
disadvantages. However, as always, with great freedom comes great 
responsibility.

Flexibility means also inconsistency to some extend. This is just natural and   
per se not really bad, but *can* make processing more difficult: you have to 
consider more combinations. Unfortunately, this affects other topics as well 
from designing (what Sabine does) to stylesheet programming. So, if we limit 
flexiblity we reduce also variations and the likelihood of errors.


3. Flexibility vs. Strictness
Apart from the previous considerations, the most important reasons for 
limiting the amount of elements are you, the writers. Why offering elements 
which are never used in the TYPO3 documentation? Less elements are always 
easier to remember and to use.

However, we've seen some good reasons to restrict flexibility. Schema design 
(or customization in our case) has to solve the two conflicting factors: 
flexiblity versus strictness. A very strict schema is very consistent, however 
not very flexible. And also probably not very fun to use. ;) I guess, as TYPO3 
has a very broad spectrum of documentation, the schema can not be very strict.


4. What Does That Mean to TYPO3 Documentation?
Ok, a schema which is too flexible is not optimal and a schema which is too 
strict isn't either. You guessed it: The optimum is in between. But how can we 
do that?

The answer is simple, but maybe not satisfying: through experience and 
iteration. In my company I've created a customization that contained a tiny 
subset of the original DocBook DTD. However, after some time, there was the 
need to use more elements to cover a specific need ("Why can't I add this?", 
"How do I do this?")

Therefore I would recommend to start with the "limited" version, which can be 
found in the file typo3.rnc[1]. Maybe we have to remove some elements, maybe 
we have to readd others. After some time, it should be frozen and changes 
should be inserted only carefully.


5. The Gory, Technical Details
The customization itself is amazingly simple. DocBook 5 has a consistent 
naming convention. An element definition, let's say for element <phone>, lies 
in the pattern db.phone. If you don't want it, just add the following line:

   db.phone = notAllowed

That's it! How easy is that?! :) This line removes any occurance of the phone 
element. The current typo3.rnc[1] file contains mostly of such lines.

I also applied two simple rules: (1) don't invent new elements, and (2) stay 
always compatible with DocBook. Removing elements is not a problem, same for 
attributes. Problematic can be changed or rewritten structures. That would 
violete rule 2.
With this simple rules, every TYPO3 documentation which is based on this 
customization could also be validated with the original DocBook schema.


6. Next Steps
I'm not sure if someone else started a similar initiative. The only way to 
find out if this customization is useful or not is to try it. If someone is 
brave enough, maybe download the directory of [1] and try to write a simple 
documentation. Let me know of your experiences, so we can discuss shortcomings 
or pitfalls.


What do you think? Hope to hear from you! :-)


Thanks,
  Tom


-------------
[1] 
https://svn.typo3.org/TYPO3v4/Documentation/official_template/trunk/DocBook/docbook51b2/typo3.rnc