ceph/src/boost/tools/boostbook/doc/together.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!--
   3    Copyright (c) 2002 Douglas Gregor <doug.gregor -at- gmail.com>
   4
   5    Distributed under the Boost Software License, Version 1.0.
   6    (See accompanying file LICENSE_1_0.txt or copy at
   7    http://www.boost.org/LICENSE_1_0.txt)
   8   -->
   9 <!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN"
  10   "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
  11 <chapter xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook.together"
  12          last-revision="$Date$">
  13   <title>Bringing Together a BoostBook Document</title>
  14
  15   <section id="boostbook.linking">
  16     <title>Linking in BoostBook</title>
  17
  18     <para>How one links to another element in BoostBook depends
  19     greatly on the nature of the element linked and how the link
  20     should appear. There are three general linking elements:
  21     &lt;xref&gt;, &lt;link&gt;, and &lt;ulink&gt;. Additionally, there
  22     are linking elements for referencing specific types of entities,
  23     such as classes (&lt;classname&gt;), functions
  24     (&lt;functionname&gt;), or libraries (&lt;libraryname&gt;).</para>
  25
  26     <para>The &lt;xref&gt; element references elements that have an
  27     <code>id</code> attribute and a title. The actual link text is
  28     composed from title and type of the element referenced. To link to
  29     a particular ID, create an &lt;xref&gt; element with the
  30     <code>linkend</code> attribute set to the ID of the intended
  31     target. For instance, this section's ID is
  32     <code>boostbook.linking</code>, so we create a reference it to
  33     with <code>&lt;xref linkend="boostbook.linking"/&gt;</code>, which
  34     will look like this in the text: <xref
  35     linkend="boostbook.linking"/>.</para>
  36
  37     <para>The &lt;link&gt; element references an ID in the same way as
  38     &lt;xref&gt;, except that &lt;link&gt; does not generate any text
  39     for the link, so text must be supplied within the element. For
  40     instance, we can again link to this chapter but this time specify
  41     our own text with <code>&lt;link
  42     linkend="boostbook.linking"&gt;like this&lt;/link&gt;</code>. This
  43     markup will result in a link to this chapter that looks <link
  44     linkend="boostbook.linking">like this</link>.</para>
  45
  46     <para>The &lt;ulink&gt; element references a URL that is outside
  47     of the DocBook document. The <code>url</code> attribute contains
  48     the URL to link to, and the element data provides the link
  49     text.For instance, we can link to the the Boost web site with
  50     <code>&lt;ulink
  51     url="http://www.boost.org"&gt;Boost&lt;/ulink&gt;,</code> which
  52     appears in the document like this: <ulink
  53     url="http://www.boost.org">Boost</ulink>.</para>
  54
  55     <para>In BoostBook, &lt;ulink&gt; supports a custom url schema for
  56     linking to files within the boost distribution. This is formed by
  57     setting the <code>url</code> attribute to <code>boost:</code>
  58     followed by the file's path. For example, we can link to the
  59     flyweight library with
  60     <code>&lt;ulink
  61     url="boost:/libs/flyweight/index.html"&gt;Boost.Flyweight&lt;/ulink&gt;</code>,
  62     which will appear like this: <ulink
  63     url="boost:/libs/flyweight/index.html">Boost.Flyweight</ulink>.
  64     This schema is only supported for BoostBook &lt;ulink&gt; elements.
  65     It isn't available for any other elements or in Docbook.</para>
  66
  67     <para>The &lt;classname&gt;, &lt;functionname&gt;,
  68     &lt;methodname&gt;, and &lt;libraryname&gt; link to classes,
  69     functions, methods, and libraries, respectively. The text of each
  70     element gives both the name of the element to link to and the link
  71     text. For instance, we can link to the Function library with
  72     <code>&lt;libraryname&gt;Function&lt;/libraryname&gt;</code>,
  73     which results in the following:
  74     <libraryname>Function</libraryname>. In cases where the displayed
  75     text is different from the actual name, the <code>alt</code>
  76     attribute can be specified. For instance, the following XML
  77     element references the <classname>boost::function</classname>
  78     class template but displays the text <classname
  79     alt="boost::function">function</classname>: <code>&lt;classname
  80     alt="boost::function"&gt;function&lt;/classname&gt;</code>.</para>
  81   </section>
  82 </chapter>