4.2 DocBook

4.2.3.1 Starting a book

　　The content of the book is contained within the <book> element. As well as containing structural markup, this element can contain elements that include additional information about the book. This is either meta-information, used for reference purposes, or additional content used to produce a title page.

　　This additional information should be contained within <bookinfo>.

<book>
  <bookinfo>
    <title>Your title here</title>
    
    <author>
      <firstname>Your first name</firstname>
      <surname>Your surname</surname>
      <affiliation>
        <address><email>Your email address</email></address>
      </affiliation>
    </author>

    <copyright>
      <year>1998</year>
      <holder role="mailto:your email address">Your name</holder>
    </copyright>

    <releaseinfo>$FreeBSD$</releaseinfo>

    <abstract>
      <para>Include an abstract of the book's contents here.</para>
    </abstract>
  </bookinfo>

  ...

</book>

4.2.3.2 Starting an article

　　The content of the article is contained within the <article> element. As well as containing structural markup, this element can contain elements that include additional information about the article. This is either meta-information, used for reference purposes, or additional content used to produce a title page.

　　This additional information should be contained within <articleinfo>.

<article>
  <articleinfo>
    <title>Your title here</title>
    
    <author>
      <firstname>Your first name</firstname>
      <surname>Your surname</surname>
      <affiliation>
        <address><email>Your email address</email></address>
      </affiliation>
    </author>

    <copyright>
      <year>1998</year>
      <holder role="mailto:your email address">Your name</holder>
    </copyright>

    <releaseinfo>$FreeBSD$</releaseinfo>

    <abstract>
      <para>Include an abstract of the article's contents here.</para>
    </abstract>
  </articleinfo>

  ...

</article>

4.2.3.3 Indicating chapters

　　Use <chapter> to mark up your chapters. Each chapter has a mandatory <title>. Articles do not contain chapters, they are reserved for books.

<chapter>
  <title>The chapter's title</title>

  ...
</chapter>

　　A chapter cannot be empty; it must contain elements in addition to <title>. If you need to include an empty chapter then just use an empty paragraph.

<chapter>
  <title>This is an empty chapter</title>

  <para></para>
</chapter>

4.2.3.4 Sections below chapters

　　In books, chapters may (but do not need to) be broken up into sections, subsections, and so on. In articles, sections are the main structural element, and each article must contain at least one section. Use the <sectn> element. The n indicates the section number, which identifies the section level.

　　The first <sectn> is <sect1>. You can have one or more of these in a chapter. They can contain one or more <sect2> elements, and so on, down to <sect5>.

<chapter>
  <title>A sample chapter</title>

  <para>Some text in the chapter.</para>

  <sect1>
    <title>First section (1.1)</title>

    ...
  </sect1>

  <sect1>
    <title>Second section (1.2)</title>

    <sect2>
      <title>First sub-section (1.2.1)</title>

      <sect3>
        <title>First sub-sub-section (1.2.1.1)</title>

        ...
      </sect3>
    </sect2>

    <sect2>
      <title>Second sub-section (1.2.2)</title>

      ...
    </sect2>
  </sect1>
</chapter>

4.2.3.5 Subdividing using <part>s

　　You can introduce another layer of organization between <book> and <chapter> with one or more <part>s. This cannot be done in an <article>.

<part>
  <title>Introduction</title>

  <chapter>
    <title>Overview</title>

    ...
  </chapter>

  <chapter>
    <title>What is FreeBSD?</title>

    ...
  </chapter>

  <chapter>
    <title>History</title>

    ...
  </chapter>
</part>

4.2.4.1 Paragraphs

　　DocBook supports three types of paragraphs: <formalpara>, <para>, and <simpara>.

　　Most of the time you will only need to use <para>. <formalpara> includes a <title> element, and <simpara> disallows some elements from within <para>. Stick with <para>.

<para>This is a paragraph.  It can contain just about any
  other element.</para>

4.2.4.2 Block quotations

　　A block quotation is an extended quotation from another document that should not appear within the current paragraph. You will probably only need it infrequently.

　　Blockquotes can optionally contain a title and an attribution (or they can be left untitled and unattributed).

<para>A small excerpt from the US Constitution:</para>
          
