[TYPO3-doc] About DocBook 5 Customization

[François Suter]

Hi Tom,

Nice to read you here. Welcome to our community :-)

> Hi Typo3 Doc Team,

BTW, it's "TYPO3", not "Typo3". I'm sure you're used to such finer 
details ;-)

> 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:

Thanks for listing those pros and cons. I have read the DocBook 5 
Definitive Guide in the meantime (well, not the reference part...) and 
it says pretty much the same, so I'm pretty well aware of the pitfalls. 
Currently I don't see any need to introduce new elements. What we have 
been discussing up to now as far as customization is concerned is about 
removing unneeded elements to simplify editors' lives. Such changes seem 
pretty innocuous, right?

> 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)

Good that you raise this point, as it was on my list of questions to you ;-)

As fas as I can tell, the advantage of sect1, sect2, etc. is that they 
are logically nested and that it would be possible to limit the level of 
nesting. However "section" is more flexible and I don't think that we 
need to "hard-code" a nesting limit (it's more like a guideline such as 
"If you need too much nesting, maybe you should restructure your 
document"). What's your advice? You seem to be rather in favor of 
"section"? If we go for sections, can we then safely drop sect1 et al.?

> Maybe this example looks a bit artificial 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. :)

Your input is more than welcome.

Cheers

-- 

Francois Suter
Cobweb Development Sarl - http://www.cobweb.ch