[TYPO3-doc] About DocBook 5 Customization

[François Suter]

Hi Tom,

This is all very interesting. Your answers raise yet more questions ;-)

> Ok, here we go:
> * Internal links in DocBook-speak are usually<xref/>s (coming from cross-
> [snip]
> Internal links (xrefs) are checked during validation regardless of the schema.
> As you know, each ID can occur only once in the whole document.

OK, clear enough.

> * External links in DocBook-speak are usually<link>s. Interestingly, DocBook5
> allows not only<link>  elements as external links. Each(!) element can be
> turned into a "hot link" using the XLink syntax. For example:

Looks cool.

>    <link xlink:href="http://www.w3.org/1999/xlink"
>      >XML Linking Language (XLink)</link>
>
> the previous link can also be written with citetitle:
>
>    <citetitle xlink:href="http://www.w3.org/1999/xlink"
>      >XML Linking Language (XLink)</citetitle>

Funnily enough XMLMind allows only the latter. I found it impossible to 
define a xlink:href attribute on a link tag. That would seem to be a bug...

> Your problems remind me of the current structure of our manuals. We use a
> structure like this (simplified for the sake of simplicity):
>
>    set
>      book xml:id=book.quick  # Quick Starts
>        article
>        article
>      book xml:id=book.user   # User Guide
>        preface
>        chapter
>        ...
>      book xml:id=book.admin  # Admin Guide
>        preface
>        chapter
>
> In the above structure, we can create a<xref/>  from deep inside book.user to
> some chapter or section in book.admin. As this is a _complete_ document, the
> <xref/>s are checked and correctly resolved. Numbers are preserved.

This is really interesting. However does it mean that all the books have 
to be "in the same place"? I mean that right now we have a number of 
official manuals for TYPO3 v4, which are somewhere in our main SVN 
repository. For TYPO3 v5/FLOW3 the manuals are - for the time being - 
inside each Package (the whole thing structured purely in packages). 
Would all these manuals have to be brought under the same file hierarchy 
in order to group them into a single set?

BTW can any tag be included using xi:include? I'm thinking here of 
books, in particular, which could then be made to belong to several sets.

Since xi:include can use absolute URLs, it should be possible to include 
books from many different "places", right (hmm, I seem to be answering 
my own question, but I've googled in the meantime ;-) )? As long as we 
have a consistent rule for IDs, we shouldn't run into problems. Is that 
right?

> The DocBook stylesheet allows to process only a part of the document, for
> example, only the User Guide.

Right.

> Disadvantage: IDs can only be used once in the whole set. This may be
> problematic when dealing with a more "topic oriented" approach when you
> shuffle around your chapters, section, etc. to form a new manual.

Indeed it can introduce some overhead in managing IDs, but it's just as 
well if we have a well-defined convention for all manuals. It will make 
cross-linking easier, so it's worth the effort.

> This can be solved really easily by DocBook. For example, let's assume you
> have a chapter with this ID:
>
>    <chapter xml:id="cha.typo3.introduction">
>
> You can control the filename with a stylesheet parameter. This turns the ID
> value into a filename: cha.typo3.introduction.html. It is also possible to
> create individual HTML filenames.

That sounds really good.

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

Great.

More questions to come, but maybe I'll open a new thread then.

Cheers

-- 

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