<blockquote>
  <title>Preamble to the Constitution of the United States</title>

  <attribution>Copied from a web site somewhere</attribution>
        
  <para>We the People of the United States, in Order to form a more perfect
    Union, establish Justice, insure domestic Tranquility, provide for the
    common defence, promote the general Welfare, and secure the Blessings
    of Liberty to ourselves and our Posterity, do ordain and establish this
    Constitution for the United States of America.</para>
</blockquote>

4.2.4.3 Tips, notes, warnings, cautions, important information and sidebars.

　　You may need to include extra information separate from the main body of the text. Typically this is “meta” information that the user should be aware of.

　　Depending on the nature of the information, one of <tip>, <note>, <warning>, <caution>, and <important> should be used. Alternatively, if the information is related to the main text but is not one of the above, use <sidebar>.

　　The circumstances in which to choose one of these elements over another is unclear. The DocBook documentation suggests:

• A Note is for information that should be heeded by all readers.

• An Important element is a variation on Note.

• A Caution is for information regarding possible data loss or software damage.

• A Warning is for information regarding possible hardware damage or injury to life or limb.

<warning>
  <para>Installing FreeBSD may make you want to delete Windows from your
    hard disk.</para>
</warning>

4.2.4.4 Lists and procedures

　　You will often need to list pieces of information to the user, or present them with a number of steps that must be carried out in order to accomplish a particular goal.

　　In order to do this, use <itemizedlist>, <orderedlist>, or <procedure>[2]

　　<itemizedlist> and <orderedlist> are similar to their counterparts in HTML, <ul> and <ol>. Each one consists of one or more <listitem> elements, and each <listitem> contains one or more block elements. The <listitem> elements are analogous to HTML's <li> tags. However, unlike HTML, they are required.

　　<procedure> is slightly different. It consists of <step>s, which may in turn consists of more <step>s or <substep>s. Each <step> contains block elements.

<itemizedlist>
  <listitem>
    <para>This is the first itemized item.</para>
  </listitem>

  <listitem>
    <para>This is the second itemized item.</para>
  </listitem>
</itemizedlist>

<orderedlist>
  <listitem>
    <para>This is the first ordered item.</para>
  </listitem>

  <listitem>
    <para>This is the second ordered item.</para>
  </listitem>
</orderedlist>

<procedure>
  <step>
    <para>Do this.</para>
  </step>

  <step>
    <para>Then do this.</para>
  </step>

  <step>
    <para>And now do this.</para>
  </step>
</procedure>

4.2.4.5 Showing file samples

　　If you want to show a fragment of a file (or perhaps a complete file) to the user, wrap it in the <programlisting> element.

　　White space and line breaks within <programlisting> are significant. In particular, this means that the opening tag should appear on the same line as the first line of the output, and the closing tag should appear on the same line as the last line of the output, otherwise spurious blank lines may be included.

<para>When you have finished, your program should look like
  this:</para>

<programlisting>#include &lt;stdio.h&gt;

int
main(void)
{
    printf("hello, world\n");
}</programlisting>

#include <stdio.h>

int
main(void)
{
    printf("hello, world\n");
}

4.2.4.6 Callouts

　　A callout is a mechanism for referring back to an earlier piece of text or specific position within an earlier example without linking to it within the text.

　　To do this, mark areas of interest in your example (<programlisting>, <literallayout>, or whatever) with the <co> element. Each element must have a unique id assigned to it. After the example include a <calloutlist> that refers back to the example and provides additional commentary.

<para>When you have finished, your program should look like
  this:</para>

<programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include">

int <co id="co-ex-return">
main(void)
{
    printf("hello, world\n"); <co id="co-ex-printf">
}</programlisting>

<calloutlist>
  <callout arearefs="co-ex-include">
    <para>Includes the standard IO header file.</para>
  </callout>

  <callout arearefs="co-ex-return">
    <para>Specifies that <function>main()</function> returns an
      int.</para>
  </callout>

  <callout arearefs="co-ex-printf">
    <para>The <function>printf()</function> call that writes
      <literal>hello, world</literal> to standard output.</para>
  </callout>
</calloutlist>

#include <stdio.h> 

int 
main(void)
{
    printf("hello, world\n"); 
}

4.2.4.7 Tables

　　Unlike HTML, you do not need to use tables for layout purposes, as the stylesheet handles those issues for you. Instead, just use tables for marking up tabular data.

