The presence of an <xreflabel> attribute reduces the usability of printed versions of a book. As well, attribute values are not seen by translators and, consequently, cannot be translated.
For example, if you have the following:
<chapter id="ch03" xreflabel="Chapter Three">
<title>The Secret to Eternal Life</title>
<para>The secret to eternal life is…</para>
</chapter>
[more deathless prose here]
…see <xref linkend="ch03"> for details.
when your XML is built to HTML, the <xref> tag becomes an HTML anchor tag as follows:
…see <a href="#ch03">Chapter Three</a> for details.
The text contained by the anchor tag is the same as the data in the <xreflabel> attribute. In this case, it means that readers of printed copies have less information available to them.
You could work around this if you make the value of the <xreflabel> attribute the same as the text within the <title></title> element tags. However, this duplication increases the risk of typo-level errors and otherwise offers no underlying improvement. And it still reduces the amount of information presented to readers of printed copies.
The following XML:
<chapter id="ch03" xreflabel="The Secret to Eternal Life">
<title>The Secret to Eternal Life</title>
<para>The secret to eternal life is…</para>
</chapter>
[more deathless prose here]
…see >xref linkend="ch03"> for details.
Will result in an HTML anchor tag as follows:
…see <a href="#ch03">The Secret to Eternal Life</a> for details.
This isn't as informative as the text presented to a reader if you do not use an <xreflabel> attribute. The following:
<chapter id="ch03">
<title>The Secret to Eternal Life</title>
<para>The secret to eternal life is…</para>
</chapter>
[more deathless prose here]
…see <xref linkend="ch03"> for details.
transforms the <xref> element as follows when built to HTML:
…see <a href="#ch03">Chapter 3: The Secret to Eternal Life</a> for details.
More important, however, are the translation problems that <xreflabel> tags cause. Attribute values are not seen by translators. Consequently, they are not translated. Consider the second example above again:
<chapter id="ch03" xreflabel="The Secret to Eternal Life">
<title>The Secret to Eternal Life</title>
<para>The secret to eternal life is…</para>
</chapter>
[more deathless prose here]
…see <xref linkend="ch03"> for details.
In English, the <xref> is still transformed into an anchor tag as follows:
…see <a href="#ch03">The Secret to Eternal Life</a> for details.
Someone reading the German version, however, will have this as their underlying HTML:
…Sehen Sie <a href="#ch03">The Secret to Eternal Life</a> für Details.
If the <xreflabel> attribute is not used, the title and chapter indicator, both properly translated, appear to the reader. That is, the following:
<chapter id="ch03">
<title>The Secret to Eternal Life</title>
<para>The secret to eternal life is…</para>
</chapter>
[more deathless prose here]
…see <xref linkend="ch03"> for details.
will, after translation, present thus to a German-speaking reader:
…Sehen Sie <a href="#ch03">Kapitel 3: Das Geheimnis des ewigen Lebens</a> für Details.
This is, not surprisingly, what we want.
The xreflabel attribute is therefore disallowed.
The endterm attribute allows you to present hyperlinked text other than the name of the section or chapter to which the hyperlink points. As such, it decreases the usability of printed versions of documents, and causes difficulty for translators.
The text presented in an element (such as an <xref>) that contains the endterm attribute is taken from a <titleabbrev> tag in the target chapter or section. Although the content of the <titleabbrev> tag is available to translators in the document's PO files, it is removed from the context of the <xref>. The absence of this context makes reliable translation impossible in languages that mark prepositions or articles for grammatical number and grammatical gender.
For example, if you have the following:
<chapter id="The_Secret">
<title>The Secret to Eternal Life</title>
<titleabbrev id="final">the final chapter</titleabbrev>
<para>The secret to eternal life is…</para>
</chapter>
[more deathless prose here]
The solution is in <xref linkend="The_Secret" endterm="final"/>.
The text surrounding the <xref> presents in the English version of the document as:
The solution is in the final chapter.
A translator sees the <titleabbrev> in a PO file as:
#. Tag: titleabbrev
#, no-c-format
msgid "the final chapter"
msgstr ""
and sees the text that contains the <xref> elsewhere in the PO file (or, more likely, in a completely different PO file) as:
#. Tag: para
#, no-c-format
msgid "The solution is in <xref linkend="The_Secret" endterm="final"/>."
msgstr ""
The translator has no way of telling what will be substituted for <xref linkend="The_Secret" endterm="final"/> when the document builds, so a translation in Italian might read:
#. Tag: para
#, no-c-format
msgid "The solution is in <xref linkend="The_Secret" endterm="final"/>."
msgstr "La soluzione è in <xref linkend="The_Secret" endterm="final"/>."
Note the preposition in.
If the translator rendered the final chapter in Italian as l'ultimo capitolo, the result when the document builds will read:
La soluzione è in l'ultimo capitolo.
This result is comprehensible, but inelegant, because Italian combines some of its prepositions with its definite articles. More elegant Italian would be:
La soluzione è nell'ultimo capitolo.
Without knowing what text will appear in place of <xref linkend="The_Secret" endterm="final"/>, the translator into Italian cannot know whether to leave the preposition in to stand by itself, or which of seven different possible combinations with the definite article to use: nel, nei, nello, nell', negli, nella, or nelle.
Furthermore, note that the combined preposition and article also poses a problem with regard to whether this word should be placed in the text surrounding the <xref>, or in the <titleabbrev>. Whichever of these two solutions the translator selects will cause problems when the endterm appears in other grammatical contexts, because not all Italian prepositions can combine with the definite article in this way.
Due to the problems that endterm presents for translation, Publican disallows this attribute.
