doc/src/sgml/README.links

   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.