　　In general terms (and see the DocBook documentation for more detail) a table (which can be either formal or informal) consists of a <table> element. This contains at least one <tgroup> element, which specifies (as an attribute) the number of columns in this table group. Within the tablegroup you can then have one <thead> element, which contains elements for the table headings (column headings), and one <tbody> which contains the body of the table.

　　Both <tgroup> and <thead> contain <row> elements, which in turn contain <entry> elements. Each <entry> element specifies one cell in the table.

<informaltable frame="none" pgwide="1">
  <tgroup cols="2">
    <thead>
      <row>
        <entry>This is column head 1</entry>
        <entry>This is column head 2</entry>
      </row>
    </thead>

    <tbody>
      <row>
        <entry>Row 1, column 1</entry>
        <entry>Row 1, column 2</entry>
      </row>

      <row>
        <entry>Row 2, column 1</entry>
        <entry>Row 2, column 2</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>

　　Always use the pgwide attribute with a value of 1 with the <informaltable> element. A bug in Internet Explorer can cause the table to render incorrectly if this is omitted.

　　If you do not want a border around the table the frame attribute can be added to the <informaltable> element with a value of none (i.e., <informaltable frame="none">).

4.2.4.8 Examples for the user to follow

　　A lot of the time you need to show examples for the user to follow. Typically, these will consist of dialogs with the computer; the user types in a command, the user gets a response back, they type in another command, and so on.

　　A number of distinct elements and entities come into play here.

<screen>&prompt.user; <userinput>ls -1</userinput>
foo1
foo2
foo3
&prompt.user; <userinput>ls -1 | grep foo2</userinput>
foo2
&prompt.user; <userinput>su</userinput>
<prompt>Password: </prompt>
&prompt.root; <userinput>cat foo2</userinput>
This is the file called 'foo2'</screen>

% ls -1
foo1
foo2
foo3
% ls -1 | grep foo2
foo2
% su
Password: 
# cat foo2
This is the file called 'foo2'

4.2.5.1 Emphasizing information

　　When you want to emphasize a particular word or phrase, use <emphasis>. This may be presented as italic, or bold, or might be spoken differently with a text-to-speech system.

　　There is no way to change the presentation of the emphasis within your document, no equivalent of HTML's <b> and <i>. If the information you are presenting is important then consider presenting it in <important> rather than <emphasis>.

<para>FreeBSD is without doubt <emphasis>the</emphasis>
  premiere Unix like operating system for the Intel architecture.</para>

4.2.5.2 Quotations

　　To quote text from another document or source, or to denote a phrase that is used figuratively, use <quote>. Within a <quote> tag, you may use most of the markup tags available for normal text.

<para>However, make sure that the search does not go beyond the
  <quote>boundary between local and public administration</quote>,
  as RFC 1535 calls it.</para>

4.2.5.3 Keys, mouse buttons, and combinations

　　To refer to a specific key on the keyboard, use <keycap>. To refer to a mouse button, use <mousebutton>. And to refer to combinations of key presses or mouse clicks, wrap them all in <keycombo>.

　　<keycombo> has an attribute called action, which may be one of click, double-click, other, press, seq, or simul. The last two values denote whether the keys or buttons should be pressed in sequence, or simultaneously.

　　The stylesheets automatically add any connecting symbols, such as +, between the key names, when wrapped in <keycombo>.

<para>To switch to the second virtual terminal, press 
  <keycombo action="simul"><keycap>Alt</keycap>
    <keycap>F1</keycap></keycombo>.</para>

<para>To exit <command>vi</command> without saving your work, type
  <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap>
    <keycap>q</keycap><keycap>!</keycap></keycombo>.</para>

<para>My window manager is configured so that
  <keycombo action="simul"><keycap>Alt</keycap>
    <mousebutton>right</mousebutton>
  </keycombo> mouse button is used to move windows.</para>

4.2.5.4 Applications, commands, options, and cites

　　You will frequently want to refer to both applications and commands when writing for the Handbook. The distinction between them is simple: an application is the name for a suite (or possibly just 1) of programs that fulfil a particular task. A command is the name of a program that the user can run.

　　In addition, you will occasionally need to list one or more of the options that a command might take.

　　Finally, you will often want to list a command with its manual section number, in the “command(number)” format so common in Unix manuals.

