[TYPO3-doc] DocBook: sample reference file

[Stephan Petzl]

Hi François!
It's great that you keep this topic alive, I think the documentation 
part is one of the most important and underestimated ones. I have heard 
so many times that especially typoscript is the major reason when people 
get distracted from TYPO3 in the beginning.

After inspecting your docbook sketch, I have to say that it's quite self 
explaining, and intuitive.

Further I have some notes on your last post:

Am 18.02.11 12:39, schrieb François Suter:
> .... 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.
good point - totally agree!

> 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:
I have to disagree here- personally I don't think that this structure is 
important for TYPO3 extension developers/integrators. (Maybe we need to 
discuss some use cases / target group for the manual). I think that we 
have to really hide the complexity, so TYPO3 beginners are not afraid of 
typoscript any more.
My experience is that you don't have to know the difference of functions 
and cObjects to use typoscript and build extensions.

So why not keep it just that simple:
1. There are object types which can have properties
2. Properties have a type themselves

This is a common concept, people can understand because they know OOP.

I know that there is more complexity in the TYPO3 rendering engine, but 
do we really have to track this here in the user documentation?

> ...
> 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:
> ...
>Finally a property of a TMENUITEM
> object will have an id like typoscript.menu.tmenu.tmenuitem.allwrap
>
think that's good. we would need that for the t3editor xml as well.

Thanks for the docbook demonstration!

-- 
Best Regards
Stephan Petzl
http://www.ajado.com