Reduce the number of xref links
The usage of xref
links in our DocBook XML documentation can be confusing for translators and also documentation writers that are not very familiar with all DocBook details.
For example:
"Rendering intents are ways of dealing with colors that are out-of-<xref "
"linkend=\"glossary-gamut\"/> colors present in the source space that the "
"destination space is incapable of producing. There are four rendering "
"intents defined by the ICC:"
Here, the glossary-gamut
link will specify what text will be inserted for the clickable link. Translators may think there is missing text for the link and may even add extra text and a closing </xref>
, which would be invalid.
In most cases, it is probably better to use <link linkend=\"glossary-gamut\">gamut</link>
. This way, it will be clear for translators what the text for the link will be. It also makes it easier for them to rearrange the sentence structure when needed.
This information should also be added to our manual/instructions for documentation writers.