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 <xref>, <link>, and <ulink>. Additionally, there 22 are linking elements for referencing specific types of entities, 23 such as classes (<classname>), functions 24 (<functionname>), or libraries (<libraryname>).</para> 25 26 <para>The <xref> 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 <xref> 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><xref linkend="boostbook.linking"/></code>, which 34 will look like this in the text: <xref 35 linkend="boostbook.linking"/>.</para> 36 37 <para>The <link> element references an ID in the same way as 38 <xref>, except that <link> 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><link 42 linkend="boostbook.linking">like this</link></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 <ulink> 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><ulink 51 url="http://www.boost.org">Boost</ulink>,</code> which 52 appears in the document like this: <ulink 53 url="http://www.boost.org">Boost</ulink>.</para> 54 55 <para>In BoostBook, <ulink> 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><ulink 61 url="boost:/libs/flyweight/index.html">Boost.Flyweight</ulink></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 <ulink> elements. 65 It isn't available for any other elements or in Docbook.</para> 66 67 <para>The <classname>, <functionname>, 68 <methodname>, and <libraryname> 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><libraryname>Function</libraryname></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><classname 80 alt="boost::function">function</classname></code>.</para> 81 </section> 82</chapter> 83