　　Mark up application names with <application>.

　　When you want to list a command with its manual section number (which should be most of the time) the DocBook element is <citerefentry>. This will contain a further two elements, <refentrytitle> and <manvolnum>. The content of <refentrytitle> is the name of the command, and the content of <manvolnum> is the manual page section.

　　This can be cumbersome to write, and so a series of general entities have been created to make this easier. Each entity takes the form &man.manual-page.manual-section;.

　　The file that contains these entities is in doc/share/sgml/man-refs.ent, and can be referred to using this FPI:

PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"

　　Therefore, the introduction to your documentation will probably look like this:

<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [

<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;

...

]>

　　Use <command> when you want to include a command name “in-line” but present it as something the user should type in.

　　Use <option> to mark up the options which will be passed to a command.

　　When referring to the same command multiple times in close proximity it is preferred to use the &man.command.section; notation to markup the first reference and use <command> to markup subsequent references. This makes the generated output, especially HTML, appear visually better.

　　This can be confusing, and sometimes the choice is not always clear. Hopefully this example makes it clearer.

<para><application>Sendmail</application> is the most
  widely used Unix mail application.</para>

<para><application>Sendmail</application> includes the
  <citerefentry>
    <refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum>
  </citerefentry>, &man.mailq.8;, and &man.newaliases.8;
  programs.</para>

<para>One of the command line parameters to <citerefentry>
    <refentrytitle>sendmail</refentrytitle>
    <manvolnum>8</manvolnum>
  </citerefentry>, <option>-bp</option>, will display the current
  status of messages in the mail queue.  Check this on the command
  line by running <command>sendmail -bp</command>.</para>

4.2.5.5 Files, directories, extensions

　　Whenever you wish to refer to the name of a file, a directory, or a file extension, use <filename>.

<para>The SGML source for the Handbook in English can be
  found in <filename class="directory">/usr/doc/en/handbook/</filename>.  The first
  file is called <filename>handbook.sgml</filename> in that
  directory.  You should also see a <filename>Makefile</filename>
  and a number of files with a <filename>.ent</filename>
  extension.</para>

4.2.5.6 The name of ports

　　You might need to include the name of a program from the FreeBSD Ports Collection in the documentation. Use the <filename> tag with the role attribute set to package to identify these. Since ports can be installed in any number of locations, only include the category and the port name; do not include /usr/ports.

<para>Install the <filename role="package">net/ethereal</filename> port to view network traffic.</para>

4.2.5.7 Devices

　　When referring to devices you have two choices. You can either refer to the device as it appears in /dev, or you can use the name of the device as it appears in the kernel. For this latter course, use <devicename>.

　　Sometimes you will not have a choice. Some devices, such as networking cards, do not have entries in /dev, or the entries are markedly different from those entries.

<para><devicename>sio</devicename> is used for serial
  communication in FreeBSD.  <devicename>sio</devicename> manifests
  through a number of entries in <filename>/dev</filename>, including
  <filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para>

<para>By contrast, the networking devices, such as
  <devicename>ed0</devicename> do not appear in <filename>/dev</filename>.</para>

<para>In MS-DOS, the first floppy drive is referred to as
  <devicename>a:</devicename>.  In FreeBSD it is
  <filename>/dev/fd0</filename>.</para>

4.2.5.8 Hosts, domains, IP addresses, and so forth

　　You can markup identification information for networked computers (hosts) in several ways, depending on the nature of the information. All of them use <hostid> as the element, with the role attribute selecting the type of the marked up information.

<para>The local machine can always be referred to by the
  name <hostid>localhost</hostid>, which will have the IP address
  <hostid role="ipaddr">127.0.0.1</hostid>.</para>

<para>The <hostid role="domainname">FreeBSD.org</hostid> domain
  contains a number of different hosts, including
  <hostid role="fqdn">freefall.FreeBSD.org</hostid> and
  <hostid role="fqdn">bento.FreeBSD.org</hostid>.</para>

