[TYPO3-doc] DocBook: sample reference file

[Thomas Schraitle]

Hi François,

as I don't know the TYPO3 reference documentation (yet), I don't feel 
qualified enough to give some good comments so I've abstained from giving 
stupid recommendations. :) Therefor my post is focusing more on the DocBook 
source code itself.

Friday 18 February 2011
> 
> 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.

As I now have commit rights, I've added some remarks in your file. Just search 
for the marker "toms" and you'll quickly find them.

Here is a brief summary for those who don't want to read the XML file:

1. para vs. programlisting/screen
When showing examples to your readers I would use programlisting or screen but 
not para. The latter is just for "explanations", verbose text etc.

2. <para linkend="typoscript.datatype.type.int">int</para>
This construct is not very common in DocBook and will probably not work as 
expected. :) I would recommend to replace it with <para>See also <xref 
linkend="typoscript.datatype.type.int"/></para>.
The previous construct has two advantages:
  a) No linkend in para, so no inconsistencies. ;) 
  b) Let <xref/> resolve the correct name.

3. <link linkend="typoscript.datatype.type.boolean">boolean</link>
Same as 2.

4. chapter/preface at the end of part
Should be possible. My oXygen editor let me choose it. :)


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

I think that is a very good approach!

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

There are no xml:id's for 
typoscript.datatype.type.boolean, typoscript.function.stdwrap, and 
typoscript.datatype.type.wrap

:)

 
> [...]
> 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 ;-)

I've only one final comment. When transforming your XML file to HTML (using  
the standard settings), you'll get the following table of contents:


----------
Table of Contents
  Introduction
    About this document
    What's new
    Credits
    Feedback

I. Data Types
  I. Data Types
    int — A simple integer number
    resource — A reference to a file in a template

II. Functions
  II. imgResource function
    frame — Choice of frame within an animated GIF...

III. Content objects
  III. IMAGE object
    file — Path to an image file

IV. MENU objects
  IV. TMENU object
    expAll — Expand the submenu or not
  V. TMENUITEM object (TMENU)
    allWrap — Wraps the whole item

Next steps
----------

The numbering between parts and references might be a bit unfortunate, but can 
be changed easily with the reference.autolabel parameter:
http://docbook.sourceforge.net/release/xsl/current/doc/html/reference.autolabel.html


Ok that's it. 


Tom