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

[François Suter]

Hi Tom,

Thanks again for your patience and all your explanations.

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

We do have a lot of manuals. Just have a look here:

http://wiki.typo3.org/DocTeam/Official_Documentation_Maintenance

And that's not even the complete list, because it doesn't take into 
accounts some very old manuals which need to be rewritten and some 
others which we hope to create. Which is why I was thinking that it 
might make sense to have a nested structure in this case: the set of all 
TYPO3 v4 manuals, containing one set for each of our categories, but 
this is maybe overkill and a single set is enough.

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

There are not so many. It's true that it could be a book. Maybe with a 
part for each system extension. OTOH a couple have rather large manuals 
(and would need references too), so they might be better as stand-alone 
books. Which could be grouped inside a "System Extensions" set.

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

There is really a huge number of extensions (around 5000), so it's 
definitely not possible (on second thoughts) to group them all in a 
single set, as it would not only be huge itself, but requires a lot of 
maintenance, as new manuals would constantly need to be added to it.

OTOH there's one thing the extension developers who write manuals really 
want to do (I guess; I certainly do, as an extension developer) and 
that's cross-linking to the official manuals. And actually the same 
applies to the system extensions discussed above. So maybe the olink 
mechanism you mention below could be a useful tool, although it could be 
introduced in a second step. Whatever the solution, this cross-linking 
possibility is very important and we need to find some of making it work 
without too much hassle for the editors.

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

Taking Christian's remarks into account here, I would say that - from a 
global point of view - v4 and v5 have similar documentation needs and a 
pretty similar structure.

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

OK. I have made the homework you mention further below and I can see the 
problems.

>   (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 ;-)

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

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

Hmm. Interesting. As you explained earlier with cross-references across 
books, the link to another book in admin.html is broken. I can render a 
single book, but it will be "whole" only if it contains solely internal 
cross-links. Which means that - at least on the documentation server - 
we would only render sets.

This points to the fact that all the official documentation should 
belong to a single set (possibly with nested sets) so that we don't have 
to bother with olinks (or some other method) within the context of 
official documentation at least.

Cheers

-- 

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