[TYPO3-doc] About DocBook 5 Customization

[Thomas Schraitle]

Hi Sebastian,

Tuesday 14 December 2010
> > [... 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".

Any convention is good if it is consistent. :) Usually I follow these rules of 
thumb:

* Avoid numbers like "chapter1" as they are not stable enough; a chapter 1 can 
occur as "chapter15" and you need to fix all IDs and references to it.

* Don't translate IDs. ID works as a "stable anchor" so it is easier to 
recognize the same chapter in different languages.

* Stay with English names for your IDs. That has two reasons for it: You are 
restricted to the ASCII character set and it is a common language.

* Uppercase or lowercase? That's up to you. Generally I use lowercase as it is 
easier and faster to type. 

These are my rules and I don't know if they work for you. However, they've 
worked for some years now.

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

I would avoid numbers in IDs at all. As written in my previous paragraph, 
numbers change too often and are not stable.

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

Exactly! IMHO remarks are _very_ important, because you can switch off the 
remarks during processing.


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

They are very convenient.


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

I consider that as a good idea. :)

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

That's already the case in DocBook 5. See the content model in TDG:
http://docbook.org/tdg51/en/html/example.html

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

I've read about it, but never used it.


> Do you have a special package for that?

Actually I have two "rendering processes": one for my book and one for the 
official openSUSE manuals. They don't share code, only a brain. ;)

My book is just a collection of self-written Shell and Python scripts which 
does nothing fancy. :)

For the openSUSE part: well, that is a bit more complicated as our text 
contains lots of profiling (aka "conditional text" see [1]). We use the 
susedoc package which is maintained by us. Find the source code on BerliOS[2]. 
It's all GPL, but at the moment DocBook 4 only.

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

Perfectly! I hope what I've written is somehow useful. :)



Cheers,
  Tom


--- References
[1] http://www.sagehill.net/docbookxsl/Profiling.html
[2] https://developer.berlios.de/projects/opensuse-doc/