[TYPO3-doc] DocBook: sample reference file

[Thomas Schraitle]

Hi François,

Tuesday 22 February 2011
> [...]
> It's the contrary :-)
> 
> I want to see "int" printed. But if I use the xref as you propose I get
> "typoscript.datatype.type.int", which is not good for readers.

I'm not really grasp the idea why the more verbose version is not good for 
readers, but you know your readers better than me so I trust you here. :)


> [...]
> On the refentry with the id "typoscript.datatype.type.int", I used the
> xreflabel attribute and set it to "int". This way now the xrefs show "int".
> 
> Is that what you meant? This is indeed very good!

Well, I think we come closer. :)

It's correct, there is a xreflabel and it influences the generated link text 
from a xref element. However, in this case I believe it's unnecessary.

Maybe, we should dissect this issue step by step so we can come to its core. 
Let's use our int datatype structure:

  <refentry xml:id="typoscript.datatype.type.int">
    <refnamediv>
       <refname>int</refname>
       <refpurpose>A simple integer number</refpurpose>
    </refnamediv>
    <!-- Other irrelevant elements omitted -->
  </refentry>

Correct? Somewhere in your document you want to cross reference to your int 
datatype. In that case, just write this:

  <para>For more information, see the <xref
       linkend="typoscript.datatype.type.int"/> datatype.</para>

Which would be rendered as this:

  For more information, see the int datatype.

(The "int" in the previous sentece is a link in HTML.)

If you add an additional xreflabel in your refentry and set it to "int" it 
will change nothing. :) It's still printed as "int". Therefor it's useless and 
can be omitted.

On the other side, if you really want to deviate from the default "int" 
rendering, _then_ use the xreflabel. The advantage of this apporach is to 
exchange the generated text very easily. Every xref pointing to your refentry 
is exchanged by the content of the xreflabel attribute.

Just try it out and transform your reference.xml into HTML by using this 
command ($ indicates a prompt):

 $ DB=PATH/TO/THE/DOCBOOK/DIRECTORY
 $ xsltproc --output reference.html $DB/xhtml/docbook.xsl reference.xml

Compare it with and without the xreflabel attribute. Is it clearer now?


Cheers,
  Tom