[TYPO3-doc] DocBook: customizing the schema

[François Suter]

Hi Tom,

Thanks for your detailed posting.

> 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].

Sounds good.

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

Exactly.

> Some open questions still persist:
>
> 1. How "restrictive" want we to be?
>[snip]
>
> 2. What should we do with semantical similar elements?
> [snip]

Answering those 2 questions together: I think we should not be too 
restrictive. OTOH I think it's worth banning as many tags as possible to 
make editor's lives easier and the editing process less prone to 
mistakes. DocBook sometimes goes into a lot of details, which I don't 
think is necessary. Your example with all the "gui*" tags is a perfect 
one. With the sample manual I tried to use most of the tags that I think 
we would need, so I would take it as a basis for restrictions. Of 
course, this is open for discussion as I may well have missed some 
useful tag.

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

I don't know. I wouldn't expect math formulas to be necessary. SVG could 
be nice I guess, although our need for charts is pretty limited. Most of 
our pictures are screenshots. I suppose it's still possible to point to 
an SVG file, right?

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

I read quickly about the topic and I agree with you: let's leave them 
aside for now, we can always add them later on.

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

Yes.

> 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 would say that links are indeed easier to understand (and especially 
to keep an overview of). In the sample reference manual I also used xref 
tags. Is that related to your question?

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

Sure.

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

I understand and agree :-)

Cheers

-- 

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