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 the document, no equivalent of
HTML's b
and
i
. If the information being presented is
important, then consider presenting it in
important
rather than
emphasis
.
emphasis
Usage:
<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
. Most of the markup tags available
for normal text are also available from within a
quote
.
Usage:
<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
.
Usage:
<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 changes, 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 changes,
type Esc : q !.
My window manager is configured so that Alt+ mouse button is used to move windows.
Both applications and commands are frequently referred to when writing documentation. The distinction between them is that an application is the name of a program or suite of programs that fulfill a particular task. A command is the filename of a program that the user can type and run at a command line.
It is often necessary to show some of the options that a command might take.
Finally, it is often useful 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
.
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:
Therefore, the introduction to FreeBSD documentation will usually include this:
Use command
when 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.
notation to markup the first reference and use
command
.section
;command
to markup subsequent references.
This makes the generated output, especially
HTML, appear visually better.
Usage:
<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.1;, and &man.newaliases.1;
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(1), and newaliases(1) 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.
notation is easier to follow.command
.section
;
To refer to the name of a file, a directory, or a file
extension, use filename
.
filename
Usage:
<para>
The XML source for the Handbook in English is
found in <filename class="directory">
/usr/doc/en_US.ISO8859-1/books/handbook/</filename>
. The first
file is called <filename>
book.xml</filename>
in that
directory. There is also a <filename>
Makefile</filename>
and a number of files with a <filename>
.ent</filename>
extension.</para>
Appearance:
The XML source for the Handbook in English can be
found in /usr/doc/en/handbook/
. The
first file is called handbook.xml
in
that directory. There is also 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.
To include the name of a program from the FreeBSD
Ports Collection in the document, use the
filename
tag with the
role
attribute set to
package
. 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
RoleUsage:
<para>
Install the <filename role="package">
net/wireshark</filename>
port to view network traffic.</para>
Appearance:
Install the net/wireshark
port to view
network traffic.
These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD.
There are two names for devices: the device name as it
appears in /dev
, or the name of the
device as it appears in the kernel. For this latter course,
use devicename
.
Sometimes there is no choice. Some devices, such as
network cards, do not have entries in
/dev
, or the entries are markedly
different from their kernel device names.
devicename
Usage:
<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, network 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, network 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.
Identification information for networked computers (hosts)
can be marked up 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
attribute, or
role="hostname"
With no role
attribute (i.e.,
hostid
.../hostid
)
the marked up information is the simple hostname, such
as freefall
or
wcarchive
. The hostname can be
explicitly specified 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
(CIDR notation).
role="mac"
The text is an Ethernet MAC address, expressed as a series of 2 digit hexadecimal numbers separated by colons.
hostid
and RolesUsage:
<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 <acronym>
IP</acronym>
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 <acronym>
MAC</acronym>
address uniquely identifies
every network card in existence. A typical
<acronym>
MAC</acronym>
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.
To refer to a specific username, such as
root
or bin
, use
username
.
username
Usage:
<para>
To carry out most system administration functions
requires logging in as <username>
root</username>
.</para>
Appearance:
To carry out most system administration functions
requires logging in as root
.
Email addresses are marked up as
email
elements. In the HTML
output format, the wrapped text becomes a hyperlink to the
email address. Other output formats that support hyperlinks
may also make the email address into a link.
email
with a HyperlinkUsage:
<para>
An email address that does not actually exist, like
<email>
notreal@example.com</email>
, can be used as an
example.</para>
Appearance:
An email address that does not actually exist, like
<notreal@example.com>
, can be used as an
example.
A FreeBSD-specific extension allows setting the
role
attribute to nolink
to prevent the creation of the hyperlink to the email
address.
email
Without a HyperlinkUsage:
<para>
Sometimes a link to an email address like
<email role="nolink">
notreal@example.com</email>
is not
desired.</para>
Appearance:
Sometimes a link to an email address like
<notreal@example.com>
is not
desired.
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
Usage:
<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
.
Literal text, or text which should be entered verbatim, is often needed in documentation. This is text that is excerpted from another file, or which should be copied exactly as shown from the documentation into another file.
Some of the time, programlisting
will
be sufficient to denote this text. But
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
Usage:
<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 the user is shown what to do, or referred to a file or command line, but cannot simply copy the example provided. Instead, they must supply 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
Usage:
<screen>
&prompt.user; <userinput>
man <replaceable>
command</replaceable>
</userinput>
</screen>
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.
Usage:
<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
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.n
For a desktop workstation, 32
is a
good value for n
.
Buttons presented by a graphical user interface are marked
with guibutton
. To make the text look more
like a graphical button, brackets and non-breaking spaces are
added surrounding the text.
guibutton
Usage:
<para>
Edit the file, then click
<guibutton>
[ Save ]</guibutton>
to save the
changes.</para>
Appearance:
Edit the file, then click
to save the changes.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>.