<para>When adding an IP alias to an interface (using
  <command>ifconfig</command>) <emphasis>always</emphasis> use a
  netmask of <hostid role="netmask">255.255.255.255</hostid>
  (which can also be expressed as <hostid
    role="netmask">0xffffffff</hostid>.</para>

<para>The MAC address uniquely identifies every network card
  in existence.  A typical MAC address looks like <hostid
    role="mac">08:00:20:87:ef:d0</hostid>.</para>

4.2.5.9 Usernames

　　When you need to refer to a specific username, such as root or bin, use <username>.

<para>To carry out most system administration functions you
  will need to be <username>root</username>.</para>

4.2.5.10 Describing Makefiles

　　Two elements exist to describe parts of Makefiles, <maketarget> and <makevar>.

　　<maketarget> identifies a build target exported by a Makefile that can be given as a parameter to make. <makevar> identifies a variable that can be set (in the environment, on the make command line, or within the Makefile) to influence the process.

<para>Two common targets in a <filename>Makefile</filename>
  are <maketarget>all</maketarget> and <maketarget>clean</maketarget>.</para>

<para>Typically, invoking <maketarget>all</maketarget> will rebuild the
  application, and invoking <maketarget>clean</maketarget> will remove
  the temporary files (<filename>.o</filename> for example) created by
  the build process.</para>

<para><maketarget>clean</maketarget> may be controlled by a number of
  variables, including <makevar>CLOBBER</makevar> and
  <makevar>RECURSE</makevar>.</para>

4.2.5.11 Literal text

　　You will often need to include “literal” text in the Handbook. This is text that is excerpted from another file, or which should be copied from the Handbook into another file verbatim.

　　Some of the time, <programlisting> will be sufficient to denote this text. <programlisting> is not always appropriate, particularly when you want to include a portion of a file “in-line” with the rest of the paragraph.

　　On these occasions, use <literal>.

<para>The <literal>maxusers 10</literal> line in the kernel
  configuration file determines the size of many system tables, and is
  a rough guide to how many simultaneous logins the system will
  support.</para>

4.2.5.12 Showing items that the user must fill in

　　There will often be times when you want to show the user what to do, or refer to a file, or command line, or similar, where the user cannot simply copy the examples that you provide, but must instead include some information themselves.

　　<replaceable> is designed for this eventuality. Use it inside other elements to indicate parts of that element's content that the user must replace.

<informalexample>
  <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
</informalexample>

% man command

<para>The <literal>maxusers <replaceable>n</replaceable></literal>
  line in the kernel configuration file determines the size of many system
  tables, and is a rough guide to how many simultaneous logins the system will
  support.</para>

<para>For a desktop workstation, <literal>32</literal> is a good value
  for <replaceable>n</replaceable>.</para>

4.2.5.13 Quoting system errors

　　You might want to show errors generated by FreeBSD. Mark these with <errorname>. This indicates the exact error that appears.

 
<screen><errorname>Panic: cannot mount root</errorname></screen>

“Panic: cannot mount root”

4.2.6.1 Image formats

　　We currently support two formats for images. The format you should use will depend on the nature of your image.

　　For images that are primarily vector based, such as network diagrams, time lines, and similar, use Encapsulated Postscript, and make sure that your images have the .eps extension.

　　For bitmaps, such as screen captures, use the Portable Network Graphic format, and make sure that your images have the .png extension.

　　These are the only formats in which images should be committed to the CVS repository.

　　Use the right format for the right image. It is to be expected that your documentation will have a mix of EPS and PNG images. The Makefiles ensure that the correct format image is chosen depending on the output format that you use for your documentation. Do not commit the same image to the repository in two different formats.

4.2.6.2 Markup

　　The markup for an image is relatively simple. First, markup a <mediaobject>. The <mediaobject> can contain other, more specific objects. We are concerned with two, the <imageobject> and the <textobject>.

　　You should include one <imageobject>, and two <textobject> elements. The <imageobject> will point to the name of the image file that will be used (without the extension). The <textobject> elements contain information that will be presented to the user as well as, or instead of, the image.

　　There are two circumstances where this can happen.

• When the reader is viewing the documentation in HTML. In this case, each image will need to have associated alternate text to show the user, typically whilst the image is loading, or if they hover the mouse pointer over the image.

• When the reader is viewing the documentation in plain text. In this case, each image should have an ASCII art equivalent to show the user.

　　An example will probably make things easier to understand. Suppose you have an image, called fig1, that you want to include in the document. This image is of a rectangle with an A inside it. The markup for this would be as follows.

<mediaobject>
  <imageobject>
    <imagedata fileref="fig1"> 
  </imageobject>

  <textobject>
    <literallayout class="monospaced">+---------------+ 
|       A       |
+---------------+</literallayout>
  </textobject>

  <textobject>
    <phrase>A picture</phrase> 
  </textobject>
</mediaobject>

4.2.6.3 Makefile entries

　　Your images must be listed in the Makefile in the IMAGES variable. This variable should contain the name of all your source images. For example, if you have created three figures, fig1.eps, fig2.png, fig3.png, then your Makefile should have lines like this in it.

...
IMAGES= fig1.eps fig2.png fig3.png
...

　　or

...
IMAGES=  fig1.eps
IMAGES+= fig2.png
IMAGES+= fig3.png
...

　　Again, the Makefile will work out the complete list of images it needs to build your source document, you only need to list the image files you provided.

4.2.6.4 Images and chapters in subdirectories

　　You must be careful when you separate your documentation into smaller files (see 第 3.7.1 节) in different directories.

　　Suppose you have a book with three chapters, and the chapters are stored in their own directories, called chapter1/chapter.sgml, chapter2/chapter.sgml, and chapter3/chapter.sgml. If each chapter has images associated with it, I suggest you place those images in each chapter's subdirectory (chapter1/, chapter2/, and chapter3/).

　　However, if you do this you must include the directory names in the IMAGES variable in the Makefile, and you must include the directory name in the <imagedata> element in your document.

　　For example, if you have chapter1/fig1.png, then chapter1/chapter.sgml should contain:

<mediaobject>
  <imageobject>
    <imagedata fileref="chapter1/fig1"> 
  </imageobject>

  ...

</mediaobject>

　　The Makefile must contain:

...
IMAGES=  chapter1/fig1.png
...

　　Then everything should just work.

4.2.7.1 Linking to other parts of the same document

　　Linking within the same document requires you to specify where you are linking from (i.e., the text the user will click, or otherwise indicate, as the source of the link) and where you are linking to (the link's destination).

　　Each element within DocBook has an attribute called id. You can place text in this attribute to uniquely name the element it is attached to.

　　This value will be used when you specify the link source.

　　Normally, you will only be linking to chapters or sections, so you would add the id attribute to these elements.

<chapter id="chapter1">
  <title>Introduction</title>

  <para>This is the introduction.  It contains a subsection,
    which is identified as well.</para>

  <sect1 id="chapter1-sect1">
    <title>Sub-sect 1</title>

    <para>This is the subsection.</para>
  </sect1>
</chapter>

　　Obviously, you should use more descriptive values. The values must be unique within the document (i.e., not just the file, but the document the file might be included in as well). Notice how the id for the subsection is constructed by appending text to the id of the chapter. This helps to ensure that they are unique.

　　If you want to allow the user to jump into a specific portion of the document (possibly in the middle of a paragraph or an example), use <anchor>. This element has no content, but takes an id attribute.

<para>This paragraph has an embedded
  <anchor id="para1">link target in it.  It will not show up in
  the document.</para>

　　When you want to provide the user with a link they can activate (probably by clicking) to go to a section of the document that has an id attribute, you can use either <xref> or <link>.

　　Both of these elements have a linkend attribute. The value of this attribute should be the value that you have used in a id attribute (it does not matter if that value has not yet occurred in your document; this will work for forward links as well as backward links).

　　If you use <xref> then you have no control over the text of the link. It will be generated for you.

<para>More information can be found
  in <xref linkend="chapter1">.</para>

<para>More specific information can be found
  in <xref linkend="chapter1-sect1">.</para>

　　Notice how the text from the link is derived from the section title or the chapter number.

　　If you want to control the text of the link then use <link>. This element wraps content, and the content will be used for the link.

<para>More information can be found in
  <link linkend="chapter1">the first chapter</link>.</para>

<para>More specific information can be found in
  <link linkend="chapter1-sect1">this</link> section.</para>

4.2.7.2 Linking to documents on the WWW

　　Linking to external documents is much simpler, as long as you know the URL of the document you want to link to. Use <ulink>. The url attribute is the URL of the page that the link points to, and the content of the element is the text that will be displayed for the user to activate.

<para>Of course, you could stop reading this document and
  go to the <ulink url="&url.base;/index.html">FreeBSD
  home page</ulink> instead.</para>