5.6. In-line Elements
Prev | Chapter 5. DocBook Markup | Next

## 5.6. In-line Elements

### 5.6.1. Emphasizing Information

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`.

Example 5.15. `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.

### 5.6.2. Quotations

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`.

Example 5.16. Quotations

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.

### 5.6.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`.

Example 5.17. Keys, Mouse Buttons, and Combinations

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+right mouse button is used to move windows.

### 5.6.4. Applications, Commands, Options, and Cites

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:

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

Therefore, the introduction to FreeBSD documentation will usually include 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 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.

Example 5.18. Applications, Commands, and Options

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`.

### Note:

Notice how the `&man.`command`.`section`;` notation is easier to follow.

### 5.6.5. Files, Directories, Extensions

To refer to the name of a file, a directory, or a file extension, use `filename`.

Example 5.19. `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.

### 5.6.6. The Name of Ports

### FreeBSD 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`.

Example 5.20. `filename` Tag with `package` Role

Usage:

<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.

### 5.6.7. Devices

### FreeBSD Extension:

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.

Example 5.21. `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`.

### 5.6.8. Hosts, Domains, IP Addresses, and So Forth

### FreeBSD Extension:

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.

No `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.

Example 5.22. `hostid` and Roles

Usage:

<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`.

### 5.6.9. Usernames

### FreeBSD Extension:

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`.

Example 5.23. `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`.

### 5.6.10. Describing `Makefile`s

### FreeBSD Extension:

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.

Example 5.24. `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`.

### 5.6.11. Literal Text

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`.

Example 5.25. `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.

### 5.6.12. Showing Items That the User Must Fill In

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.

Example 5.26. `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 `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`.

### 5.6.13. Quoting System Errors

System errors generated by FreeBSD are marked with `errorname`. This indicates the exact error that appears.

Example 5.27. `errorname`

Usage:

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

Appearance:

Panic: cannot mount root

Prev | Up | Next
5.5. Block Elements | Home | 5.7. Images

This, and other documents, can be downloaded from http://ftp.FreeBSD.org/pub/FreeBSD/doc/

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.