| <?xml version="1.0" encoding="utf-8"?> |
| <!-- |
| Copyright (c) 2002 Douglas Gregor <doug.gregor -at- gmail.com> |
| |
| Distributed under the Boost Software License, Version 1.0. |
| (See accompanying file LICENSE_1_0.txt or copy at |
| http://www.boost.org/LICENSE_1_0.txt) |
| --> |
| <!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" |
| "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> |
| <chapter xmlns:xi="http://www.w3.org/2001/XInclude" id="boostbook.together" |
| last-revision="$Date: 2009-04-15 03:37:45 -0400 (Wed, 15 Apr 2009) $"> |
| <title>Bringing Together a BoostBook Document</title> |
| |
| <section id="boostbook.linking"> |
| <title>Linking in BoostBook</title> |
| |
| <para>How one links to another element in BoostBook depends |
| greatly on the nature of the element linked and how the link |
| should appear. There are three general linking elements: |
| <xref>, <link>, and <ulink>. Additionally, there |
| are linking elements for referencing specific types of entities, |
| such as classes (<classname>), functions |
| (<functionname>), or libraries (<libraryname>).</para> |
| |
| <para>The <xref> element references elements that have an |
| <code>id</code> attribute and a title. The actual link text is |
| composed from title and type of the element referenced. To link to |
| a particular ID, create an <xref> element with the |
| <code>linkend</code> attribute set to the ID of the intended |
| target. For instance, this section's ID is |
| <code>boostbook.linking</code>, so we create a reference it to |
| with <code><xref linkend="boostbook.linking"/></code>, which |
| will look like this in the text: <xref |
| linkend="boostbook.linking"/>.</para> |
| |
| <para>The <link> element references an ID in the same way as |
| <xref>, except that <link> does not generate any text |
| for the link, so text must be supplied within the element. For |
| instance, we can again link to this chapter but this time specify |
| our own text with <code><link |
| linkend="boostbook.linking">like this</link></code>. This |
| markup will result in a link to this chapter that looks <link |
| linkend="boostbook.linking">like this</link>.</para> |
| |
| <para>The <ulink> element references a URL that is outside |
| of the DocBook document. The <code>url</code> attribute contains |
| the URL to link to, and the element data provides the link |
| text.For instance, we can link to the the Boost web site with |
| <code><ulink |
| url="http://www.boost.org">Boost</ulink>,</code> which |
| appears in the document like this: <ulink |
| url="http://www.boost.org">Boost</ulink>.</para> |
| |
| <para>In BoostBook, <ulink> supports a custom url schema for |
| linking to files within the boost distribution. This is formed by |
| setting the <code>url</code> attribute to <code>boost:</code> |
| followed by the file's path. For example, we can link to the |
| flyweight library with |
| <code><ulink |
| url="boost:/libs/flyweight/index.html">Boost.Flyweight</ulink></code>, |
| which will appear like this: <ulink |
| url="boost:/libs/flyweight/index.html">Boost.Flyweight</ulink>. |
| This schema is only supported for BoostBook <ulink> elements. |
| It isn't available for any other elements or in Docbook.</para> |
| |
| <para>The <classname>, <functionname>, |
| <methodname>, and <libraryname> link to classes, |
| functions, methods, and libraries, respectively. The text of each |
| element gives both the name of the element to link to and the link |
| text. For instance, we can link to the Function library with |
| <code><libraryname>Function</libraryname></code>, |
| which results in the following: |
| <libraryname>Function</libraryname>. In cases where the displayed |
| text is different from the actual name, the <code>alt</code> |
| attribute can be specified. For instance, the following XML |
| element references the <classname>boost::function</classname> |
| class template but displays the text <classname |
| alt="boost::function">function</classname>: <code><classname |
| alt="boost::function">function</classname></code>.</para> |
| </section> |
| </chapter> |