[TYPO3-doc] DocBook: customizing the schema

[Thomas Schraitle]

Hi,

thanks Francois for starting this mail.

Friday 10 June 2011
> 
> On the road to having the first rendering done, there's one important
> step: customizing the DocBook schema that we use.
> 
> Indeed DocBook is very rich and we will not need every single tag. The
> schema customization lets us define tags that we don't use. This
> simplifies the life of editors, as it reduces the number of tags they
> are faced with while writing a manual. It also reduces the amount of
> work needed for setting up the rendering scripts, as we know what tags
> we don't need to worry about.
> 
> Tom already made a proposal [1] and started spelling out a list of do's
> and don'ts [2].

In my opinion it's an iterative process: first we start with a more or less 
"restrictive" customization and as time goes by, we will see if it is too 
restrictive. 

For example, I've started with the FLOW3 manual and experienced some things 
that I would consider as disadvantageous:

  * Block elements in <para>s,

  * bridgeheads, floating titles without any child structures. 

Both issues make XSLT processing harder to some extend, especially when it 
comes to customizing the DocBook XSL stylesheets. As such, I banned them from 
the RELAX NG schema. Both issues can be solved through some XSLT magic, by the 
way. You can find the modified version in our docu SVN[1].

Furthermore, we've discussed sect1 vs. section which we solved already: we 
decided for section.

Some open questions still persist:

1. How "restrictive" want we to be?

   There's always the tension between flexibility on the one side
   and consistency/strictness on the other side. Both have their 
   advantages and merits. 
   For example, it would be pretty to change the structure of a
   section so it always starts with a para after its title. However,
   maybe someone has good reasons to start with a warning? In that
   case it wouldn't be allowed.
   I think, this is more a style guide rather than a technical issue.


2. What should we do with semantical similar elements?

   For example, there is guilabel, guibutton, guimenu, guisubmenu, guiicon
   etc. All elements describe more or less the same; an object on a GUI. 
   Do we have to be really such specific? Or is it better we restrict the
   above collection to one or two elements?


3. Do we want to allow "foreign" DocBook vocabulary (like SVG or MathML)?

   That means, we can insert SVG graphics _directly_ inside any
   inlinemediaobject or mediaobject. Or we can use mathematical terms 
   using MathML inside an inlineequation or equation.
   In my opinion, this seems not to be an issue for TYPO3 manuals, is it?
   Do you ever thought of using "hand-made" SVG graphics or MathML 
   formulas?


4. Should we allow annotations?

   Annotations are pretty new in DocBook. They are introduced in version 5.
   With annotation you can attach additional information to an element.
   In PDF it is suppressed, but in online formats it can show an icon
   after the annotated element. When you click the icon, it will show
   a kind of popup with the annotation.
   I would recommend to remove them for the time being. If they are
   really needed, we can add them later.


5. What table model do we use?

   If I remember correctly, we favored the HTML table model instead of CALS.
   Is this still right?


6. Consistent Linking?

   DocBook 5 allows XLinks. They are present in almost all elements which
   means you do not need necessarily a special <link> element. In theory, 
   you can turn every element into a link using the xlink:href attribute.
   This adds more expressive power to our markup, but it's maybe harder to 
   understand. 
   Should we use explicitly <link> for our external links and disallow 
   XLinks? Again, consistency vs. flexibility.


I know, the above questions are very detailed. However, we should decide these 
questions _now_ as they influence the way we structure our TYPO3 manuals in 
the near future. They will also influence the design.

Remember, a good schema is only the basis. However, it doesn't necessarily 
mean all your documents are perfectly good. A writer still can use the "wrong" 
element,  disobey any style guide recommendations, or use an unfortunate 
structure. DocBook doesn't prevent you from doing this, nor the schema 
customization.
But a good schema allows a writer to get help what is allowed and what is not. 
A kind of "guided editing", a "contract". Not more, not less.

The process is documented in task #27364 on forge[2].

What do you think?


Tom

-------
[1] 
https://svn.typo3.org/TYPO3v4/Documentation/official_template/trunk/DocBook/flow3-
manual
[2] http://forge.typo3.org/issues/27364