1<!-- doc/src/sgml/README.links -->
2
3Linking within DocBook documents can be confusing, so here is a summary:
4
5
6Intra-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<link>
16	use to supply text for the link, requires </link>
17	http://www.oasis-open.org/docbook/documentation/reference/html/link.html
18
19linkend=
20	controls the target of the link/xref, required
21
22endterm=
23	for <xref>, allows the text of the link/xref to be taken from a
24	different link target title
25
26
27External Linking
28----------------
29
30<ulink>
31	like <link>, but uses a URL (not a document target);  requires
32	</ulink>; if no text is specified, the URL appears as the link
33	text
34	http://www.oasis-open.org/docbook/documentation/reference/html/ulink.html
35
36url=
37	used by <ulink> to specify the URL, required
38
39
40Guidelines
41----------
42
43- For an internal link, if you want to supply text, use <link>, else
44  <xref>.
45
46- Specific nouns like GUC variables, SQL commands, and contrib modules
47  usually have xreflabels.
48
49- For an external link, use <ulink>, with or without link text.
50