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

[François Suter]

Hi,

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

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

No idea, here.

>> 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="..."/>

OK

> 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 familiar with XML catalogs?

I wasn't, but I educated myself :-) I get the point.

> 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

OK, understood.

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

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

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

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

It might be. Currently not, but it could arise as the documentation gets 
more structured.

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

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

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

OK

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

Interesting.

> 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? You're mentioning 
issues if id's have changed or did you imply something else?

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

Yep, that's encouraging :-) It may need a lot of thinking, but I guess 
we'll have a solution that rocks eventually.

Cheers

-- 

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