[TYPO3-doc] A few DocBook questions

[Thomas Schraitle]

Hi,

Monday 20 December 2010
> 
> >> I wonder if we can really cover our use case with the existing tags (if
> >> we want to be really formal).
> > 
> > What do you miss?
> 
> Maybe nothing, but I'm not sure because I don't yet know DocBook so
> well. Here's the information that's needed for each TypoScript property:
> 
> 1) name
> 2) data type (which would be a xref to the explanation of that data type)
> 3) description
> 4) default value
> 
> That's what we currently have.

This _could_ be marked with funcsynopsis: 
http://www.docbook.org/tdg5/en/html/funcsynopsis.html
(There are some quite nice examples, although it's for the C language.)

However, even the DocBookers don't seem to use it much. Some consider it as 
legacy thing from the old days of UNIX manpages, some think it's quite useful.

I don't know if this works for TypoScript. Probably you have to adjust the 
DocBook XSL stylesheet to adhere to the special notation of that language.

As always, you have to make your own judgement. :)


> Furthermore it would be nice to have the
> range of TYPO3 versions during which it is/was available (new properties
> regularly get added, some are deprecated/removed more rarely).

This could be done with one of the common effectivity attributes that DocBook 
provides:

 http://www.docbook.org/tdg5/en/html/ref-
elements.html#common.effectivity.attributes
 
I think, conformance could be a good match. Combine it with paramdef, for 
example:

 <paramdef conformance="typo3">...</paramdef>

Of course, this is only _one_ part of the story. The other part, the DocBook 
stylesheets, does nothing special with it. You have to implement the different 
typography (bold, with logo, etc.) in your customization layer.


> The other issue is one of "hierarchy". Every TypoScript property belongs
> to a TypoScript object. So we would have something like "groups" of
> properties which belong together. If we move to refentries we need to
> make sure that we are able to keep that structure.
> 
> What's your advice to handle such data?

Hmn, do you have an example of such a relation? I have an idea, but before I 
go public I would like to see if it works. :)


Cheers,
  Tom