DocBook Markup

DocBook Markup Introduction This chapter is an introduction to DocBook as it is used for &os; documentation. DocBook is a large and complex markup system, but the subset described here covers the parts that are most widely used for &os; documentation. While a moderate subset is covered, it is impossible to anticipate every situation. Please post questions that this document does not answer to the &a.doc;. DocBook was originally developed by HaL Computer Systems and O'Reilly & Associates to be a Document Type Definition (DTD) for writing technical documentation A short history can be found under http://www.oasis-open.org/docbook/intro.shtml#d0e41.. Since 1998 it is maintained by the DocBook Technical Committee. As such, and unlike LinuxDoc and XHTML, DocBook is very heavily oriented towards markup that describes what something is, rather than describing how it should be presented. The DocBook DTD is available from the Ports Collection in the textproc/docbook-xml port. It is automatically installed as part of the textproc/docproj port. Formal Versus 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. Inline Versus Block In the remainder of this document, when describing elements, inline means that the element can occur within a block element, and does not cause a line break. A block element, by comparison, will cause a line break (and other processing) when it is encountered. &os; Extensions The &os; Documentation Project has extended the DocBook DTD with additional elements and entities. These additions serve to make some of the markup easier or more precise. Throughout the rest of this document, the term DocBook is used to mean the &os;-extended DocBook DTD. Most of these extensions are not unique to &os;, 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 contact &a.doceng;. &os; Elements The additional &os; elements are not (currently) in the Ports Collection. They are stored in the &os; Subversion tree, as head/share/xml/freebsd.dtd. &os;-specific elements used in the examples below are clearly marked. &os; Entities This table shows some of the most useful entities available in the FDP. For a complete list, see the *.ent files in doc/share/xml. &os; Name Entities &os; &os; &os.stable; &os.stable; &os.current; &os.current; Manual Page Entities &man.ls.1; &man.ls.1; Usage: &man.ls.1; is the manual page for <command>ls</command>. &man.cp.1; &man.cp.1; Usage: The manual page for <command>cp</command> is &man.cp.1;. &man.command.sectionnumber; link to command manual page in section sectionnumber Entities are defined for all the &os; manual pages. &os; Mailing List Entities &a.doc; &a.doc; Usage: A link to the &a.doc;. &a.questions; &a.questions; Usage: A link to the &a.questions;. &a.listname; link to listname Entities are defined for all the &os; mailing lists. &os; Document Link Entities &url.books.handbook; &url.books.handbook; Usage: A link to the <link xlink:href="&url.books.handbook;/advanced-networking.html">Advanced Networking</link> chapter of the Handbook. &url.books.bookname; relative path to bookname Entities are defined for all the &os; books. &url.articles.committers-guide; &url.articles.committers-guide; Usage: A link to the <link xlink:href="&url.articles.committers-guide;">Committer's Guide</link> article. &url.articles.articlename; relative path to articlename Entities are defined for all the &os; articles. Other Operating System Name Entities &linux; &linux; The &linux; operating system. &unix; &unix; The &unix; operating system. &windows; &windows; The &windows; operating system. Miscellaneous Entities &prompt.root; &prompt.root; The root user prompt. &prompt.user; &prompt.user; A prompt for an unprivileged user. &postscript; &postscript; The &postscript; programming language. &tex; &tex; The &tex; typesetting language. &xorg; &xorg; The &xorg; open source X Window System. Formal Public Identifier (FPI) In compliance with the DocBook guidelines for writing FPIs for DocBook customizations, the FPI for the &os; extended DocBook DTD is: PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN" Document Structure DocBook allows structuring documentation in several ways. The &os; Documentation Project uses two primary types of DocBook document: the book and the article. Books are organized into chapters. This is a mandatory requirement. There may be parts between the book and the chapter to provide another layer of organization. For example, 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. The nature of the document being written should be used to determine 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 &os; tutorials are all marked up as articles, while this document, the FAQ, and the Handbook are all marked up as books, for example. Starting a Book The content of a 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 is contained within info. Boilerplate <tag>book</tag> with <tag>info</tag> book info titleYour Title Heretitle author personname firstnameYour first namefirstname surnameYour surnamesurname personname affiliation address emailYour email addressemail address affiliation author copyright year1998year holder role="mailto:your email address"Your nameholder copyright releaseinfo$&os;$releaseinfo abstract paraInclude an abstract of the book's contents here.para abstract info … book 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 is contained within info. Boilerplate <tag>article</tag> with <tag>info</tag> article info titleYour title heretitle author personname firstnameYour first namefirstname surnameYour surnamesurname personname affiliation address emailYour email addressemailaddress address affiliation author copyright year1998year holder role="mailto:your email address"Your nameholder copyright releaseinfo$&os;$releaseinfo abstract paraInclude an abstract of the article's contents here.para abstract info … article 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. A Simple Chapter chapter titleThe Chapter's Titletitle ... 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. Empty Chapters chapter titleThis is An Empty Chaptertitle parapara chapter 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. Sections in Chapters chapter titleA Sample Chaptertitle paraSome text in the chapter.para sect1 titleFirst Sectiontitle … sect1 sect1 titleSecond Sectiontitle sect2 titleFirst Sub-Sectiontitle sect3 titleFirst Sub-Sub-Sectiontitle … sect3 sect2 sect2 titleSecond Sub-Section (1.2.2)title … sect2 sect1 chapter Section numbers are automatically generated and prepended to titles when the document is rendered to an output format. The generated section numbers and titles from the example above will be: 1.1. First Section 1.2. Second Section 1.2.1. First Sub-Section 1.2.1.1. First Sub-Sub-Section 1.2.2. Second Sub-Section Subdividing Using <tag>part</tag> Elements parts introduce another level of organization between book and chapter with one or more parts. This cannot be done in an article. part titleIntroductiontitle chapter titleOverviewtitle ... chapter chapter titleWhat is FreeBSD?title ... chapter chapter titleHistorytitle ... chapter part Block Elements Paragraphs DocBook supports three types of paragraphs: formalpara, para, and simpara. Almost all paragraphs in &os; documentation use para. formalpara includes a title element, and simpara disallows some elements from within para. Stick with para. <tag>para</tag> Example Usage: paraThis 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. Block Quotations A block quotation is an extended quotation from another document that should not appear within the current paragraph. These are rarely needed. Blockquotes can optionally contain a title and an attribution (or they can be left untitled and unattributed). <tag>blockquote</tag> Example Usage: paraA small excerpt from the US Constitution:para blockquote titlePreamble to the Constitution of the United Statestitle attributionCopied from a web site somewhereattribution paraWe 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: A small excerpt from the US Constitution:

