DocBook was originally developed by HaL Computer Systems and O'Reilly & Associates to be a DTD for writing technical documentation [3]. Since 1998 it is maintained by the DocBook Technical Committee. As such, and unlike LinuxDoc and HTML, DocBook is very heavily oriented towards markup that describes what something is, rather than describing how it should be presented.
formal
vs. informal
: Some elements may exist in two forms, formal and informal. Typically, the formal version of the element will consist of a title followed by the informal version of the element. The informal version will not have a title.
The DocBook DTD is available from the ports collection in the textproc/docbook port. It is automatically installed as part of the textproc/docproj port.
The FreeBSD Documentation Project has extended the DocBook DTD by adding some new elements. These elements serve to make some of the markup more precise.
Where a FreeBSD specific element is listed below it is clearly marked.
Throughout the rest of this document, the term “DocBook” is used to mean the FreeBSD extended DocBook DTD.
There is nothing about these extensions that is FreeBSD
specific, it was just felt that they were useful enhancements for
this particular project. Should anyone from any of the other *nix
camps (NetBSD, OpenBSD, Linux, …) be interested in
collaborating on a standard DocBook extension set, please get in
touch with Documentation Engineering Team <doceng@FreeBSD.org>
.
The FreeBSD extensions are not (currently) in the ports collection. They are stored in the FreeBSD CVS tree, as doc/share/xml/freebsd.dtd.
In compliance with the DocBook guidelines for writing FPIs for DocBook customizations, the FPI for the FreeBSD extended DocBook DTD is:
PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"
DocBook allows you to structure your documentation in several ways. In the FreeBSD Documentation Project we are using two primary types of DocBook document: the book and the article.
A book is organized into chapter
s. This is a
mandatory requirement. There may be part
s between
the book and the chapter to provide another layer of organization.
The Handbook is arranged in this way.
A chapter may (or may not) contain one or more sections. These
are indicated with the sect1
element. If a section
contains another section then use the sect2
element, and so on, up to sect5
.
Chapters and sections contain the remainder of the content.
An article is simpler than a book, and does not use chapters.
Instead, the content of an article is organized into one or more
sections, using the same sect1
(and
sect2
and so on) elements that are used in
books.
Obviously, you should consider the nature of the documentation you are writing in order to decide whether it is best marked up as a book or an article. Articles are well suited to information that does not need to be broken down into several chapters, and that is, relatively speaking, quite short, at up to 20-25 pages of content. Books are best suited to information that can be broken up into several chapters, possibly with appendices and similar content as well.
The FreeBSD tutorials are all marked up as articles, while this document, the FreeBSD FAQ, and the FreeBSD Handbook are all marked up as books.
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
with
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>
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
with
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>
Use chapter
to mark up your chapters. Each
chapter has a mandatory title
. Articles do not
contain chapters, they are reserved for books.
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.
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
sect
element. The
n
n
indicates the section number, which
identifies the section level.
The first sect
is
n
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>
This example includes section numbers in the section titles. You should not do this in your documents. Adding the section numbers is carried out by the stylesheets (of which more later), and you do not need to manage them yourself.
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>
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
Use:
<para>This is a paragraph. It can contain just about any other element.</para>
Appearance:
This is a paragraph. It can contain just about any other element.
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).
blockquote
Use:
<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>
Appearance:
Preamble to the Constitution of the United States 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. | ||
--Copied from a web site somewhere |
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
Use:
<warning> <para>Installing FreeBSD may make you want to delete Windows from your hard disk.</para> </warning>
Installing FreeBSD may make you want to delete Windows from your hard disk.
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
[4]
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
,
orderedlist
, and
procedure
Use:
<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>
Appearance:
This is the first itemized item.
This is the second itemized item.
This is the first ordered item.
This is the second ordered item.
Do this.
Then do this.
And now do this.
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.
programlisting
Use:
<para>When you have finished, your program should look like this:</para> <programlisting>#include <stdio.h> int main(void) { printf("hello, world\n"); }</programlisting>
Notice how the angle brackets in the
#include
line need to be referenced by their
entities instead of being included literally.
Appearance:
When you have finished, your program should look like this:
#include <stdio.h> int main(void) { printf("hello, world\n"); }
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.
co
and
calloutlist
<para>When you have finished, your program should look like this:</para> <programlisting>#include <stdio.h> <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>
Appearance:
When you have finished, your program should look like this:
#include <stdio.h>int
main(void) { printf("hello, world\n");
}
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
Use:
<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>
Appearance:
This is column head 1 | This is column head 2 |
---|---|
Row 1, column 1 | Row 1, column 2 |
Row 2, column 1 | Row 2, column 2 |
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">
).
frame="none"
Appearance:
This is column head 1 | This is column head 2 |
---|---|
Row 1, column 1 | Row 1, column 2 |
Row 2, column 1 | Row 2, column 2 |
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
Everything the user sees in this example will be on the
computer screen, so the next element is
screen
.
Within screen
, white space is
significant.
prompt
,
&prompt.root;
and
&prompt.user;
Some of the things the user will be seeing on the screen
are prompts from the computer (either from the operating system, command
shell, or application). These should be marked up using
prompt
.
As a special case, the two shell prompts for the normal
user and the root user have been provided as entities. Every
time you want to indicate the user is at a shell prompt, use
one of &prompt.root;
and
&prompt.user;
as necessary. They do
not need to be inside prompt
.
&prompt.root;
and
&prompt.user;
are FreeBSD
extensions to DocBook, and are not part of the original
DTD.
userinput
When displaying text that the user should type in, wrap it
in userinput
tags. It will probably be
displayed differently to the user.
screen
, prompt
, and
userinput
Use:
<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>
Appearance:
%
ls -1
foo1 foo2 foo3%
ls -1 | grep foo2
foo2%
su
Password:
#
cat foo2
This is the file called 'foo2'
Even though we are displaying the contents of the file
foo2
, it is not marked
up as programlisting
. Reserve
programlisting
for showing fragments of files
outside the context of user actions.
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
.
emphasis
Use:
<para>FreeBSD is without doubt <emphasis>the</emphasis> premiere Unix like operating system for the Intel architecture.</para>
Appearance:
FreeBSD is without doubt the premiere Unix like operating system for the Intel architecture.
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.
Use:
<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>
Appearance:
However, make sure that the search does not go beyond the “boundary between local and public administration”, as RFC 1535 calls it.
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
.
Use:
<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>
Appearance:
To switch to the second virtual terminal, press Alt+F1.
To exit vi
without saving your work, type
Esc : q !.
My window manager is configured so that Alt+ mouse button is used to move windows.
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/xml/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.
Use:
<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>
Appearance:
Sendmail is the most widely used Unix mail application.
Sendmail includes the sendmail(8), mailq(8), and newaliases(8) programs.
One of the command line parameters to sendmail(8), -bp
, will display the current
status of messages in the mail queue. Check this on the command
line by running sendmail -bp
.
Notice how the
&man.command.section;
notation is easier to follow.
Whenever you wish to refer to the name of a file, a directory,
or a file extension, use filename
.
filename
Use:
<para>The SGML source for the Handbook in English can be found in <filename>/usr/doc/en/handbook/</filename>. The first file is called <filename>handbook.xml</filename> in that directory. You should also see a <filename>Makefile</filename> and a number of files with a <filename>.ent</filename> extension.</para>
Appearance:
The SGML source for the Handbook in English can be found in
/usr/doc/en/handbook/
. The first file is
called handbook.xml
in that directory. You
should also see a Makefile
and a number of
files with a .ent
extension.
These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD.
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
.
filename
tag with
package
roleUse:
<para>Install the <filename role="package">net/ethereal</filename> port to view network traffic.</para>
Appearance:
Install the net/ethereal port to view network traffic.
These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD.
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.
devicename
Use:
<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>
Appearance:
sio
is used for serial communication
in FreeBSD. sio
manifests through a
number of entries in /dev
, including
/dev/ttyd0
and
/dev/cuaa0
.
By contrast, the networking devices, such as
ed0
do not appear in
/dev
.
In MS-DOS, the first floppy drive is referred to as
a:
. In FreeBSD it is
/dev/fd0
.
These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD.
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.
role="hostname"
With no role attribute (i.e.,
hostid
.../hostid
) the
marked up information is the simple hostname, such as
freefall
or wcarchive
.
You can explicitly specify this with
role="hostname"
.
role="domainname"
The text is a domain name, such as
FreeBSD.org
or
ngo.org.uk
. There is no hostname
component.
role="fqdn"
The text is a Fully Qualified Domain Name, with both hostname and domain name parts.
role="ipaddr"
The text is an IP address, probably expressed as a dotted quad.
role="ip6addr"
The text is an IPv6 address.
role="netmask"
The text is a network mask, which might be expressed as a
dotted quad, a hexadecimal string, or as a
/
followed by a number.
role="mac"
The text is an Ethernet MAC address, expressed as a series of 2 digit hexadecimal numbers separated by colons.
hostid
and rolesUse:
<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>
Appearance:
The local machine can always be referred to by the name
localhost
, which will have the IP address 127.0.0.1
.
The FreeBSD.org
domain
contains a number of different hosts, including freefall.FreeBSD.org
and bento.FreeBSD.org
.
When adding an IP alias to an interface (using
ifconfig
) always use a
netmask of 255.255.255.255
(which
can also be expressed as 0xffffffff
.
The MAC address uniquely identifies every network card in
existence. A typical MAC address looks like 08:00:20:87:ef:d0
.
These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD.
When you need to refer to a specific username, such as
root
or bin
, use
username
.
username
Use:
<para>To carry out most system administration functions you will need to be <username>root</username>.</para>
Appearance:
To carry out most system administration functions you will
need to be root
.
These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD.
Two elements exist to describe parts of
Makefile
s, 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.
maketarget
and
makevar
Use:
<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>
Appearance:
Two common targets in a Makefile
are
all
and
clean
.
Typically, invoking all
will rebuild
the application, and invoking clean
will
remove the temporary files (.o
for example)
created by the build process.
clean
may be controlled by a number
of variables, including CLOBBER
and
RECURSE
.
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
.
literal
Use:
<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>
Appearance:
The maxusers 10
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.
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.
replaceable
Use:
<informalexample> <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> </informalexample>
Appearance:
%
man command
replaceable
can be used in many different
elements, including literal
. This example also
shows that replaceable
should only be wrapped
around the content that the user is meant to
provide. The other content should be left alone.
Use:
<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>
Appearance:
The maxusers n
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.
For a desktop workstation, 32
is a good
value for n
.
Image support in the documentation is currently extremely experimental. I think the mechanisms described here are unlikely to change, but that is not guaranteed.
You will also need to install the
graphics/ImageMagick port, which is used to
convert between the different image formats. This is a big port,
and most of it is not required. However, while we are working on the
Makefile
s and other infrastructure it makes
things easier. This port is not in the
textproc/docproj meta port, you must install it
by hand.
The best example of what follows in practice is the
doc/en_US.ISO8859-1/articles/vm-design/
document.
If you are unsure of the description that follows, take a look at the
files in that directory to see how everything hangs together.
Experiment with creating different formatted versions of the
document to see how the image markup appears in the formatted
output.
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
Makefile
s 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.
It is anticipated that the Documentation Project will switch to using the Scalable Vector Graphic (SVG) format for vector images. However, the current state of SVG capable editing tools makes this impractical.
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.png
, 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>
Include an | |
The first Notice how the first and last lines of the content of the
| |
The second |
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.
You must be careful when you separate your documentation into smaller files (see 節 3.7.1, “Using general entities to include files”) in different directories.
Suppose you have a book with three chapters, and the chapters
are stored in their own directories, called
chapter1/chapter.xml
,
chapter2/chapter.xml
, and
chapter3/chapter.xml
. 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.xml
should
contain:
<mediaobject> <imageobject> <imagedata fileref="chapter1/fig1"></imageobject> … </mediaobject>
The Makefile
must contain:
… IMAGES= chapter1/fig1.png …
Then everything should just work.
Links are also in-line elements.
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.
id on chapters and sections
<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.
anchor
<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.
xref
Assume that this fragment appears somewhere in a document that
includes the id
example:
<para>More information can be found in <xref linkend="chapter1">.</para> <para>More specific information can be found in <xref linkend="chapter1-sect1">.</para>
The text of the link will be generated automatically, and will look like (emphasized text indicates the text that will be the link):
More information can be found in Chapter One.
More specific information can be found in the section called Sub-sect 1.
Notice how the text from the link is derived from the section title or the chapter number.
This means that you cannot use
xref
to link to an id
attribute on an anchor
element. The
anchor
has no content, so the
xref
cannot generate the text for the
link.
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.
link
Assume that this fragment appears somewhere in a document that
includes the id
example.
<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>
This will generate the following (emphasized text indicates the text that will be the link):
More information can be found in the first chapter.
More specific information can be found in this section.
That last one is a bad example. Never use words like “this” or “here” as the source for the link. The reader will need to hunt around the surrounding context to see where the link is actually taking them.
You can use link
to
include a link to an id
on an
anchor
element, since the
link
content defines the text that will be used
for the link.
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.
ulink
Use:
<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>
Appearance:
Of course, you could stop reading this document and go to the FreeBSD home page instead.
[3] A short history can be found under http://www.oasis-open.org/committees/docbook/intro.shtml.
[4] There are other types of list element in DocBook, but we are not concerned with those at the moment.
All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.