[TYPO3-doc] DocBook: sample reference file

[François Suter]

Hi all,

As announced, here is a separate thread and a separate DocBook file:

https://svn.typo3.org/TYPO3v4/Documentation/official_template/trunk/DocBook/reference.xml

for discussing the structure of language references. Indeed as I 
mentioned already in the previous thread, while working on a first 
sample DocBook manual, it quickly became obvious that references (such 
as the TypoScript reference, for example) required a special treatment 
as it would use a pretty different set of DocBook tags. It's perfectly 
possible to use references inside a "normal" manual, but since we have 
pretty large documents which are quite exclusively references, it made 
sense (to me at least) to handle these separately.

The major problem that I faced was one of structure. Although it has 
grown organically over the years, TypoScript is still pretty structured. 
We have data types, functions, top-level objects, content objects, and 
GIFBUILDER and MENU objects that both have "sub-objects" (i.e. objects 
that are used only in the GIFBUILDER and MENU contexts, respectively). 
IMO it is very important that the reference document somehow preserves 
that structure:

1) for the readers, so that they can also understand that structure
2) for the rendering, so that we can reliably build links between all 
the data types, functions, objects and their parents.

The approach that I have taken and that I now submit to you for 
discussion is the following:

- data types being quite simple fit inside a single "reference", with 
one "refentry" per data type
- for functions, there's one reference per function and one refentry per 
function property
- the same for objects, one per reference and one refentry per function 
property
- on top of that I have used "parts" to group references together. For 
data types, there's only one reference, but it's still wrapped in a part 
to match the other elements. All function references are wrapped in one 
part. For objects, we would have several parts (only 2 appear in the 
sample reference), that would probably mimic the current chapters of the 
TSref, i.e. top-level objects, content objects, menu objects, GIFBUILDER 
objects, etc. Of course, this could be an opportunity to reorganize that 
structure if need be.
- the limitation is that we can't have references inside references. So 
it's not possible to have - for example - a TMENU reference and inside 
it a TMENUITEM reference. My simple work-around for now is to add 
(between brackets) the name of the "parent" object in the title of the 
object (see the TMENUITEM example).

The next step was to think of a system for keeping track of the 
relations between all the elements. What I described above is not really 
sufficient, especially since we want to be able to heavily cross-link in 
such a case. The important point here is not so much the document 
structure but the syntax of the "id" attributes. My goad is that - with 
a minimum of knowledge of a few conventions - all id attributes can be 
guessed easily. This will facilitate cross-linking.

So here's the schema that I'm proposing:

1) parts have id attributes reference the global topic. Examples: 
typoscript.datatype or typoscript.cobject
2) references have id attributes one level deeper. Examples: 
typoscript.cobject.image for the IMAGE object or 
typoscript.function.imgresource for the imgResource function. For data 
types, which need one less level, I have still set an id 
(typoscript.datatype.type) to keep a consistent structure
3) refentries have the "final" level of id structure. Examples: 
typoscript.cobject.image.file or typoscript.function.imgResource.frame
4) however when objects are dependent on others I have expanded the id 
hierarchy. Example: the TMENU object is a menu object, so its id is 
typoscript.menu.tmenu. The TMENUITEM is a child of TMENU, so its id is 
typoscript.menu.tmenu.tmenuitem. Finally a property of a TMENUITEM 
object will have an id like typoscript.menu.tmenu.tmenuitem.allwrap

Just check out the XML itself and look at all the id attributes 
(hopefully I haven't left some mistakes behind, as I changed the naming 
schema a couple of times).

I would say that this will actually help a lot for the on-line TS 
reference project, as it could probably be built just by some HTML 
rendering. And maybe that's the way to go: manuals and references might 
have different HTML renderings.

If I may also add a conclusion to this post: at the beginning I was 
pretty desperate because it seemed like it would be very hard to fit the 
TypoScript reference to the DocBook structure. Although I'm still not 
100% satisfied I think this first draft is already quite promising and I 
feel far more confident now.

Looking forward to your feedback. On top of all what I said above, there 
are also remarks in the document, properly using remarks tag this time ;-)

-- 

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