[TYPO3-doc] DocBook: sample reference file

[François Suter]

Hi Philipp,

Thanks for your input in this discussion.

> I can only speak for myself. If I open TSref I what to know one of the
> following (in that order, more often on top):
> 1. the exact spelling of an element
> 2. all "children" of an element
> 3. the meaning of an element (what exactly does it do and what values does
> it have, required children, etc.)
> 4. search an element I could use for a given problem

The more I read about use cases (yours and Christian's), the more I 
wonder whether we really need them. Consider it this way: what we all 
agree on is that we need the central reference file to be as complete as 
possible (and that is well-represented by the chart from T3DD10). That's 
a given. And we need this data to be structured enough that we can 
cross-link as needed and that we also can know any parent-child 
relationship that may exist between some elements.

IMO the use cases don't bring anything new to this part. What they bring 
are ideas about how people would use the available data, but people are 
never going to access the central reference directly, just the way the 
will never read the raw DocBook files. Instead people will use whatever 
has been rendered and that's where the use cases will be really useful.

And I'm pretty sure that we can manage to have renderings which are 
perfectly suitable to all the purposes that were expressed here.

What do you think?

> Drawn from my use-cases we would need the following structure (pseudo-XML):
> <element id="xyz">  //I like the id structure you proposed
>    <title>TMENU</title>
>    <description>
>      TMENU is used for creating text menus.
>    <description>
> [snip]
> </element>

That is indeed pretty close to the T3DD10 structure.

> We still need to deal with datatype and data ... looking into docbook
> reference, I think we could use the itemized list. If we can use more then
> on list, we could define the first one to contain links to datatype and the
> second to contain a list of values/keywords.

Well, I prefer the current structure which uses refsections. Of course 
pretty much any DocBook structure can be used inside a refsection, so 
it's perfectly possible to use itemized lists inside one, but I wouldn't 
rely on the order of itemized lists (or other items) just to know that 
one must be data types and the other some other piece of information.

> By the way, I would not mind writing a custom XML-DTD if it turns out that
> we can not add everything needed into docbook. Creating a docbook file via
> XSLT should not be a problem if the XML is wellformed and "explicit".

Of course, this is still a possibility.

> This text turned out to be much longer that I intended ;)
> I hope it tells my ideas and what is needed from my point of view.

No problem for the length. We need to go deeply into that topic, so that 
we come up with a solution that's fully satisfying.

Cheers

-- 

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