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

[François Suter]

Hi all,

Although we haven't finished exploring the previous topics that I 
started, there's another one that I would like to tackle early on. It's 
about all the processes related to rendering the manuals (but *not* 
about the rendering process itself, this does not need to be discussed 
right now IMO) and how the whole repository is structured to enable 
simple cross-linking as much as possible.

I think we all agree that easy cross-linking (using just id attributes) 
is ideal. As far as I understand it to achieve this all manuals would 
have to grouped under a single set. This begs already the following 
questions:

1) what do we want "all manuals" to mean in our context? Should it 
really be all, i.e. all v4-related official manuals, all FLOW3 + v5 
official manuals, all extensions/packages manuals? Or should we have a 
v4 and a v5 set, or even some finer-grained sets?
The answer to this question will certainly have implications on the 
repository structure, as we will then want to have all manuals under the 
same hierarchy, maybe through the use of SVN:externals or its Git 
equivalent (hoping there's one).
BTW this is the opportunity to finally gather the stuff that's included 
in the sysext manuals, which cannot found online in the current state of 
affairs.

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. What's the implication on the 
file structure?

3) also what is the implication of having sets on the rendering process? 
Do all the books in the set have to be rendered at the same time? Can a 
given book still be rendered individually? If so how does the 
cross-linking work (I mean how does a book know that it belongs to a set)?

Another important issue is how we organize "releases" of manuals. 
Currently the process is quite clear: we work in manuals stored inside 
extensions and a new version of a manual is released whenever we decide 
to publish the wrapping extension. Version numbers are managed when 
uploading the extension to the TER.

I have been unconvinced by that way of doing for official manuals for a 
long time. Furthermore if we add sysext manuals to that, we can't rely 
on an extension being published to trigger the rendering of its manual. 
Additionally I don't think FLOW3/v5 follows the same logic.

What I would envision is that manuals would be rendered straight off the 
repository. But of course we don't want to render *all* manuals in 
*every* format *every night* (or something). Version number would be 
taken from the DocBook code anyway (productnumber in the first info 
block). For an extension author, publishing his/her extension would add 
a trigger for the rendering of the relevant manual...

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. Indeed if you assume that 
developers would be encouraged to submit DocBook patches for documenting 
new or changing features in the code instead of adding text to the 
Pending Documentation page, we could have reference documentation that 
is nearly in sync with Core development.

Rendered manuals would be available at a central place and links to the 
various formats could be assembled automatically, for example from the 
TER when looking at an extension or from the Extension Manager inside 
the TYPO3 backend.

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.

So please consider this mail as a form of brainstorming, with some 
important questions in it :-)

(Credits: some ideas from Ingo Renner).

Cheers

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