Preamble to the Constitution of the United States Copied from a web site somewhere 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.

Tips, Notes, Warnings, Cautions, and Important Information Extra information may need to be separated from the main body of the text. Typically this is meta information of which the user should be aware. Several types of admonitions are available: tip, note, warning, caution, and important. Which admonition to choose depends on the situation. The DocBook documentation suggests: Note is for information that should be heeded by all readers. Important is a variation on Note. Caution is for information regarding possible data loss or software damage. Warning is for information regarding possible hardware damage or injury to life or limb. <tag>tip</tag> and <tag>important</tag> Example Usage: tip para&os; may reduce stress.para tip important paraPlease use admonitions sparingly. Too many admonitions are visually jarring and can have the opposite of the intended effect.para important Appearance: &os; may reduce stress. Please use admonitions sparingly. Too many admonitions are visually jarring and can have the opposite of the intended effect. Examples Examples can be shown with example. <tag>example</tag> Source Usage: example paraEmpty files can be created easily:para screen&prompt.user; userinputtouch file1 file2 file3userinputscreen example Appearance: Rendered <tag>example</tag> Empty files can be created easily: &prompt.user; touch file1 file2 file3 Lists and Procedures Information often needs to be presented as lists, or as a number of steps that must be carried out in order to accomplish a particular goal. To do this, use itemizedlist, orderedlist, variablelist, or procedure. There are other types of list elements in DocBook, but we will not cover them here. 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. <tag>itemizedlist</tag> and <tag>orderedlist</tag> Example Usage: itemizedlist listitem paraThis is the first itemized item.para listitem listitem paraThis is the second itemized item.para listitem itemizedlist orderedlist listitem paraThis is the first ordered item.para listitem listitem paraThis is the second ordered item.para listitem orderedlist 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. An alternate and often useful way of presenting information is the variablelist. These are lists where each entry has a term and a description. They are well suited for many types of descriptions, and present information in a form that is often easier for the reader than sections and subsections. A variablelist has a title, and then pairs of term and listitem entries. <tag>variablelist</tag> Example Usage: variablelist varlistentry termParallelterm listitem paraIn parallel communications, groups of bits arrive at the same time over multiple communications channels.para listitem varlistentry varlistentry termSerialterm listitem paraIn serial communications, bits arrive one at a time over a single communications channel.para listitem varlistentry variablelist Appearance: Parallel In parallel communications, groups of bits arrive at the same time over multiple communications channels. Serial In serial communications, bits arrive one at a time over a single communications channel. A procedure shows a series of steps, which may in turn consist of more steps or substeps. Each step contains block elements and may include an optional title. Sometimes, steps are not sequential, but present a choice: do this or do that, but not both. For these alternative choices, use stepalternatives. <tag>procedure</tag> Example Usage: procedure step paraDo this.para step step paraThen do this.para step step substeps step paraAnd now do this smaller thing.para step step paraAnd now do this other smaller thing.para step substeps step step paraFinally, do one of these:para stepalternatives step paraGo left.para step step paraGo right.para step stepalternatives step procedure Appearance: Do this. Then do this. And now do this small thing. And this other small thing. Finally, do one of these: Go left. Go right. Showing File Samples Fragments of a file (or perhaps a complete file) are shown by wrapping them 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. <tag>programlisting</tag> Example Usage: paraWhen finished, the program will look like this:para programlisting#include <stdio.h> int main(void) { printf("hello, world\n"); return 0; }programlisting Notice how the angle brackets in the #include line need to be referenced by their entities instead of being included literally. Appearance: When finished, the program will look like this: #include <stdio.h> int main(void) { printf("hello, world\n"); return 0; } Callouts A callout is a visual marker for referring to a piece of text or specific position within an example. Callouts are marked with the co element. Each element must have a unique id assigned to it. After the example, include a calloutlist that describes each callout. <tag>co</tag> and <tag>calloutlist</tag> Example paraWhen finished, the program will look like this:para programlisting#include <stdio.h> co xml:id="co-ex-include" int co xml:id="co-ex-return" main(void) { printf("hello, world\n"); co xml:id="co-ex-printf" }programlisting calloutlist callout arearefs="co-ex-include" paraIncludes the standard IO header file.para callout callout arearefs="co-ex-return" paraSpecifies that functionmain()function returns an int.para callout callout arearefs="co-ex-printf" paraThe functionprintf()function call that writes literalhello, worldliteral to standard output.para callout calloutlist Appearance: When finished, the program will look like this: #include <stdio.h> int main(void) { printf("hello, world\n"); } Includes the standard IO header file. Specifies that main() returns an int. The printf() call that writes hello, world to standard output. Tables Unlike HTML, DocBook does not need tables for layout purposes, as the stylesheet handles those issues. 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 there is 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. <tag>informaltable</tag> Example Usage: informaltable pgwide="1" tgroup cols="2" thead row entryThis is Column Head 1entry entryThis is Column Head 2entry row thead tbody row entryRow 1, column 1entry entryRow 1, column 2entry row row entryRow 2, column 1entry entryRow 2, column 2entry 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. Table borders can be suppressed by setting the frame attribute to none in the informaltable element. For example, informaltable frame="none". Table with <literal>frame="none"</literal> Example 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 Examples for the User to Follow Examples for the user to follow are often necessary. Typically, these will consist of dialogs with the computer; the user types in a command, the user gets a response back, the user types 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. 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 &os; 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 be displayed differently than system output text. <tag>screen</tag>, <tag>prompt</tag>, and <tag>userinput</tag> Example Usage: screen&prompt.user; userinputls -1userinput foo1 foo2 foo3 &prompt.user; userinputls -1 | grep foo2userinput foo2 &prompt.user; userinputsuuserinput promptPassword: prompt &prompt.root; userinputcat foo2userinput This is the file called 'foo2'screen Appearance: &prompt.user; ls -1 foo1 foo2 foo3 &prompt.user; ls -1 | grep foo2 foo2 &prompt.user; su Password: &prompt.root; 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. In-line Elements 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. <tag>emphasis</tag> Example Usage: para&os; is without doubt emphasistheemphasis premiere &unix;-like operating system for the Intel architecture.para Appearance: &os; is without doubt the premiere &unix;-like operating system for the Intel architecture. Acronyms Many computer terms are acronyms, words formed from the first letter of each word in a phrase. Acronyms are marked up into acronym elements. It is helpful to the reader when an acronym is defined on the first use, as shown in the example below. <tag>acronym</tag> Example Usage: paraRequest For Comments (acronymRFCacronym) 1149 defined the use of avian carriers for transmission of Internet Protocol (acronymIPacronym) data. The quantity of acronymIPacronym data currently transmitted in that manner is unknown.para Appearance: Request For Comments (RFC) 1149 defined the use of avian carriers for transmission of Internet Protocol (IP) data. The quantity of IP data currently transmitted in that manner is unknown. 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. <tag>quote</tag> Example Usage: paraHowever, make sure that the search does not go beyond the quoteboundary between local and public administrationquote, as acronymRFCacronym 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. 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. Keys, Mouse Buttons, and Combinations Example Usage: paraTo switch to the second virtual terminal, press keycombo action="simul"keycapAltkeycap keycapF1keycapkeycombo.para paraTo exit commandvicommand without saving changes, type keycombo action="seq"keycapEsckeycapkeycap:keycap keycapqkeycapkeycap!keycapkeycombo.para paraMy window manager is configured so that keycombo action="simul"keycapAltkeycap mousebuttonrightmousebutton 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. 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 &os; 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 to include a command name in-line but present it as something the user should type. 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. Applications, Commands, and Options Example Usage: paraapplicationSendmailapplication is the most widely used Unix mail application.para paraapplicationSendmailapplication includes the citerefentry refentrytitlesendmailrefentrytitle manvolnum8manvolnum citerefentry, &man.mailq.1;, and &man.newaliases.1; programs.para paraOne of the command line parameters to citerefentry refentrytitlesendmailrefentrytitle manvolnum8manvolnum citerefentry, option-bpoption, will display the current status of messages in the mail queue. Check this on the command line by running commandsendmail -bpcommand.para Appearance: Sendmail is the most widely used Unix mail application. Sendmail includes the sendmail 8 , &man.mailq.1;, and &man.newaliases.1; programs. One of the command line parameters to sendmail 8 , , 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. Files, Directories, Extensions, Device Names To refer to the name of a file, a directory, a file extension, or a device name, use filename. <tag>filename</tag> Example Usage: paraThe source for the Handbook in English is found in filename/usr/doc/en_US.ISO8859-1/books/handbook/filename. The main file is called filenamebook.xmlfilename. There is also a filenameMakefilefilename and a number of files with a filename.entfilename extension.para parafilenamekbd0filename is the first keyboard detected by the system, and appears in filename/devfilename.para Appearance: The source for the Handbook in English is found in /usr/doc/en_US.ISO8859-1/books/handbook/. The main file is called book.xml. There is also a Makefile and a number of files with a .ent extension. kbd0 is the first keyboard detected by the system, and appears in /dev. The Name of Ports &os; Extension These elements are part of the &os; extension to DocBook, and do not exist in the original DocBook DTD. To include the name of a program from the &os; Ports Collection in the document, use the package tag. Since the Ports Collection can be installed in any number of locations, only include the category and the port name; do not include /usr/ports. By default, package refers to a binary package. To refer to a port that will be built from source, set the role attribute to port. <tag>package</tag> Example Usage: paraInstall the packagenet/wiresharkpackage binary package to view network traffic.para parapackage role="port"net/wiresharkpackage can also be built and installed from the Ports Collection.para Appearance: Install the net/wireshark binary package to view network traffic. net/wireshark can also be built and installed from the Ports Collection. Hosts, Domains, IP Addresses, User Names, Group Names, and Other System Items &os; Extension These elements are part of the &os; extension to DocBook, and do not exist in the original DocBook DTD. Information for system items is marked up with systemitem. The class attribute is used to identify the particular type of information shown. class="domainname" The text is a domain name, such as FreeBSD.org or ngo.org.uk. There is no hostname component. class="etheraddress" The text is an Ethernet MAC address, expressed as a series of 2 digit hexadecimal numbers separated by colons. class="fqdomainname" The text is a Fully Qualified Domain Name, with both hostname and domain name parts. class="ipaddress" The text is an IP address, probably expressed as a dotted quad. class="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). class="systemname" With class="systemname" the marked up information is the simple hostname, such as freefall or wcarchive. class="username" The text is a username, like root. class="groupname" The text is a groupname, like wheel. <tag>systemitem</tag> and Classes Example Usage: paraThe local machine can always be referred to by the name systemitem class="systemname"localhostsystemitem, which will have the IP address systemitem class="ipaddress"127.0.0.1systemitem.para paraThe systemitem class="domainname"FreeBSD.orgsystemitem domain contains a number of different hosts, including systemitem class="fqdomainname"freefall.FreeBSD.orgsystemitem and systemitem class="fqdomainname"bento.FreeBSD.orgsystemitem.para paraWhen adding an acronymIPacronym alias to an interface (using commandifconfigcommand) emphasisalwaysemphasis use a netmask of systemitem class="netmask"255.255.255.255systemitem (which can also be expressed as systemitem class="netmask"0xffffffffsystemitem).para paraThe acronymMACacronym address uniquely identifies every network card in existence. A typical acronymMACacronym address looks like systemitem class="etheraddress"08:00:20:87:ef:d0systemitem.para paraTo carry out most system administration functions requires logging in as systemitem class="username"rootsystemitem.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. To carry out most system administration functions requires logging in as root. Uniform Resource Identifiers (<acronym>URI</acronym>s) Occasionally it is useful to show a Uniform Resource Identifier (URI) without making it an active hyperlink. The uri element makes this possible: <tag>uri</tag> Example Usage: paraThis URL shows only as text: urihttps://www.FreeBSD.orguri. It does not create a link.para Appearance: This URL shows only as text: https://www.FreeBSD.org. It does not create a link. To create links, see . Email Addresses 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. <tag>email</tag> with a Hyperlink Example Usage: paraAn email address that does not actually exist, like emailnotreal@example.comemail, 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 &os;-specific extension allows setting the role attribute to nolink to prevent the creation of the hyperlink to the email address. <tag>email</tag> Without a Hyperlink Example Usage: paraSometimes a link to an email address like email role="nolink"notreal@example.comemail is not desired.para Appearance: Sometimes a link to an email address like notreal@example.com is not desired. Describing <filename>Makefile</filename>s &os; Extension These elements are part of the &os; extension to DocBook, and do not exist in the original DocBook DTD. Two elements exist to describe parts of Makefiles, buildtarget and varname. buildtarget identifies a build target exported by a Makefile that can be given as a parameter to make. varname identifies a variable that can be set (in the environment, on the command line with make, or within the Makefile) to influence the process. <tag>buildtarget</tag> and <tag>varname</tag> Example Usage: paraTwo common targets in a filenameMakefilefilename are buildtargetallbuildtarget and buildtargetcleanbuildtarget.para paraTypically, invoking buildtargetallbuildtarget will rebuild the application, and invoking buildtargetcleanbuildtarget will remove the temporary files (filename.ofilename for example) created by the build process.para parabuildtargetcleanbuildtarget may be controlled by a number of variables, including varnameCLOBBERvarname and varnameRECURSEvarname.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 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. <tag>literal</tag> Example Usage: paraThe literalmaxusers 10literal 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. Showing Items That the User <emphasis>Must</emphasis> 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. <tag>replaceable</tag> Example Usage: screen&prompt.user; userinputman replaceablecommandreplaceableuserinputscreen Appearance: &prompt.user; 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: paraThe literalmaxusers replaceablenreplaceableliteral 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 paraFor a desktop workstation, literal32literal is a good value for replaceablenreplaceable.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. Showing <acronym>GUI</acronym> Buttons 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. <tag>guibutton</tag> Example Usage: paraEdit the file, then click guibutton[ Save ]guibutton to save the changes.para Appearance: Edit the file, then click [ Save ] to save the changes. Quoting System Errors System errors generated by &os; are marked with errorname. This indicates the exact error that appears. <tag>errorname</tag> Example Usage: screenerrornamePanic: cannot mount rooterrornamescreen Appearance: Panic: cannot mount root Images Image support in the documentation is somewhat experimental. The mechanisms described here are unlikely to change, but that is not guaranteed. To provide conversion between different image formats, the graphics/ImageMagick port must be installed. This port is not included in the textproc/docproj meta port, and must be installed separately. A good example of the use of images is the doc/en_US.ISO8859-1/articles/vm-design/ document. Examine the files in that directory to see how these elements are used together. Build different output formats to see how the format determines what images are shown in the rendered document. Image Formats The following image formats are currently supported. An image file will automatically be converted to bitmap or vector image depending on the output document format. These are the only formats in which images should be committed to the documentation repository. EPS (Encapsulated Postscript) Images that are primarily vector based, such as network diagrams, time lines, and similar, should be in this format. These images have a .eps extension. PNG (Portable Network Graphic) For bitmaps, such as screen captures, use this format. These images have the .png extension. PIC (PIC graphics language) PIC is a language for drawing simple vector-based figures used in the &man.pic.1; utility. These images have the .pic extension. SCR (SCReen capture) This format is specific to screenshots of console output. The following command generates an SCR file shot.scr from video buffer of /dev/ttyv0: &prompt.root; vidcontrol -p < /dev/ttyv0 > shot.scr This is preferable to PNG format for screenshots because the SCR file contains plain text of the command lines so that it can be converted to a PNG image or a plain text depending on the output document format. Use the appropriate format for each image. Documentation will often have a mix of EPS and PNG images. The Makefiles ensure that the correct format image is chosen depending on the output format used. Do not commit the same image to the repository in two different formats. The Documentation Project may eventually switch to using the SVG (Scalable Vector Graphic) format for vector images. However, the current state of SVG capable editing tools makes this impractical. Image File Locations Image files can be stored in one of several locations, depending on the document and image: In the same directory as the document itself, usually done for articles and small books that keep all their files in a single directory. In a subdirectory of the main document. Typically done when a large book uses separate subdirectories to organize individual chapters. When images are stored in a subdirectory of the main document directory, the subdirectory name must be included in their paths in the Makefile and the imagedata element. In a subdirectory of doc/share/images named after the document. For example, images for the Handbook are stored in doc/share/images/books/handbook. Images that work for multiple translations are stored in this upper level of the documentation file tree. Generally, these are images that can be used unchanged in non-English translations of the document. Image Markup Images are included as part of a mediaobject. The mediaobject can contain other, more specific objects. We are concerned with two, the imageobject and the textobject. Include one imageobject, and two textobject elements. The imageobject will point to the name of the image file without the extension. The textobject elements contain information that will be presented to the user as well as, or instead of, the image itself. Text elements are shown to the reader in several situations. When the document is viewed in HTML, text elements are shown while the image is loading, or if the mouse pointer is hovered over the image, or if a text-only browser is being used. In formats like plain text where graphics are not possible, the text elements are shown instead of the graphical ones. This example shows how to include an image called fig1.png in a document. The image is a rectangle with an A inside it: mediaobject imageobject imagedata fileref="fig1" imageobject textobject literallayout class="monospaced"+---------------+ | A | +---------------+literallayout textobject textobject phraseA picturephrase textobject mediaobject Include an imagedata element inside the imageobject element. The fileref attribute should contain the filename of the image to include, without the extension. The stylesheets will work out which extension should be added to the filename automatically. The first textobject contains a literallayout element, where the class attribute is set to monospaced. This is an opportunity to demonstrate ASCII art skills. This content will be used if the document is converted to plain text. Notice how the first and last lines of the content of the literallayout element butt up next to the element's tags. This ensures no extraneous white space is included. The second textobject contains a single phrase element. The contents of this phrase will become the alt attribute for the image when this document is converted to HTML. Image <filename>Makefile</filename> Entries Images must be listed in the Makefile in the IMAGES variable. This variable must contain the names of all the source images. For example, if there are three figures, fig1.eps, fig2.png, fig3.png, then the 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 the source document, you only need to list the image files you provided. Images and Chapters in Subdirectories Be careful when separating documentation into smaller files in different directories (see ). Suppose there is 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, place those images in each chapter's subdirectory (chapter1/, chapter2/, and chapter3/). However, doing this requires including the directory names in the IMAGES variable in the Makefile, and including the directory name in the imagedata element in the document. For example, if the book has chapter1/fig1.png, then chapter1/chapter.xml should contain: mediaobject imageobject imagedata fileref="chapter1/fig1" imageobject … mediaobject The directory name must be included in the fileref attribute. The Makefile must contain: … IMAGES= chapter1/fig1.png … Links Links are also in-line elements. To show a URI without creating a link, see . <literal>xml:id</literal> Attributes Most DocBook elements accept an xml:id attribute to give that part of the document a unique name. The xml:id can be used as a target for a crossreference or link. Any portion of the document that will be a link target must have an xml:id attribute. Assigning an xml:id to all chapters and sections, even if there are no current plans to link to them, is a good idea. These xml:ids can be used as unique reference points by anyone referring to the HTML version of the document. <literal>xml:id</literal> on Chapters and Sections Example chapter xml:id="introduction" titleIntroductiontitle paraThis is the introduction. It contains a subsection, which is identified as well.para sect1 xml:id="introduction-moredetails" titleMore Detailstitle paraThis is a subsection.para sect1 chapter Use descriptive values for xml:id names. The values must be unique within the entire document, not just in a single file. In the example, the subsection xml:id is constructed by appending text to the chapter xml:id. This ensures that the xml:ids are unique. It also helps both reader and anyone editing the document to see where the link is located within the document, similar to a directory path to a file. Crossreferences with <literal>xref</literal> xref provides the reader with a link to jump to another section of the document. The target xml:id is specified in the linkend attribute, and xref generates the link text automatically. <tag>xref</tag> Example Assume that this fragment appears somewhere in a document that includes the xml:id example shown above: paraMore information can be found in xref linkend="introduction".para paraMore specific information can be found in xref linkend="introduction-moredetails".para The link text will be generated automatically, looking like (emphasized text indicates the link text):

