Debian Codegraph @

doc/src/sgml/README.links

raw
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.