| 1 |
<!-- doc/src/sgml/README.links --> |
| 2 |
|
| 3 |
Linking within DocBook documents can be confusing, so here is a summary: |
| 4 |
|
| 5 |
|
| 6 |
Intra-document Linking |
| 7 |
---------------------- |
| 8 |
|
| 9 |
<xref> |
| 10 |
use to get chapter/section number from the title of the target |
| 11 |
link, or xreflabel if defined at the target, or refentrytitle if target |
| 12 |
is a refentry; has no close tag |
| 13 |
http://www.oasis-open.org/docbook/documentation/reference/html/xref.html |
| 14 |
|
| 15 |
linkend= |
| 16 |
controls the target of the link/xref, required |
| 17 |
|
| 18 |
endterm= |
| 19 |
for <xref>, allows the text of the link/xref to be taken from a |
| 20 |
different link target title |
| 21 |
|
| 22 |
<link> |
| 23 |
use to supply text for the link, only uses linkend, requires </link> |
| 24 |
http://www.oasis-open.org/docbook/documentation/reference/html/link.html |
| 25 |
can be embedded inside of <command>, unlike <xref> |
| 26 |
|
| 27 |
|
| 28 |
External Linking |
| 29 |
---------------- |
| 30 |
|
| 31 |
<ulink> |
| 32 |
like <link>, but uses a URL (not a document target); requires |
| 33 |
</ulink>; if no text is specified, the URL appears as the link |
| 34 |
text |
| 35 |
http://www.oasis-open.org/docbook/documentation/reference/html/ulink.html |
| 36 |
|
| 37 |
url= |
| 38 |
used by <ulink> to specify the URL, required |
| 39 |
|
| 40 |
|
| 41 |
Guidelines |
| 42 |
---------- |
| 43 |
|
| 44 |
- For an internal link, if you want to supply text, use <link>, else |
| 45 |
<xref>. |
| 46 |
|
| 47 |
- Specific nouns like GUC variables, SQL commands, and contrib modules |
| 48 |
usually have xreflabels. |
| 49 |
|
| 50 |
- For an external link, use <ulink>, with or without link text. |
| 51 |
|
| 52 |
- xreflabels added to tags prevent the chapter/section for id's from being |
| 53 |
referenced; only the xreflabel is accessible. Therefore, use xreflabels |
| 54 |
only when linking is common, and chapter/section information is unneeded. |