The generated text for chapters and appendixes is by default both the number and the title, such as Chapter 3, Using a Mouse. When section numbering is turned on, references to sections also get both. If you set the stylesheet parameter xref.with.number.and.title to zero (it's one by default), then only a number label like Chapter 3 is generated.

For elements like para or note that don't have a title or number, you can add an xreflabel attribute to the element. That attribute should contain the text you want to appear when an xref points to that element. Here is an example:

<para  id="ChooseSCSIid"  xreflabel="choosing a SCSI id">The methods
for choosing a <acronym>SCSI</acronym> id are ...
</para>
...
<para>
See the paragraph on <xref  linkend="ChooseSCSIid"/>.
</para>

The xref in the second paragraph points to the first paragraph. When processed, the second paragraph will read “See the paragraph on choosing a SCSI id.” and an HTML hot link will take the reader to the beginning of the paragraph.

The advantage of xreflabel over using a link element is to provide consistent reference text to that element. If you decide to change the wording, you only have to change the xreflabel, and all xref references to it will change. If you had used link instead, then you would have to find and edit each instance to change the text.

DocBook has another trick for generating text for an xref. You can actually grab the text from another element. Here is how it works.

You can add an endterm attribute to the xref element. The value of endterm must match an id value of an element in the document. The children of the element pointed to by endterm are used as the cross reference text. But the cross reference destination is still the linkend element.

Here is an example that matches the previous one but uses endterm instead:

<para  id="ChooseSCSIid"  >The methods
for <phrase  id="SCSIxref">choosing a <acronym>SCSI</acronym> id</phrase>
are ...
</para>
...
<para>
See the paragraph on <xref  linkend="ChooseSCSIid"  endterm="SCSIxref"/>.
</para>

Note that the endterm attribute goes in the xref element, not the target element. In this case it points to a phrase element in the paragraph that has the text you want in the reference text. When processed, the second paragraph will read “See the paragraph on choosing a SCSI id.” and an HTML hot link will take the reader to the beginning of the paragraph.

There is one difference with the previous example, however. Here, the <acronym>SCSI</acronym> element will be processed by the stylesheet as an acronym. You could not put the acronym markup in the xreflabel, because attributes cannot contain elements. So this feature is most useful when the generated text needs to contain elements.

You also need to be careful what element you point the endterm to. All the children of the selected element will be processed by the stylesheet as the reference text. If you point to a list, for example, then all the listitem elements in the list become the reference text.

A more likely example is forming a cross reference to the question in a qandaentry. By default, an xref to a question element displays just the label for the question, such as Q:1. If you want the reference text to be the question text, then you might try pointing both the endterm and the linkend attributes to the id on the question element. But the child elements of question will likely include para, which will be processed into <P> tags in HTML and introduce paragraph breaks where you just wanted some inline reference text. The solution is to add an id attribute to the para and point the endterm to that instead. Here are both the good and bad examples for comparison:

<qandaentry>
  <question  id="myQuestion">
    <para  id="QuestionText">What is the circumference of the Earth?</para>
  </question>
  <answer>
    ...
  </answer>
</qandaentry>

Bad example:  introduces paragraphs breaks in reference text
<xref  linkend="myQuestion"  endterm="myQuestion" />

Good example:  selects only the text children of para
<xref  linkend="myQuestion"  endterm="QuestionText" />

You may want to change the way xref text is generated for a particular kind of element, such as chapter or appendix. See the section “Customizing cross references” for the methods of doing that.