[TYPO3-doc] About DocBook 5 Customization

[François Suter]

Hi,

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

Good to know. It could be useful indeed.

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

 From what I understand from DocBook (which is not yet much) internal 
links are not really problematic. Our issue is really with external 
links, i.e. linking across manuals, but also outside links pointing to 
manuals. This is in large part due to the current transformation to 
HTML, how speaking URLs are managed by TYPO3 and - more generally - the 
structure of the community site typo3.org.

The real headache we're having right now is that most of the time when a 
manual is generated the numbering of the chapters changes. This means 
that existing links are broken (plus the fact that the full URLs also 
contain the version of the manual, which doesn't help). So the problem 
is not strictly related to DocBook, but we're hoping that DocBook can 
help. In particular I was thinking that if we give "speaking" IDs to 
sections, these can be used when creating our speaking URLs rather than 
(potentially changing) numbers.

As an example, here's a link to the "doc_core_tsconfig" manual:

http://typo3.org/documentation/document-library/core-documentation/doc_core_tsconfig/4.3.2/view/1/6/

The problem with the version number must be handled on the TYPO3 side, 
but it would be much better if we could use more explicit keywords than 
"/1/6". This is probably something that needs to be solved on the TYPO3 
side too, but with information extracted from the DocBook files.

BTW I'm wondering how a full manual rendered to HTML would fit into the 
structure of typo3.org. Currently the manuals are cut into HTML "pages" 
that correspond to chapters. These "pages" are stored in a database 
table (AFAIK, I'm unsure about this part) and are served as content 
inside the site's template when requested. I'm not sure how this would 
be achieved after the DocBook migration. Could we have a rendering that 
splits the HTML into several files that would be equivalent to the 
"virtual pages" that we have now?

(I don't know if this is really clear for you :-/ )

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

Ah yes, quite obvious :-) I was looking for some "lang" tag...

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

I'm currently preparing a sample DocBook document based on our current 
template, so that we have a first example which should normally contain 
most of what we should need. I'm also using the FLOW3 (TYPO3's next 
generation PHP framework) documentation as a reference, as it seems 
quite clean and well structured.

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

Interesting. This makes sense IMO.

Cheers

-- 

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