More information can be found in Chapter 1, Introduction. More specific information can be found in Section 1.1, More Details.

The link text is generated automatically from the chapter and section number and title elements. Linking to Other Documents on the Web The link element described here allows the writer to define the link text. When link text is used, it is very important to be descriptive to give the reader an idea of where the link goes. Remember that DocBook can be rendered to multiple types of media. The reader might be looking at a printed book or other form of media where there are no links. If the link text is not descriptive enough, the reader might not be able to locate the linked section. The xlink:href attribute is the URL of the page, and the content of the element is the text that will be displayed for the user to activate. In many situations, it is preferable to show the actual URL rather than text. This can be done by leaving out the element text entirely. <tag>link</tag> to a &os; Documentation Web Page Example Link to the book or article URL entity. To link to a specific chapter in a book, add a slash and the chapter file name, followed by an optional anchor within the chapter. For articles, link to the article URL entity, followed by an optional anchor within the article. URL entities can be found in doc/share/xml/urls.ent. Usage for &os; book links: paraRead the link xlink:href="&url.books.handbook;/svn.html#svn-intro"SVN introductionlink, then pick the nearest mirror from the list of link xlink:href="&url.books.handbook;/svn.html#svn-mirrors"Subversion mirror siteslink.para Appearance: Read the SVN introduction, then pick the nearest mirror from the list of Subversion mirror sites. Usage for &os; article links: paraRead this link xlink:href="&url.articles.bsdl-gpl;"article about the BSD licenselink, or just the link xlink:href="&url.articles.bsdl-gpl;#intro"introductionlink.para Appearance: Read this article about the BSD license, or just the introduction. <tag>link</tag> to a &os; Web Page Example Usage: paraOf course, you could stop reading this document and go to the link xlink:href="&url.base;/index.html"FreeBSD home pagelink instead.para Appearance: Of course, you could stop reading this document and go to the FreeBSD home page instead. <tag>link</tag> to an External Web Page Example Usage: paraWikipedia has an excellent reference on link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"GUID Partition Tableslink.para Appearance: Wikipedia has an excellent reference on GUID Partition Tables. The link text can be omitted to show the actual URL: paraWikipedia has an excellent reference on GUID Partition Tables: link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"link.para The same link can be entered using shorter notation instead of a separate ending tag: paraWikipedia has an excellent reference on GUID Partition Tables: link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table".para The two methods are equivalent. Appearance: Wikipedia has an excellent reference on GUID Partition Tables: http://en.wikipedia.org/wiki/GUID_Partition_Table.