[TYPO3-doc] DocBook: storage structure

[François Suter]

Hi,

> However, I think one top-level folder "Build" is still missing, which
> contains the full build chain. For that, I'd suggest to use Phing
> Scripts (but that's another topic...)

I would put that in a separate Git repository that we have planned to 
have with Daniel.

> I'd like to discuss one related point: SVN or GIT // how to store
> different versions of core manuals
>
> For all core manuals, they are bound to a specific TYPO3 version -- so
> we'd need branches for each 4.X release, and tags for each 4.X.Y release.
> Thus, the structure would be more like:
> CoreManuals
> |-- doc_core_api
>       |-- en
>            |-- branches
>            |-- tags
>            |-- trunk
>
> right?

That's an issue indeed, we haven't discussed yet. But Git does not mark 
this physically, right? So we don't really need these subdirectories, do we?

> And this brings me to the second question: *If* we use Git (which I
> think is a good idea, as we're moving to Git in the mid-term), I'd
> suggest to use *different repositories for each language version of a
> manual*. Else, it would be impossible to use branches / tags as it is
> supposed to in Git.

Branches are for a whole repository, right? Hmm, that's an issue indeed.

There's one other reason why I think having a single large structure 
could be useful is because we would to try and use the online DocBook 
editor used by the PHP project to manage their own documentation:

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

They are open to patches for changes that we might need to make the tool 
less PHP-community-centric.

I'm pretty this would require to have all manuals together and 
especially the translations side-by-side, but I may be wrong.

I agree that all this makes it difficult to keep track of particular 
versions of a manual. On the one hand I would tend to say that it's not 
such a big issue, as we have never gone back and modified older manuals 
until now. However this is also because it was already a hassle to 
maintain the OpenOffice files at all, so we were not very willing to go 
back just for minor corrections. On the other hand, it would of course 
be good to tag individual versions of manuals per language... But that 
many a strongly split structure and so many repositories and teams. It 
seems like a maintenance nightmare to me...

I would say I could sacrifice tagging for having a single structure. One 
possible workaround could be to agree on a naming convention for tags 
which include the manual's name, its version and its language. That way 
it would still be possible to find a given "release" in the version 
history and branch from there if necessary.

> Furthermore, I'd suggest one "Distribution" which contains the structure
> you outlined, and pulls in all the other manuals as Git Submodules. We
> from the v5 team use this structure for Phoenix and FLOW3 for a while
> now, and made quite good experiences with it.
> The only small hassle: Git Submodules always *point to a specific
> revision*, so in v5 we have a small hudson job which automatically
> updates the distribution regularly... And that's what I'd suggest as well.

I guess we will have external submodules anyway, mostly for v5. I don't 
know how you see things. For example, for now, the FLOW3 documentation 
is inside the FLOW3 package. One way or other it should be available in 
the global documentation structure. Since I can see the point of having 
packages being fully self-contained (in particular containing their own 
documentation, even if in a format that cannot be read out of the box), 
this would mean that the FLOW3 manual - for example - stays in the FLOW3 
package and gets sync'ed into the global documentation repository. OTOH 
this is a shame if we manage to get the online editor to work. It's not 
such an easy issue...

Cheers

-- 

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