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

[Thomas Schraitle]

Hi François,

Wednesday 23 February 2011

> > 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?")
> 
> Interesting, but that information still needs to be maintained, of course.

Well, you need it only once. Sure, if the maintainer of the file changes, 
you'll have to adapt it. However, if maintains don't change too often, it's 
not really an issue.

 
> > [... to have all files which belongs to a set in one directory...]
> 
> That makes sense. Now we need to figure out what sets make sense in our
> case. As far as I can see we have to handle the following manuals:
> 
> - TYPO3 v4 official documentation. This is a set of books grouped into
> three categories: core manuals, tutorials and references. Should that be
> a single set? Should there be one set per category?

Well, I'm a bit unsure which is the best approach. Let's list some of the 
possibilities:

* Nesting a set in a set
I never saw this kind of documentation, but maybe you need this structure. 
Could be useful, if you have a set for references, a set for tutorials, and a 
set for core manuals which you want to combine under a set.
I guess, this makes only sense, when you have LOTS of books. Otherwise I would 
probably go with a lower structuring (parts, chapters, sections, ...)

* Using one set with multiple books
This is probably what you have in mind, right? If printed, you'll end up with 
something like this:

  set
    +-- book: Core Manuals
    +-- book: Tutorials
    +-- book: References

This is perfectly ok and shouldn't be a problem. I don't the structure of 
TYPO3 yet, but I would try this structure first.

* Something completely different?


> - TYPO3 v4 system extensions manuals. System extensions are extension
> that are delivered with the TYPO3 source code. Their manual is inside
> the extension, inside the source code. These manuals are currently
> unavailable online. As far as I'm concerned one aspect of this project
> is to make them "visible" again. They could form a set of their own, but
> does it actually make sense to group them in a set?

Depends how many manuals you have and how you want to distinguish them. I 
would probably go for a book, named "System Extension Manuals".


> - TYPO3 v4 public extensions. These are the extensions released by
> anyone who decided to publish his/her extension. A well-done extension
> is expected to contain a manual. I don't see any point in grouping all
> those manuals in a single set, as it would only complicate their
> rendering and the dependencies between extensions are very loose (I mean
> an extension may refer to another one, but this is not systematic).
> - as for FLOW3/TYPO3 v5 I'm not sure how things exactly stand. The
> source code is structure in packages and each package may have
> documentation. On top of that it's very likely that other manuals will
> exist, but I don't know if there's a plan to wrap them in packages too.
> And of course, there will also be 3rd-party packages developed by
> members of the community, as for v4.

I would say, these topics are currently out of scope for the TYPO3 core 
documentation. They can be integrated later when your official documentation 
is ready and works.

 
> It's quite a challenge to get all this organized so that cross-linking
> can be made easy (or at least not too hard).

Cross-linking is indeed a challenge and sometimes unsolved. I think, in this 
regard you have these options:

 (1) Rely on <xref/>s. This can make it difficult, as you *must* have a valid 
set, otherwise you may get problems in your transformation step.

 (2) Use <link>s. This *may* be an alternative, if you can ensure stable URLs 
or know them in advance.

 (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

 (4) Use some "weak links". These wouldn't be checked during the validation 
step, but resolved in the transformation step. 

 (5) Avoid any cross-links which goes beyond your current book. Or in other 
words: Use as much <xref/>s as you want, but stay in your own book.
 
For the time being, method (1) is the prefered method if you refer from one 
chapter into another chapter inside the _same_ book.

If possible, I would try to avoid cross-linking into other books. That's 
method (5). When you know the structure and the whole process, it's always 
possible to add further functionality. Don't make it too complicated in the 
first run.

 
> >> 3) also what is the implication of having sets on the rendering process?
> > 
> > They share a table of contents, index,
> 
> What do you mean exactly? Does each book have the same?

No, with a set you get two things:

* Each book has its own index
* Additonally, you can get an index which includes all indexterms from each 
book (it's called setindex).


> Actually I'm not
> really sure what "rendering a set" really means. All books are rendered,
> obviously, but what's the result of the set itself? Does it appear
> "physically" in any way? Is it just a global TOC and index?

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: ($ indicates the prompt):

 $ DB=PATH/TO/YOUR/DOCBOOK/STYLESHEETS
 $ xsltproc --output set.html $DB/xhtml/docbook.xsl set.xml

You can also render just one book. Let's say, you are only interested in the 
Administration Guide. To render a book inside a set, the respective book needs 
a xml:id attribute. If there is none, it's not possible to use the rootid 
feature.
Looking at set.xml, the book element contains the ID "t3.admin". Run the 
command with the rootid parameter (one line):

 $ xsltproc --output admin.html --stringparam rootid "t3.admin" \
   $DB/xhtml/docbook.xsl set.xml

Compare the two rendered XHTML files. 

 
> > it's possible to link from one book into another
> 
> Here I guess you mean easily, just by using simple cross-references and
> not having to bother with URIs, namespaces, etc.?

Yes, cross-referencing with <xref/>. As I said earlier, cross-referencing 
between books has it's own implications. 


> > 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:
> I'm not sure I get this. If the id's haven't changed in book A and B,
> all cross-references can be rebuilt safely, right?

Yes, but it's not a matter of changed IDs. It's a matter of building a 
separate book as I've demonstrated above with the rootid feature.
I've added two paras which contains two <xref/>s. The first points to a 
different chapter. The second points to another book. Transform it and load it 
in your browser. 

If you want to resolve the second <xref/>, you need the other book. Or in 
other words: the complete set.

> [...]

Cheers,
  Tom