6.6. Footnotes6.7. Cross-references (26/59)6.8. Index terms

6.7. Cross-references

No need to specify the text of a link when this link points to a book division (chapter, section, etc) or to a table, figure, example, or equation having a caption.

Example, the following empty links point respectively to section "Admonitions" and to table "Admonition classes" found in this section:

<p><a href="admonitions.html"></a> contains
<a href="admonitions.html#admonition_classes"></a>.</p>

are rendered as:

Section 6.5. Admonitions contains Table 6-1. Admonition classes.

The text which is automatically generated for these empty links may be configured using attribute xreflabels of element book.

Links specified using attribute data-xml-id-ref

It's also possible to create links using the a element and proprietary attribute data-xml-id-ref rather than (or in addition to) standard attribute href.

Attribute data-xml-id-ref must contain the value of the xml:id attribute of a book division found in the ebook specification. This allows the creation of links to locations that do not exist in the input HTML pages, but which will be created in the output HTML pages.

Example, <a data-xml-id-ref="ch04"/> points to the following chapter:

1
2
3
4
5
<chapter xml:id="ch04">
  <head><title>...</title></head>
  <section href="ch4/s1.html"/>
  <section href="ch4/s2.html"/>
</chapter>

In input HTML page "ch4/s2.html", you may refer to the first section of the chapter by writing <a href="s1.html"/>. But how to refer to the chapter itself? Notice that this chapter has no input HTML page to refer to.

The solution to this problem is to add proprietary attribute data-xml-id-ref to an a element. For the above example, it's <a data-xml-id-ref="ch04"/>.

Note that writing <a href="s1.html" data-xml-id-ref="ch04"/> is an even better option because href="s1.html" is used as a fallback link target in case xml:id="ch04" is not defined in the ebook specification.