[TYPO3-doc] DocBook: repository structure and release processes

[Thomas Schraitle]

Hi François,

today my vacation begins so I can give only limited answers, unfortunately.

Sunday 27 February 2011

> [...]
> >   (2) Use <link>s. This *may* be an alternative, if you can ensure stable
> >   URLs
> > 
> > or know them in advance.
> 
> That doesn't sound very safe indeed ;-)

Well, depends. ;) I assume you control your TYPO3 domain, so it shouldn't be a 
problem to create a stable structure for documentation on your server. 
Regardless of xrefs and the like, I would also evalute this option.


> >   (3) Use<olink>s. This is a method which is developed just for this
> >   purpose.
> > 
> > However, I never liked it much as it involves some intermediate steps and
> > makes it complicate on its own. Find more information here:
> > http://www.sagehill.net/docbookxsl/Olinking.html
> 
> Quite a bit of additional work, but very interesting. Maybe we don't
> need to look at this in the first step, but I don't see (from what you
> described so far) an alternative method to make it possible to
> cross-link safely between books. While this method requires careful
> setup on the documentation server, it's not so complicated to use for
> editors.

Yes, it's interesting and needs some careful investigation.

I forgot to tell you there might be an additional option. You can use <xref/> 
as much as you want even link into other books. During transformation from 
DocBook into your target format, the <xref/>s to other books will be replaced 
with ordenary text or with <link>s.

This method has the advantage that the author can use *one* method of cross 
referencing. The author doesn't have to distinguish between the different 
cross references. The build process takes care of evaluating and resolving it.


> > I've committed the file set.xml which contains some examples (not
> > necessarily related to your structure, but partly influenced).
> > 
> > Ok, François, here is your homework. ;)
> > I think, it's better if you try and see the result yourself. Transform
> > the set.xml to XHTML with the following command: 
> > [...]
> > Looking at set.xml, the book element contains the ID "t3.admin". Run the
> > command with the rootid parameter 
> > [...]
> > Compare the two rendered XHTML files.
> 
> Hmm. Interesting. As you explained earlier with cross-references across
> books, the link to another book in admin.html is broken.

Well, yes. However, I only showed you a small part of the picture. :) The 
previous command wrote everything in _one_ file. Now we can climb another step 
of the ladder and I want to introduce "chunking".

The DocBook stylesheets can split your document into several (X)HTML files. 
This process is called "chunking" and can be influenced through  parameters. 
The simplest command would be the following:

 DB=PATH/TO/YOUR/DOCBOOK/STYLESHEETS
 $ xsltproc $DB/xhtml/chunk.xsl set.xml

(See the different XSLT stylesheet name: chunk.xsl instead of docbook.xsl). 
This gives you the following output:

Writing bk01ar01s02.html for sect1
Writing bk01ar01.html for article
Writing bk01ar02.html for article
Writing bk01ix01.html for index
Writing bk01.html for book(t3.tut)
Writing bk02pr01.html for preface
Writing bk02ch01.html for chapter
Writing bk02ch02.html for chapter
Writing bk02ch03.html for chapter
Writing bk02ch04.html for chapter
Writing bk02ix01.html for index
Writing bk02.html for book(t3.inst)
Writing bk03pr01.html for preface
Writing bk03ch01.html for chapter(t3.admin.maintaining)
Writing bk03ch02.html for chapter
Writing bk03ix01.html for index
Writing bk03.html for book(t3.admin)
Writing bk04pr01.html for preface
Writing bk04rn01re01.html for refentry
Writing bk04rn01.html for reference
Writing bk04ix01.html for index
Writing bk04.html for book(t3.dev)
Writing si01.html for setindex
Writing index.html for set

However, I wouldn't recommend this. The filenames contain some numbers which 
are not stable when you remove or add chapters or sections. To create stable 
filenames you can use the ID of your chapter, section, etc. Use the parameter 
use.id.as.filename:

 $ xsltproc --stringparam use.id.as.filename 1 $DB/xhtml/chunk.xsl set.xml
Writing bk01ar01s02.html for sect1                                                                                          
Writing bk01ar01.html for article
Writing bk01ar02.html for article
Writing bk01ix01.html for index
Writing t3.tut.html for book(t3.tut)
[...]

As you can see, bk01.html is now named as t3.tut.html, the name of the ID with 
the .html extension. As the articles don't have any xml:id attributes, they 
will be named as before. 

Ok, back to your linking problem. Combined with the rootid, it's possible to 
just generate one book, and create the other later. As long as the structure 
and IDs are intact, the linking to other books will work.


Unfortunately, I have to prepare my vacation now. Here are some links to 
further information which (hopefully) helps you with this topic:

More information can be found here:
  http://www.sagehill.net/docbookxsl/Chunking.html

Here is a complete list of all parameters about chunking:
  http://docbook.sourceforge.net/release/xsl/current/doc/html/chunking.html



> [...]


Cheers,
  Tom