[TYPO3-doc] DocBook: sample reference file

[François Suter]

Hi,

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

That was definitely just a mistake.

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

OK, the link problem again. I'm fine with having no linkend attribute on 
para tags, but I disagree that using xref gives us the correct name. In 
this case the data type is "int" and not typoscript.datatype.type.int

You mention that we should use a link when we deviate from the tile and 
IMO this is the case.

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

Here too, looks good this way IMO.

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

Well, the elements themselves are not described :-)

> 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

Yep, that will definitely come in handy.

Thanks for your feedback and ideas.

Cheers

-- 

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