docs/1.6/links.xml

   1 <?xml version='1.0' encoding='UTF-8'?>\r
   2 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"\r
   3   xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="links">\r
   4   <title>Cross-References and Links</title>\r
   5   <info>\r
   6     <abstract>\r
   7       <para>DocBook has three linking elements that are used to create internal cross-references,\r
   8         external cross-references, and links to locations on the Web. Some of the linking elements\r
   9         perform multiple tasks and some have overlapping functionality. Authors choose the proper\r
  10         element based on the specifics of the task at hand. A portion of the link text is generated\r
  11         by the publication system and the author has some control over it.</para>\r
  12     </abstract>\r
  13   </info>\r
  14   <section xml:id="linksInternal">\r
  15     <title>Cross-References within the Same File or Book</title>\r
  16     <simplesect>\r
  17       <title>Overview</title>\r
  18       <para>Internal cross-references link to targets within the same file or book. There are two\r
  19         linking elements that can be used to make an internal cross-reference:</para>\r
  20       <itemizedlist>\r
  21         <listitem>\r
  22           <para><link linkend="xref">\r
  23               <tag class="element">xref</tag>\r
  24             </link>-generates a cross-reference whose target is in the same file.</para>\r
  25         </listitem>\r
  26         <listitem>\r
  27           <para><link linkend="link">\r
  28               <tag class="element">link</tag>\r
  29             </link>-generates a cress-reference whose target is in the same file but allows the\r
  30             author to provide the link text.</para>\r
  31         </listitem>\r
  32         <listitem>\r
  33           <para><link linkend="olinkInternal">\r
  34               <tag class="element">olink</tag>\r
  35             </link>-generates a cross-reference whose target is in a different file. The <tag\r
  36               class="element">olink</tag> element allows the author to use either generated link\r
  37             text or author supplied link text.</para>\r
  38         </listitem>\r
  39       </itemizedlist>\r
  40     </simplesect>\r
  41     <simplesect xml:id="xref">\r
  42       <title>Inserting a cross-reference in the same file, using generated text</title>\r
  43       <indexterm>\r
  44         <primary>xref element</primary>\r
  45       </indexterm>\r
  46       <indexterm>\r
  47         <primary>linking</primary>\r
  48         <secondary>using generated text</secondary>\r
  49       </indexterm>\r
  50       <indexterm>\r
  51         <primary>cross referencing</primary>\r
  52       </indexterm>\r
  53       <para>The <tag class="element">xref</tag> element creates a link to an element in the same\r
  54         file. It requires the use of the <tag class="attribute">linkend</tag> attribute to identify\r
  55         the target element.</para>\r
  56       <para>The <tag class="element">xref</tag> element does not have any content. The link text is\r
  57         generated based on the contents of the target element. <anchor xml:id="xreftextgen"/>If the\r
  58         target element has a <tag class="element">title</tag> element, such as a <tag\r
  59           class="element">section</tag> element or an <tag class="element">example</tag> element,\r
  60         the contents of the <tag class="element">title</tag> element is used as the link text.\r
  61         Alternatively, the value of the target element's <tag class="attribute">xreflabel</tag>\r
  62         attribute will be used as the link text.</para>\r
  63       <important>\r
  64         <para>If the referenced element has both a <tag class="element">title</tag> element and a\r
  65           value specified in its <tag class="attribute">xreflabel</tag> attribute, the value of the\r
  66             <tag class="attribute">xreflabel</tag> attribute is used.</para>\r
  67       </important>\r
  68       <tip>\r
  69         <para>The default generated text for a PDF cross-reference includes the page number of the\r
  70           target. The generated text can be changed using the <tag class="attribute">xrefstyle</tag>\r
  71           attribute. See <xref linkend="linkStyling"/>.</para>\r
  72       </tip>\r
  73       <para><xref linkend="xrefexample1"/> shows an example of a cross reference whose text is\r
  74         derived from the <tag class="element">title</tag> element of the referenced element. The\r
  75         resulting link text would be <literal>the section called "Coco Crisp"\r
  76         shows</literal>.</para>\r
  77       <example xml:id="xrefexample1">\r
  78         <title>Cross Reference to a Titled Element</title>\r
  79         <programlisting>&lt;para&gt;<emphasis role="bold">&lt;xref linkend="topsect" /&gt;</emphasis> shows ...&lt;/para&gt;\r
  80 ...\r
  81 &lt;section id=&quot;topsect&quot;&gt;\r
  82   &lt;title&gt;Coco Crisp&lt;/title&gt;\r
  83 ...\r
  84 &lt;/section&gt;</programlisting>\r
  85       </example>\r
  86       <para><xref linkend="xrefexample2"/> shows an example of a cross reference whose text is\r
  87         derived from the <tag class="attribute">xreflabel</tag> attribute of the targeted element.\r
  88         The resulting link text would be <literal>outfielder shows</literal>.</para>\r
  89       <example xml:id="xrefexample2">\r
  90         <title>Cross Reference to an Element with an xreflabel</title>\r
  91         <programlisting>&lt;para&gt;&lt;xref linkend=&quot;example1&quot; /&gt; shows ...&lt;/para&gt;\r
  92 ...\r
  93 &lt;example id=&quot;example1&quot; xreflabel=&quot;outfielder&quot;&gt;\r
  94   &lt;title&gt;Catching Coco Crisp&lt;/title&gt;\r
  95   ...\r
  96 &lt;/example&gt;</programlisting>\r
  97       </example>\r
  98     </simplesect>\r
  99     <simplesect xml:id="link">\r
 100       <title>Inserting link using author supplied text</title>\r
 101       <indexterm>\r
 102         <primary>link element</primary>\r
 103       </indexterm>\r
 104       <indexterm>\r
 105         <primary>linking</primary>\r
 106         <secondary>using author text</secondary>\r
 107       </indexterm>\r
 108       <para>Internal links are created using the <tag class="element">link</tag> element. The <tag\r
 109           class="element">link</tag> element has one required attribute, <tag class="attribute"\r
 110           >linkend</tag>, whose value is the id of element anchoring the link. The anchoring element\r
 111         can be any valid DocBook element that uses the <tag class="attribute">xml:id</tag>\r
 112         attribute. For example if you wanted to create a link to an image in your document, you\r
 113         would use the id of the <tag class="element">figure</tag> element that wraps the\r
 114         image.</para>\r
 115       <para>The text used for the link is the content of the <tag class="element">link</tag>\r
 116         element. <xref linkend="linkexample"/> shows the mark up for this <link linkend="link">link\r
 117           to the top</link> of this section.</para>\r
 118       <example xml:id="linkexample">\r
 119         <title>Example of an Internal Link</title>\r
 120         <programlisting>&lt;section xml:id="link"&gt;\r
 121   ...\r
 122   &lt;para&gt;... this <emphasis role="bold">&lt;link linkend=&quot;link&quot;&gt;link to the top&lt;/link&gt;</emphasis> of ...&lt;/para&gt;\r
 123   ...\r
 124 &lt;/section&gt;</programlisting>\r
 125       </example>\r
 126       <tip>\r
 127         <para>The default generated text for a PDF link includes the page number of the target. The\r
 128           generated text can be changed using the <tag class="attribute">xrefstyle</tag> attribute.\r
 129           See <xref linkend="linkStyling"/>.</para>\r
 130       </tip>\r
 131     </simplesect>\r
 132     <simplesect xml:id="olinkInternal">\r
 133       <title>Inserting a link to a target element in a different source file</title>\r
 134       <indexterm>\r
 135         <primary>olink element</primary>\r
 136       </indexterm>\r
 137       <indexterm>\r
 138         <primary>linking</primary>\r
 139         <secondary>external source file</secondary>\r
 140       </indexterm>\r
 141       <para>The <tag class="element">olink</tag> element facilitates cross-linking among DocBook\r
 142         files (just as <tag class="element">xref</tag> and <tag class="element">link</tag> elements\r
 143         enable linking within files).</para>\r
 144       <indexterm>\r
 145         <primary>olink element</primary>\r
 146       </indexterm>\r
 147       <indexterm>\r
 148         <primary>linking</primary>\r
 149         <secondary>across books</secondary>\r
 150       </indexterm>\r
 151       <indexterm>\r
 152         <primary>site map</primary>\r
 153       </indexterm>\r
 154       <para>You create a link to another book using the <tag class="element">olink</tag>\r
 155         element.</para>\r
 156       <para>Two attributes associated with the <tag class="element">olink</tag> element are used to\r
 157         specify the link target:</para>\r
 158       <variablelist>\r
 159         <varlistentry>\r
 160           <term>\r
 161             <tag class="attribute">targetptr</tag>\r
 162           </term>\r
 163           <listitem>\r
 164             <para>The value of the link target's <tag class="attribute">xml:id</tag>\r
 165               attribute</para>\r
 166           </listitem>\r
 167         </varlistentry>\r
 168         <varlistentry>\r
 169           <term>\r
 170             <tag class="attribute">targetdoc</tag>\r
 171           </term>\r
 172           <listitem>\r
 173             <para>The value of the <tag class="attribute">targetdoc</tag> attribute of the target\r
 174               document. </para>\r
 175           </listitem>\r
 176         </varlistentry>\r
 177       </variablelist>\r
 178       <para>For simplicity's sake, use the document's xml:id attribute as the document identifier;\r
 179         it will then function as both the <tag class="element">targetdoc</tag> and <tag\r
 180           class="element">targetptr</tag> element. So the <tag class="element">olink</tag> reference\r
 181         for this file would be filenames, as in this example:</para>\r
 182       <para>See the chapter on &lt;olink targetdoc="lists" targetpr="lists"&gt;creating\r
 183         lists&lt;/olink&gt; </para>\r
 184     </simplesect>\r
 185   </section>\r
 186   <section>\r
 187     <title>Cross-References to Other Books</title>\r
 188     <simplesect>\r
 189       <title>Overview</title>\r
 190       <para>Authors can create cross-references to a different book in a set using the <tag\r
 191           class="element">olink</tag> element. When linking to a different book, an author needs to\r
 192         use an additional attribute to specify the book in which the target element is located. The\r
 193         external linking mechanism relies on a site map and a number of target databases.</para>\r
 194     </simplesect>\r
 195     <simplesect>\r
 196       <title>Specifying the link text</title>\r
 197       <para>DocBook provides two methods for specifying link text for <tag class="element"\r
 198           >olink</tag> elements: author-supplied and auto-generated. Evergreen documentation uses\r
 199         author-supplied link text.</para>\r
 200       <para>Creating an olink between books</para>\r
 201       <para>adfasfsda</para>\r
 202     </simplesect>\r
 203     <simplesect>\r
 204       <title>Setting up the olink site map</title>\r
 205       <indexterm>\r
 206         <primary>site map</primary>\r
 207       </indexterm>\r
 208       <indexterm>\r
 209         <primary>linking</primary>\r
 210         <secondary>external XML source</secondary>\r
 211         <tertiary>making a site map</tertiary>\r
 212       </indexterm>\r
 213       <para>\r
 214         <note>\r
 215           <para>Most Evergreen documentation authors do not have to worry about creating or\r
 216             maintaining the site map for olinks in Evergreen documentation. This is set up in\r
 217             advance by the same team that manages the file commits.</para>\r
 218         </note>\r
 219       </para>\r
 220       <para>Stayton notes in DocBook XSL, "To form cross references between documents in HTML, their\r
 221         relative locations must be known." The olink site map defines how the published\r
 222         documentation set will be laid out and allows the publication system to resolve the links\r
 223         between all of the documents in the set.</para>\r
 224       <para>The site map for a documentation set is placed at the root of the documentation source\r
 225         tree and is always called <filename>site.xml</filename>. <xref linkend="LinksCalloutExample"\r
 226         /> shows a sample site map.</para>\r
 227       <example xml:id="LinksCalloutExample" pgwide="1">\r
 228         <?dbfo pgwide="1"?>\r
 229         <title>Document Set Site Map</title>\r
 230         <programlisting language="xml">&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt; <co linkends="sitemapptr0" xml:id="sitemapco0"/>\r
 231 &lt;targetset&gt;<co linkends="sitemapptr3" xml:id="sitemapco3"/>\r
 232   &lt;targetsetinfo&gt;<co linkends="sitemapptr4" xml:id="sitemapco4"/>\r
 233     &lt;title&gt;Library Title&lt;/tite&gt; <co linkends="sitemapptr41" xml:id="sitemapco41"/>\r
 234     &lt;desc&gt;Site map for the Evergreen XML Style Guide&lt;/desc&gt; <co linkends="sitemapptr42" xml:id="sitemapco42"/>\r
 235   &lt;/targetsetinfo&gt;\r
 236   &lt;sitemap&gt;<co linkends="sitemapptr5" xml:id="sitemapco5"/>\r
 237     &lt;dir name=&quot;docs_rls_inferno&quot;&gt;<co linkends="sitemapptr6" xml:id="sitemapco6"/>\r
 238       &lt;dir name=&quot;fluff&quot;&gt;<co linkends="sitemapptr75" xml:id="sitemapco75"/>\r
 239         &lt;dir name=&quot;overview&quot;&gt;<co linkends="sitemapptr7" xml:id="sitemapco7"/>\r
 240           &lt;document targetdoc=&quot;InfernoOverview&quot;&gt; <co linkends="sitemapptr8" xml:id="sitemapco8"/>\r
 241            &lt;xi:include href="overview/target.db" xmlns:xi="http://www.w3.org/2001/XInclude" /&gt; <co linkends="sitemapptr9" xml:id="sitemapco9"/>\r
 242           &lt;/document&gt;\r
 243         &lt;/dir&gt;\r
 244       &lt;/dir&gt;\r
 245       &lt;dir name=&quot;install_guide&quot;&gt;\r
 246         &lt;document targetdoc=&quot;InfernoInstall&quot;&gt;\r
 247         &lt;xi:include href="install_guide/target.db" xmlns:xi="http://www.w3.org/2001/XInclude" /&gt;\r
 248         &lt;/document&gt;\r
 249       &lt;/dir&gt;\r
 250       &lt;dir name=&quot;getting_started&quot;&gt;\r
 251         &lt;document targetdoc=&quot;InfernoGetStarted&quot;&gt;\r
 252         &lt;xi:include href="get_started/target.db" xmlns:xi="http://www.w3.org/2001/XInclude" /&gt;\r
 253         &lt;/document&gt;\r
 254       &lt;/dir&gt;\r
 255     &lt;/dir&gt;\r
 256   &lt;/sitemap&gt;\r
 257 &lt;/targetset&gt;</programlisting>\r
 258       </example>\r
 259       <calloutlist>\r
 260         <title>Elements of the Site Map</title>\r
 261         <callout arearefs="sitemapco0" xml:id="sitemapptr0">\r
 262           <para>The site map should always be encoded as UTF-8. This ensures that all of the\r
 263             generated target data has the same encodings regardless of the encodings used by the XML\r
 264             source files.</para>\r
 265         </callout>\r
 266         <callout arearefs="sitemapco3" xml:id="sitemapptr3">\r
 267           <para>The <tag class="element">targetset</tag> element is the root of the site map.</para>\r
 268         </callout>\r
 269         <callout arearefs="sitemapco4" xml:id="sitemapptr4">\r
 270           <para>The <tag class="element">targetsetinfo</tag> element allows you to provide a\r
 271             description for the document set or any other information that is relevant to the site\r
 272             map.</para>\r
 273         </callout>\r
 274         <callout arearefs="sitemapco41" xml:id="sitemapptr41">\r
 275           <para>The <tag class="element">title</tag> element allows you to provide a title to be\r
 276             used on the generated index page.</para>\r
 277         </callout>\r
 278         <callout arearefs="sitemapco42" xml:id="sitemapptr42">\r
 279           <para>The <tag class="element">desc</tag> element allows you to provide a description for\r
 280             the document set that will appear at the top of the generated index page.</para>\r
 281         </callout>\r
 282         <callout arearefs="sitemapco5" xml:id="sitemapptr5">\r
 283           <para>The <tag class="element">sitemap</tag> element contains the directory layout of the\r
 284             output files.</para>\r
 285         </callout>\r
 286         <callout arearefs="sitemapco6" xml:id="sitemapptr6">\r
 287           <para>The name of the top-level directory is not important in the generation of the target\r
 288             databases for the links. The links are generated relative to the top-level\r
 289             directory.</para>\r
 290         </callout>\r
 291         <callout arearefs="sitemapco75" xml:id="sitemapptr75">\r
 292           <para>This is a directory that only contains other directories.</para>\r
 293         </callout>\r
 294         <callout arearefs="sitemapco7" xml:id="sitemapptr7">\r
 295           <para>This directory holds a generated book.</para>\r
 296         </callout>\r
 297         <callout arearefs="sitemapco8" xml:id="sitemapptr8">\r
 298           <para>The <tag class="element">document</tag> element's <tag class="attribute"\r
 299               >targetdoc</tag> attribute specifies the identifier used in the <tag class="element"\r
 300               >olink</tag> element's <tag class="attribute">targetdoc</tag> attribute when linking\r
 301             to targets in the document.</para>\r
 302         </callout>\r
 303         <callout arearefs="sitemapco9" xml:id="sitemapptr9">\r
 304           <para>The target database is included in the site map using an <tag class="element"\r
 305               >xi:include</tag> element. The path for each book's target database should be\r
 306                 <filename><replaceable>book_src_dir</replaceable>/target.db</filename>.</para>\r
 307         </callout>\r
 308       </calloutlist>\r
 309     </simplesect>\r
 310   </section>\r
 311   <section xml:id="ulink">\r
 312     <title>Linking to Web Pages</title>\r
 313     <simplesect>\r
 314       <title>Creating the link</title>\r
 315       <indexterm>\r
 316         <primary>link element</primary>\r
 317         <secondary>xl:href attribute</secondary>\r
 318       </indexterm>\r
 319       <indexterm>\r
 320         <primary>linking</primary>\r
 321         <secondary>Web pages</secondary>\r
 322       </indexterm>\r
 323       <para>Links to Web pages are created using the <tag class="element">link</tag> element. You\r
 324         identify the target Web site using the <tag class="attribute">xl:href</tag> attribute. The\r
 325         value must be a valid URL.</para>\r
 326     </simplesect>\r
 327     <simplesect>\r
 328       <title>Specifying the link text</title>\r
 329       <para>The link text can be specified in one of two ways. You can specified the desired link\r
 330         text as the value of the <tag class="element">link</tag> element. If you leave the <tag\r
 331           class="element">link</tag> element empty, the value of the <tag class="attribute"\r
 332           >xl:href</tag> attribute will be used as the link text.</para>\r
 333       <tip>\r
 334         <para>The PDF will always show the URL in the generated text.</para>\r
 335       </tip>\r
 336     </simplesect>\r
 337     <simplesect>\r
 338       <title>Examples</title>\r
 339       <para><xref linkend="ulinkexample1"/> shows an example of an external link with supplied link\r
 340         text.</para>\r
 341       <example xml:id="ulinkexample1">\r
 342         <title>External Link with Link Text</title>\r
 343         <programlisting language="xml">&lt;link xl:href=&quot;http://www.cxf.org&quot;&gt;CXF Home&lt;/link&gt;</programlisting>\r
 344       </example>\r
 345       <para><xref linkend="ulinkexample2"/> shows an example of an external link that uses the\r
 346         default link text.</para>\r
 347       <example xml:id="ulinkexample2">\r
 348         <title>External Link Using Default Link Text</title>\r
 349         <programlisting>&lt;link xl:href=&quot;http://www.cxf.org&quot; /&gt;</programlisting>\r
 350       </example>\r
 351     </simplesect>\r
 352   </section>\r
 353   <section xml:id="linkAnchor">\r
 354     <title>Creating Anchor Points</title>\r
 355     <indexterm>\r
 356       <primary>anchor element</primary>\r
 357     </indexterm>\r
 358     <indexterm>\r
 359       <primary>linking</primary>\r
 360       <secondary>creating a target</secondary>\r
 361     </indexterm>\r
 362     <simplesect>\r
 363       <title>Overview</title>\r
 364       <para>Authors can create anchor points in your text using the <tag class="element"\r
 365           >anchor</tag> element. The <tag class="element">anchor</tag> element does not have any\r
 366         content and does not result in any generated text. It simply marks a place in the content\r
 367         that can be the target of a link.</para>\r
 368     </simplesect>\r
 369     <simplesect>\r
 370       <title>Marking an anchor point</title>\r
 371       <para>The <tag class="element">anchor</tag> element is empty. It has a required <tag\r
 372           class="attribute">xml:id</tag> attribute that is the ID used for linking to the anchor. In\r
 373         addition, it can take a <tag class="attribute">xreflabel</tag> attribute that provides the\r
 374         generated text for an <tag class="element">xref</tag> element or an empty <tag\r
 375           class="element">olink</tag> element.</para>\r
 376     </simplesect>\r
 377     <simplesect>\r
 378       <title>Example</title>\r
 379       <para><xref linkend="anchorEx"/> shows the mark-up for placing an anchor in a document.</para>\r
 380       <example xml:id="anchorEx">\r
 381         <title>Creating an Anchor</title>\r
 382         <programlisting language="docbook">&lt;section ...&gt;\r
 383   ...\r
 384   <emphasis role="bold">&lt;anchor xml:id="anchorID" xreflabel="here" /&gt;</emphasis>\r
 385   ...\r
 386   &lt;para&gt;&lt;xref linkend="anchorID" /&gt; is a link to an anchor.&lt;/para&gt;\r
 387   ...\r
 388 &lt;/section&gt;</programlisting>\r
 389         <para>The generated text from the mark-up in <xref linkend="anchorEx"/> is <literal>here is\r
 390             a to an anchor.</literal> and the <literal>here</literal> would be a link back to the\r
 391           anchor.</para>\r
 392       </example>\r
 393     </simplesect>\r
 394   </section>\r
 395   <section xml:id="linkStyling">\r
 396     <title>Controlling the Generated Link Text</title>\r
 397     <simplesect>\r
 398       <title>Overview</title>\r
 399       <para>The publication system adds page numbers to all cross-references in PDF books. For\r
 400         cross-references that use generated text, the publication makes choices about what text is\r
 401         appropriate for the cross-reference. In some cases the defaults used by the publication is\r
 402         not appropriate. In these cases, the author can modify the generated link text using the\r
 403           <tag class="attribute">xrefstyle</tag> attribute.</para>\r
 404     </simplesect>\r
 405     <simplesect>\r
 406       <title>The xrefstyle attribute</title>\r
 407       <para>The <tag class="attribute">xrefstyle</tag> attribute's value is a string pattern. All of\r
 408         the patterns that can be used are described in Bob Stayton's <citetitle\r
 409           xl:href="http://sagehill.net/docbookxsl/CustomXrefs.html#Xrefstyle">DocBook XSL: The\r
 410           Complete Guide</citetitle>.</para>\r
 411       <para>The pattern most commonly used in the Evergreen authoring system is the\r
 412           <literal>select</literal> pattern. This pattern is specified using the syntax shown in\r
 413           <xref linkend="xrefstyleSelectEx"/>.</para>\r
 414       <example xml:id="xrefstyleSelectEx">\r
 415         <title>Syntax for the Select Pattern</title>\r
 416         <programlisting language="docbook">&lt;xref ... <emphasis role="bold">xrefstyle="select: <replaceable>opt1</replaceable> <replaceable>opt2</replaceable> ... <replaceable>optN</replaceable>"</emphasis> /&gt;</programlisting>\r
 417       </example>\r
 418       <para>The values for <replaceable>optN</replaceable> select the text generated for the link\r
 419         text.</para>\r
 420     </simplesect>\r
 421     <simplesect>\r
 422       <title>Turning off page numbers</title>\r
 423       <para>Authors can turn off the generation of page numbers in the PDF using the\r
 424           <literal>nopage</literal> option in the select pattern. This option instructs the link\r
 425         generation algorithm to not generate page numbers, however it does not provide any guidance\r
 426         about what to include in the generated text. For <tag class="element">link</tag> elements\r
 427         and <tag class="element">olink</tag> elements that provide a value for the link text, the\r
 428           <literal>nopage</literal> option produces a the supplied link text without a page number.\r
 429         For <tag class="element">xref</tag> elements and <tag class="element">olink</tag> elements\r
 430         that rely on the publication system to generate the link text, the <literal>nopage</literal>\r
 431         is insufficient to create a valid link. The author will need to provide either the <link\r
 432           linkend="linksLabel" xrefstyle="select: nopage">label</link> option to the pattern or the\r
 433           <link linkend="linksTitle" xrefstyle="select: nopage">title</link> option to the selection\r
 434         pattern.</para>\r
 435       <para><xref linkend="linkexample2"/> shows a <tag class="element">link</tag> element that\r
 436         would not generate a page number.</para>\r
 437       <example xml:id="linkexample2" pgwide="1">\r
 438         <?dbfo pgwide="1"?>\r
 439         <title>Example of an Internal Link with no Page Number</title>\r
 440         <programlisting>&lt;section xml:id="link"&gt;\r
 441   ...\r
 442   &lt;para&gt;... this <emphasis role="bold">&lt;link linkend="link" xrefstyle="select: nopage"&gt;link to the top&lt;/link&gt;</emphasis> of ...&lt;/para&gt;\r
 443   ...\r
 444 &lt;/section&gt;</programlisting>\r
 445       </example>\r
 446     </simplesect>\r
 447     <simplesect xml:id="linksLabel">\r
 448       <title>Using the target's label</title>\r
 449       <para>Figures, tables, and examples have labels that are used to generate the link text. To\r
 450         ensure that an <tag class="element">xref</tag> element or an <tag class="element"\r
 451           >olink</tag> element that relies on the publication system to generate the link text will\r
 452         produce link text when page numbering is turned off, the author needs to provide the\r
 453           <literal>label</literal> option to the selection pattern.</para>\r
 454       <para><xref linkend="linkexample3"/> shows an <tag class="element">xref</tag> element that\r
 455         generates a label without a page number.</para>\r
 456       <example xml:id="linkexample3" pgwide="1">\r
 457         <?dbfo pgwide="1"?>\r
 458         <title>A Cross-Reference to a Figure with no Page Number</title>\r
 459         <programlisting>&lt;figure xml:id="link"&gt;\r
 460   ...\r
 461 &lt;/figure&gt;\r
 462 &lt;para&gt;<emphasis role="bold">&lt;xref linkend="link" xrefstyle="select: nopage label" /&gt;</emphasis> shows ...&lt;/para&gt;\r
 463 ...\r
 464 </programlisting>\r
 465       </example>\r
 466     </simplesect>\r
 467     <simplesect xml:id="linksTitle">\r
 468       <title>Using the target's title</title>\r
 469       <para>Chapters, sections, and blocks have titles that are used to generate the link text. To\r
 470         ensure that an <tag class="element">xref</tag> element or an <tag class="element"\r
 471           >olink</tag> element that relies on the publication system to generate the link text will\r
 472         produce link text when page numbering is turned off, the author needs to provide the\r
 473           <literal>title</literal> option to the selection pattern.</para>\r
 474       <para><xref linkend="linkexample4"/> shows an <tag class="element">xref</tag> element that\r
 475         generates a title without a page number.</para>\r
 476       <example xml:id="linkexample4" pgwide="1">\r
 477         <?dbfo pgwide="1"?>\r
 478         <title>A Cross-Reference to a Block with no Page Number</title>\r
 479         <programlisting>&lt;simplesect xml:id="link"&gt;\r
 480   ...\r
 481 &lt;/simplesect&gt;\r
 482 ...\r
 483 &lt;para&gt;As discussed in <emphasis role="bold">&lt;olink targetptr="link" xrefstyle="select: nopage label" /&gt;</emphasis> ...&lt;/para&gt;\r
 484 ...\r
 485 </programlisting>\r
 486       </example>\r
 487     </simplesect>\r
 488   </section>\r
 489 </chapter>\r