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

[Thomas Schraitle]

Hi François,

Tuesday 22 February 2011
> [...]
> same hierarchy, maybe through the use of SVN:externals or its Git
> equivalent (hoping there's one).

Maybe it's out of scope for this discussion, but I thought it might be 
interesting to some degree. 

We use SVN for our documentation. Every file of our documents contains a set 
of (SVN) properties. They contain the maintainer of the file, an editing 
state, a deadline, its priority, and if the file needs to be translated. With 
this method we can collect all the revelvant information for a book and have a 
nice overview about how far we are ("is person X still editing his file A?")

As far as I know, Git doesn't know properties.


> 2) what is the exact implication of having a global set? I imagine that
> all books would be referenced using includes, but I guess they still
> need to be in the same file hierarchy.

Not necessarily. A XInclude looks something like this:

 <xi:include href="URI" xmlns:xi="..."/>

The placeholder URI can contain almost everything what you need: a relative 
path ("foo.xml"), an URL ("http://example.org/foo.xml"), or an URN ("urn:x-
typo3:foo"). The latter needs to be resolved, usually through XML catalogs.
Are you familar with XML catalogs?


> What's the implication on the file structure?

You have to distinguish between the logical structure of your document and the 
physical structure. They don't have to match. See the following URL for more 
information:
http://www.docbook.org/tdg51/en/html/ch02.html#ch02-physdiv

Probably it would be a good idea to have all files which belongs to a set in 
one directory. However, nothing prevents you from putting it on a Web server 
or in a different directory. Actually your books can come from different 
sources and assembled in a set (or book, or chapter, ...)

Probably you have files which are needed in _all_ books, like boilerplate text 
or licenses. These would lay -- maybe -- in a separate "common" directory 
which is shared between different sets/books. As such, the href of the 
XIncludes need to be adapated as well.

However, reusing content is a complicated matter. It looks easy at a first 
glance, but can get you in some troubles if carelessly used. The DocBook 
community is developing a new method to improve reuse of logical units 
("topics"). Unfortunately, it's not mature enough to recommend that. The 
outcome looks promising.

 
> 3) also what is the implication of having sets on the rendering process?

They share a table of contents, index, it's possible to link from one book 
into another, and probably some other things that I can't remember. ;)


> Do all the books in the set have to be rendered at the same time?

No, you can render them separatly. However, for resolving every cross 
reference between books, the complete set must be rendered.

Or in other words: If you revise a book, just render that book. When 
everything is finished, render the complete set.


> Can a given book still be rendered individually?

Yes, that's possible. Use the "rootid" feature:
http://docbook.sourceforge.net/release/xsl/current/doc/html/rootid.html
http://www.sagehill.net/docbookxsl/Rootid.html

It works for every hierarchy element, not only books: chapter, preface, 
appendix, glossary, etc.


> If so how does the cross-linking work (I mean how does a book know 
> that it belongs to a set)?

The book itself doesn't "know". ;) If you use a set and place different books 
in it than it's a hierarchical structure like everything else in XML. That 
structure is recognized by the stylesheets. Nothing more, nothing less.

About the cross-linking: It will work if your document is valid DocBook. The 
DB stylesheet will resolve them correctly. The question is, if you want to 
allow cross-linking between books. So if you link somewhere from book B into 
book A, you'll create a dependency. You can still publish book A independently 
from the other books in the set. However, this will not work for book B as it 
contains a link to book A. There are some methods to circumvent or solve this 
issue:

* Avoid any intermediate cross-linking between books at all 
  (probably not nice)
* Add a pre-transformation step and resolve any cross-links before
* Replace any cross-linking with ordenary links
* Live with that issue :)


> [...]
> 
> OTOH it would be great if official manuals (or at lease core manuals)
> were rendered to HTML every night, as we could have a "nightly build"
> for manuals that follows trunk development.

I think it shouldn't create too much load to create your manuals every night. 
Of course, they must be valid otherwise funny things can emerge. :)


> [...]
> It's all a bit helter-skelter because there's actually so much to think
> of and so many ideas emerge when doing such thinking.

I know, we had the same issues when migrating to DocBook some time ago. The 
good thing is, you can create _your_ tool chain that perfectly fit _your_ 
needs.

 
Hope that helps,
  Tom