[TYPO3-doc] DocBook: sample reference file

[Thomas Schraitle]

Hi François,

Monday 21 February 2011

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

That's true, only "int" is printed. However, if you want 
"typoscript.datatype.type.int" instead of "int" why didn't you write it in the 
<refname> tag if this is important? Wouldn't be the first term more exact than 
the second?

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

Yes, I did. Personally, I use link *very* rarely but that's my style. If I 
need a modified link for one or two cases, then it's worth. However, if a link 
is spread all over the document and I need it "everywhere", I wouldn't use it.

Consider the following scenario: Let's say, "typoscript.datatype.type.int" 
will change someday to "typoscript.datatype.base.int". In that case, you have 
to tackle *all* link elements! Not really nice.

Sure, this can be searched and replaced by whatever script you like. However, 
this could not also lead to false-positives. So why not solve this through 
what DocBook and XSLT already offer? 
If you use the correct definition in refname, the <xref/> element resolve that 
name automatically. No need to touch any link, only *one* refname. :) If you 
don't like the way it's printed, it's even possible to customize the DB 
stylesheets.

Well, I don't know TypoScript so my recommendations are based on my day to day 
work with DocBook and similar documentation. Maybe I didn't dive into that 
matter deep enough or misunderstood your needs. Hopefully not. :) You are the 
TYPO3 expert. If you can *really* guarantee this name will *never* change then 
go with link. :)

 
> [...]


Thanks,
  Tom