[TYPO3-doc] About DocBook 5 Customization

[Sebastian Kurfürst]

Hey,

> Internal links (xrefs) are checked during validation regardless of the schema. 
> As you know, each ID can occur only once in the whole document.
Exactly, that's why I wanted to higlight this point as well: Do you have
any convention for using / assigning IDs? I think it'd be important to
have some good structure how these IDs should be built, like for example
"TYPO3v4.UserGuide.Introduction" <-- ID of the Chapter "Introduction" of
the book "UserGuide" of the set "TYPO3v4".

Maybe we can create some automatic XSLT script which can auto-number
these IDs for the first time, do you think that makes sense?

> Your problems remind me of the current structure of our manuals. We use a 
> structure like this (simplified for the sake of simplicity):
I would also suggest the same structure :-)

> This is mostly done by the chunking process of the DocBook HTML stylesheets. 
> You can define at which level a new chunk is created. For example, you can say 
> you want it at the chapter level, or at each section 1 level, or ...
Exactly, and as we are also displaying the HTML files on
http://flow3.typo3.org/documentation/manuals/flow3/ we just have a slim
extension which outputs the pre-rendered files.

>>> 1. Which block elements do you need (especially sectX vs. section)?
The most important ones are in my opinion:
* section
* para
* chapter / set / ...
* itemizedlist / procedure (itemized / numeric list)
* programlisting
* example
* sidebar
* tip / warning / note

We do NOT need:
sectX

I think we need the following inline styles:
* emphasis -- highlighing
* code -- inline code
* remark -- comment which is not printed, should be used for reviews, or
TODOs, etc...
* methodname / classname -- method or class names
* filename -- file or directory name
* replaceable -- used inside code or programlisting to denote user input
* footnote -- place a foot note

Additionally, I think we definitely need "callouts", which can be used
to annotate program listings -- so we need "co" and "calloutlist"

>>> 2. Should content models can be simplified?
>>> 3. Which inline elements do you need?
see above :)

>>> 4. Can para be simplified?
Yes, I would disallow things like
 <para>Some text ...
    <figure> ... </figure> <!-- a block element -->
    Another text <filename>x</filename> <!-- an inline element -->
    <example> ... </example> <!-- another block element -->
  </para>
and only allow the more "flat" syntax.

However, I think it is important that <example> can contain sub
elements, so stuff like:
<example>
  <para>...</para>
  <programlisting> ....</programlisting>
  <calloutlist>...</calloutlist>
</example>
should be possible.

@Thomas: I'd be very courious what you are using as Rendering Pipeline.
I have been using http://fusesource.org/forge/projects/FORGEDP - but it
does not seem that well maintained. Do you have a special package for that?

... long discussion, I hope I made some points and you could understand
me ... :-)

Greets,
Sebastian