[TYPO3-doc] About DocBook 5 Customization

[Thomas Schraitle]

Hi Daniel,

> you're welcome here, very nice that you help us with DocBook! Some years ago
> I bought your book from SuSE PRESS "Medienneutrales und plattformunabhängiges 
> Publizieren" for docbook 4.x and it was a big help to me. 

Wow, thanks! :)
As you probably know already: the 2nd edition is available for some time now. 
It covers DocBook5 and other nifty features from the DocBook world. Including 
a new layout with lots of text improvements, of course.
Ok, enough advertisment. :) *cough*


> Now we have a big task here to move with thousands of users and thousands 
> of manuals to DocBook. We want to avoid getting into one-way-streets and give 
> the manual writers of TYPO3-extensions a good feeling when writing documentation.

This is indeed a challenging task.


>Our next step is indeed to define the subset of DocBook XML we need here for TYPO3. 
> For us it's three topics what are special
>- Source code snippets in a bunch of types like <example>...</programlisting></example>, 
> SQL, CSS, JavaScript

What is special about your source code? Is it highlighted in some way?
There are some DocBook stylesheets which do exactly this.


>- Dividing big manuals in small parts what can be combined together (e.g. the 
> TSref manual is very big)

Lately I've used dbautosplit, a Perl script which splits a DocBook document into smaller
chunks. It is not perfect, but it does its job pretty well.
If you have migrated your legacy documents into DocBook 5 this could be
useful.


>- Much linking between manuals and to URIs outside (the problem is often broken 
> links because of changed URIs)

Yes, linking can be a pain. Are you talking about internal or external links?

Our openSUSE manuals has a similar issue when referencing from one manual
into another. The DocBook way is usually to use an olink element, but this is
a bit too complicated. So we've integrated our books into a set and use xref
to create our "inter-book-links". It is not perfect as well, but in some way
a bit simpler. For inspiration, look at our project at BerliOS:
https://developer.berlios.de/projects/opensuse-doc/


>That would give us the possibility to make the search better and do highlighting
> using geshi, and dividing big manuals make it easier to maintain in a team. 
> That also can be a great base for eLearning for new TYPO users.

Yes, that's ture. If you are interested in eLearning, there is an initiative which
makes DocBook usable for such realm. But as far as I know, it's work
in progress, so nothing really finished.


>A nice-to-have would be
>- Tagging of content (to show a tagcloud and maybe to add "see also" links)

Tagclouds... hmn, maybe you can use something like info/keywordset. 
"See also" links are probably left as a customization in the DocBook stylesheet. 


>- several user languages (de_DE, en_US, fr_FR) within one document

Use the xml:lang attribute. This is available in all elements.


>So you see we have much what we think of before we really start, and we're 
> very happy that you share our way. In which way would you prefer that we
> implement that features?

What do you mean with "which way"? Do you mean it technical-wise or
project-wise, or...?

As I don't have this deep knowledge about TYPO3 than you, I'm hardly 
qualified for good recommendations. For this reason I'm writing a list of
questions:

1. Which block elements do you need (especially sectX vs. section)?
2. Should content models can be simplified?
3. Which inline elements do you need?
4. Can para be simplified?

Especially the last item should be a bit explained:
DocBook distinguish between block and inline elements. Block
elements can be figure, screen, table, etc. whereas inline elements
can be filename, code, author, etc.

For some reasons (which is unimportant for this mail) DocBook
allows block elements also in paragraphs. This is a bit unfortunate
as this can lead to a mixture of text, inline-, and block elements
inside the para element. This makes it harder for stylesheet
writers. I don't really like this mixture as I prefer to have 
inline + text and block elements nicely separated.

To make my verbose sentence a bit clearer, here is the essence
in some lines of code:

  <para>Some text ...
    <figure> ... </figure> <!-- a block element -->
    Another text <filename>x</filename> <!-- an inline element -->
    <example> ... </example> <!-- another block element -->
  </para>

I prefer this style:

  <para>Some text... </para>
  <figure>...</figure>
  <para>Another text <filename>x</filename></para>
  <example>...</example>

I'm not sure if this is important for you, but if you don't restrict it, writers
will use it. This leads to inconsistencies which should be avoided.


>:: Daniel Brüßler - 90489 Nürnberg

Hey, Nürnbercher! :-D


Thanks,
Tom