5e38276d23
Merged revisions 52352 via svnmerge from https://svn.boost.org/svn/boost/trunk ........ r52352 | danieljames | 2009-04-12 12:21:59 +0100 (Sun, 12 Apr 2009) | 3 lines Document 'boost:' links in boostbook & quickbook. Fixes #2861. ........ [SVN r52398]
83 lines
4.1 KiB
XML
83 lines
4.1 KiB
XML
<?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$">
|
|
<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>
|