diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
index 8655ac3112..f6c1949ec3 100644
--- a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
@@ -1,2684 +1,2680 @@
SGML MarkupThis chapter describes the two markup languages you will encounter
when you contribute to the FreeBSD documentation project. Each section
describes the markup language, and details the markup that you are likely
to want to use, or that is already in use.These markup languages contain a large number of elements, and it can
be confusing sometimes to know which element to use for a particular
situation. This section goes through the elements you are most likely to
need, and gives examples of how you would use them.This is not an exhaustive list of elements, since
that would just reiterate the documentation for each language. The aim of
this section is to list those elements more likely to be useful to you.
If you have a question about how best to markup a particular piece of
content, please post it to the &a.doc;.Inline vs. blockIn 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.HTMLHTML, the HyperText Markup Language, is the markup language of
choice on the World Wide Web. More information can be found at
<URL:http://www.w3.org/>.HTML is used to markup pages on the FreeBSD web site. It should not
(generally) be used to mark up other documentation,
since DocBook offers a
far richer set of elements to choose from. Consequently, you will
normally only encounter HTML pages if you are writing for the web
site.HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the
latest, 4.0 (available in both strict and
loose variants).The HTML DTDs are available from the ports collection in the
textproc/html port. They are automatically
installed as part of the textproc/docproj
port.Formal Public Identifier (FPI)There are a number of HTML FPIs, depending upon the version (also
known as the level) of HTML that you want to declare your document to
be compliant with.The majority of HTML documents on the FreeBSD web site comply with
the loose version of HTML 4.0.PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"Sectional elementsAn HTML document is normally split into two sections. The first
section, called the head, contains
meta-information about the document, such as its title, the name of
the author, the parent document, and so on. The second section, the
body, contains the content that will be displayed
to the user.These sections are indicated with head and
body elements respectively. These elements are
contained within the top-level html element.Normal HTML document structure<html>
<head>
<title>The document's title</title>
</head>
<body>
…
</body>
</html>Block elementsHeadingsHTML allows you to denote headings in your document, at up to
six different levels.The largest and most prominent heading is h1,
then h2, continuing down to
h6.The element's content is the text of the heading.h1, h2, etc.Use:First section
This is the heading for the first section
This is the heading for the first sub-section
This is the heading for the second section
]]>Generally, an HTML page should have one first level heading
(h1). This can contain many second level
headings (h2), which can in turn contain many
third level headings. Each
hn element should have
the same element, but one further up the hierarchy, preceding it.
Leaving gaps in the numbering is to be avoided.Bad ordering of
hn elementsUse:First section
Sub-section
]]>ParagraphsHTML supports a single paragraph element,
p.pUse:This is a paragraph. It can contain just about any
other element.
]]>
Block quotationsA block quotation is an extended quotation from another document
that should not appear within the current paragraph.blockquoteUse:A small excerpt from the US Constitution:
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.
]]>ListsYou can present the user with three types of lists, ordered,
unordered, and definition.Typically, each entry in an ordered list will be numbered, while
each entry in an unordered list will be preceded by a bullet point.
Definition lists are composed of two sections for each entry. The
first section is the term being defined, and the second section is
the definition of the term.Ordered lists are indicated by the ol
element, unordered lists by the ul element, and
definition lists by the dl element.Ordered and unordered lists contain listitems, indicated by the
li element. A listitem can contain textual
content, or it may be further wrapped in one or more
p elements.Definition lists contain definition terms
(dt) and definition descriptions
(dd). A definition term can only contain inline
elements. A definition description can contain other block
elements.ul and olUse:An unordered list. Listitems will probably be
preceded by bullets.
First item
Second item
Third item
An ordered list, with list items consisting of multiple
paragraphs. Each item (note: not each paragraph) will be
numbered.
This is the first item. It only has one paragraph.
This is the first paragraph of the second item.
This is the second paragraph of the second item.
This is the first and only paragraph of the third
item.
]]>Definition lists with dlUse:
Term 1
Paragraph 1 of definition 1.
Paragraph 2 of definition 1.
Term 2
Paragraph 1 of definition 2.
Term 3
Paragraph 1 of definition 3. Note that the <p>
element is not required in the single paragraph case.
]]>Pre-formatted textYou can indicate that text should be shown to the user exactly
as it is in the file. Typically, this means that the text is shown
in a fixed font, multiple spaces are not merged into one, and line
breaks in the text are significant.In order to do this, wrap the content in the
pre element.preYou could use pre to mark up an e-mail
message; From: nik@FreeBSD.org
To: freebsd-doc@FreeBSD.org
Subject: New documentation available
There is a new copy of my primer for contributors to the FreeBSD
Documentation Project available at
Comments appreciated.
N]]>TablesMost text-mode browsers (such as Lynx) do not render tables
particularly effectively. If you are relying on the tabular
display of your content, you should consider using alternative
markup to prevent confusion.Mark up tabular information using the table
element. A table consists of one or more table rows
(tr), each containing one or more cells of table
data (td). Each cell can contain other block
elements, such as paragraphs or lists. It can also contain another
table (this nesting can repeat indefinitely). If the cell only
contains one paragraph then you do not need to include the
p element.Simple use of tableUse:This is a simple 2x2 table.
Top left cell
Top right cell
Bottom left cell
Bottom right cell
]]>A cell can span multiple rows and columns. To indicate this,
add the rowspan and/or colspan
attributes, with values indicating the number of rows of columns
that should be spanned.Using rowspanUse:One tall thin cell on the left, two short cells next to
it on the right.
Long and thin
Top cell
Bottom cell
]]>Using colspanUse:One long cell on top, two short cells below it.
Top cell
Bottom left cell
Bottom right cell
]]>Using rowspan and
colspan togetherUse:On a 3x3 grid, the top left block is a 2x2 set of
cells merged into one. The other cells are normal.
Top left large cell
Top right cell
Middle right cell
Bottom left cell
Bottom middle cell
Bottom right cell
]]>In-line elementsEmphasising informationYou have two levels of emphasis available in HTML,
em and strong.
em is for a normal level of emphasis and
strong indicates stronger emphasis.Typically, em is rendered in italic and
strong is rendered in bold. This is not always
the case, however, and you should not rely on it.em and strongUse:This has been emphasised, while
this has been strongly emphasised.]]>Bold and italicsBecause HTML includes presentational markup, you can also
indicate that particular content should be rendered in bold or
italic. The elements are b and
i respectively.b and iThis is in bold, while this is
in italics.]]>Indicating fixed pitch textIf you have content that should be rendered in a fixed pitch
(typewriter) typeface, use tt (for
teletype).ttUse:This document was originally written by
Nik Clayton, who can be reached by e-mail as
nik@FreeBSD.org.]]>Content sizeYou can indicate that content should be shown in a larger or
smaller font. There are three ways of doing this.Use big and small
around the content you wish to change size. These tags can be
nested, so <big><big>This is much
bigger</big></big> is possible.Use font with the size
attribute set to +1 or -1
respectively. This has the same effect as using
big or small. However,
the use of this approach is deprecated.Use font with the size
attribute set to a number between 1 and 7. The default font size
is 3. This approach is deprecated.big, small, and
fontThe following fragments all do the same thing.This text is slightly smaller. But
this text is slightly bigger.
This text is slightly smaller. But
this text is slightly bigger
This text is slightly smaller. But
this text is slightly bigger.
]]>
LinksLinks are also in-line elements.Linking to other documents on the WWWIn order to include a link to another document on the WWW you
must know the URL of the document you want to link to.The link is indicated with a, and the
href attribute contains the URL of the target
document. The content of the element becomes the link, and is
normally indicated to the user in some way (underlining, change of
color, different mouse cursor when over the link, and so
on).Using <a href="...">Use:More information is available at the
FreeBSD web site.]]>These links will take the user to the top of the chosen
document.Linking to other parts of documentsLinking to a point within another document (or within the same
document) requires that the document author include anchors that you
can link to.Anchors are indicated with a and the
name attribute instead of
href.Using <a name="...">Use:This paragraph can be referenced
in other links with the name para1.]]>To link to a named part of a document, write a normal link to
that document, but include the name of the anchor after a
# symbol.Linking to a named part of another documentAssume that the para1 example resides in a
document called foo.html.More information can be found in the
first paragraph of
foo.html.]]>If you are linking to a named anchor within the same document
then you can omit the document's URL, and just include the name of
the anchor (with the preceding #).Linking to a named part of the same documentAssume that the para1 example resides in
this documentMore information can be found in the
first paragraph of this
document.]]>DocBookDocBook was designed by the Davenport Group to be
a DTD for writing technical documentation. 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. informalSome elements may exist in two forms, formal
and informal. Typically, the formal version of
the element will consist of a title followed by the information
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.FreeBSD extensionsThe 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 &a.nik;.The FreeBSD extensions are not (currently) in the ports
collection. They are stored in the FreeBSD CVS tree, as doc/share/sgml/freebsd.dtd.Formal Public Identifier (FPI)In compliance with the DocBook guidelines for writing FPIs for
DocBook customisations, the FPI for the FreeBSD extended DocBook DTD
is;PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"Document structureDocBook 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 organised into chapters. This is a
mandatory requirement. There may be parts between
the book and the chapter to provide another layer of organisation.
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 organised 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.Starting a bookThe 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.Boilerplate book with
bookinfo<book>
<bookinfo>
<title>Your title here</title>
<author>
<firstname>Your first name</firstname>
<surname>Your surname</surname>
<affiliation>
<address><email>Your e-mail address</email></address>
</affiliation>
</author>
<copyright>
<year>1998</year>
<holder role="mailto:your e-mail address">Your name</holder>
</copyright>
- <pubdate role="rcs">$Date$</pubdate>
-
- <releaseinfo>$Id$</releaseinfo>
+ <releaseinfo>$FreeBSD$</releaseinfo>
<abstract>
<para>Include an abstract of the book's contents here.</para>
</abstract>
</bookinfo>
…
</book>Starting an articleThe 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.Boilerplate article with
articleinfo<article>
<articleinfo>
<title>Your title here</title>
<author>
<firstname>Your first name</firstname>
<surname>Your surname</surname>
<affiliation>
<address><email>Your e-mail address</email></address>
</affiliation>
</author>
<copyright>
<year>1998</year>
<holder role="mailto:your e-mail address">Your name</holder>
</copyright>
- <pubdate role="rcs">$Date$</pubdate>
-
- <releaseinfo>$Id$</releaseinfo>
+ <releaseinfo>$FreeBSD$</releaseinfo>
<abstract>
<para>Include an abstract of the article's contents here.</para>
</abstract>
</articleinfo>
…
</article>Indicating chaptersUse chapter to mark up your chapters. Each
chapter has a mandatory title. Articles do not
contain chapters, they are reserved for books.A simple chapterThe chapter's title
...
]]>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 chaptersThis is an empty chapter
]]>Sections below chaptersIn 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 chaptersA sample chapterSome text in the chapter.First section (1.1)
…
Second section (1.2)First sub-section (1.2.1)First sub-sub-section (1.2.1.1)
…
Second sub-section (1.2.2)
…
]]>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.Subdividing using partsYou can introduce another layer of organisation between
book and chapter with one or
more parts. This cannot be done in an
article.IntroductionOverview
...
What is FreeBSD?
...
History
...
]]>Block elementsParagraphsDocBook 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.paraUse:This is a paragraph. It can contain just about any
other element. ]]>Appearance:This is a paragraph. It can contain just about any other
element.Block quotationsA 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).blockquoteUse:A small excerpt from the US Constitution;
Preamble to the Constitution of the United StatesCopied from a web site somewhereWe 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.
]]>Appearance:
Preamble to the Constitution of the United StatesCopied from a web site somewhereWe 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, important information and
sidebars.You may need to include extra information separate from the
main body of the text. Typically this is meta
information that the user should be aware of.Depending on the nature of the information, one of
tip, note,
warning, caution, and
important should be used. Alternatively, if the
information is related to the main text but is not one of the above,
use sidebar.The circumstances in which to choose one of these elements over
another is unclear. The DocBook documentation suggests;A Note is for information that should be heeded by all
readers.An Important element is a variation on Note.A Caution is for information regarding possible data loss
or software damage.A Warning is for information regarding possible hardware
damage or injury to life or limb.warningUse:Installing FreeBSD may make you want to delete Windows from your
hard disk.
]]>Installing FreeBSD may make you want to delete Windows from
your hard disk.Lists and proceduresYou 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
procedureThere are other types of
list element in DocBook, but we are not concerned with those at
the moment.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 steps, which may in turn consists of more
steps or substeps. Each
step contains block elements.itemizedlist,
orderedlist, and
procedureUse: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.]]>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.Showing file samplesIf 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
programlistingare
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.programlistingUse:When you have finished, your program should look like
this;
#include <stdio.h>
int
main(void)
{
printf("hello, world\n");
}]]>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");
}CalloutsA 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
calloutlistWhen you have finished, your program should 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.]]>Appearance:When you have finished, your program should 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.TablesUnlike 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.informaltableUse:This is column head 1This is column head 2Row 1, column 1Row 1, column 2Row 2, column 1Row 2, column 2
]]>Appearance:This is column head 1This is column head 2Row 1, column 1Row 1, column 2Row 2, column 1Row 2, column 2If 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">).Tables where frame="none"Appearance:This is column head 1This is column head 2Row 1, column 1Row 1, column 2Row 2, column 1Row 2, column 2Examples for the user to followA 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.screenEverything 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.userinputWhen 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
userinputUse:&prompt.user; ls -1
foo1
foo2
foo3
&prompt.user; ls -1 | grep foo2
foo2
&prompt.user; suPassword:
&prompt.root; cat foo2
This is the file called 'foo2']]>Appearance:&prompt.user; ls -1
foo1
foo2
foo3
&prompt.user; ls -1 | grep foo2
foo2
&prompt.user; suPassword:
&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 elementsEmphasising informationWhen you want to emphasise 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.emphasisUse:FreeBSD is without doubt the
premiere Unix like operating system for the Intel architecture.]]>Appearance:FreeBSD is without doubt the premiere Unix
like operating system for the Intel architecture.QuotationsTo 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.QuotationsUse:However, make sure that the search does not go beyond the
boundary between local and public administration,
as RFC 1535 calls it.]]>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 combinationsTo 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 combinationsUse:To switch to the second virtual terminal, press
AltF1.
To exit vi without saving your work, type
Esc:q!.My window manager is configured so that
Altright mouse button is used to move windows.]]>Appearance:To switch to the second virtual terminal, press
AltF1.To exit vi without saving your work, type
Esc:q!.My window manager is configured so that
Altright mouse button is used to move windows.Applications, commands, options, and citesYou will frequently want to refer to both applications and
commands when writing for the Handbook. The distinction between
them is simple: an application is the name for a suite (or possibly
just 1) of programs that fulfil a particular task. A command is the
name of a program that the user can run.In addition, you will occasionally need to list one or more of
the options that a command might take.Finally, you will often want to list a command with its manual
section number, in the command(number) format so
common in Unix manuals.Mark up application names with
application.When you want to list a command with its manual section number
(which should be most of the time) the DocBook element is
citerefentry. This will contain a further two
elements, refentrytitle and
manvolnum. The content of
refentrytitle is the name of the command, and the
content of manvolnum is the manual page
section.This can be cumbersome to write, and so a series of general entities
have been created to make this easier. Each entity takes the form
&man.manual-page.manual-section;.The file that contains these entities is in
doc/share/sgml/man-refs.ent, and can be
referred to using this FPI:PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"Therefore, the introduction to your documentation will probably
look like this:<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;
…
]>Use command when you want to include a
command name in-line but present it as something the
user should type in.Use option to mark up a command's
options.This can be confusing, and sometimes the choice is not always
clear. Hopefully this example makes it clearer.Applications, commands, and options.Use:Sendmail is the most
widely used Unix mail application.
Sendmail includes the
sendmail8, &man.mailq.8;, and &man.newaliases.8;
programs.One of the command line parameters to sendmail8, , will display the current
status of messages in the mail queue. Check this on the command
line by running sendmail -bp.]]>Appearance:Sendmail is the most widely used
Unix mail application.Sendmail includes the
sendmail8, mailq8, and newaliases8 programs.One of the command line parameters to sendmail8, , 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, extensionsWhenever you wish to refer to the name of a file, a directory,
or a file extension, use filename.filenameUse:The SGML source for the Handbook in English can be
found in /usr/doc/en/handbook/. The first
file is called handbook.sgml in that
directory. You should also see a Makefile
and a number of files with a .ent
extension.]]>Appearance:The SGML source for the Handbook in English can be found in
/usr/doc/en/handbook/. The first file is
called handbook.sgml in that directory. You
should also see a Makefile and a number of
files with a .ent extension.The name of portsFreeBSD extensionThese 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:Install the net/ethereal port to view network traffic.]]>Appearance:Install the net/ethereal
port to view network traffic.DevicesFreeBSD extensionThese 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.devicenameUse: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.]]>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.Hosts, domains, IP addresses, and so forthFreeBSD extensionThese 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.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.
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: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.]]>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.UsernamesFreeBSD extensionThese 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.usernameUse:To carry out most system administration functions you
will need to be root.]]>Appearance:To carry out most system administration functions you will
need to be root.Describing MakefilesFreeBSD extensionThese 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
Makefiles, maketarget and
makevar.maketarget identifies a build target exported
by a Makefile that can be given as a parameter
to make. makevar identifies a
variable that can be set (in the environment, on the
make command line, or within the
Makefile) to influence the process.maketarget and
makevarUse: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.]]>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 textYou 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.literalUse: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.]]>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 must fill
inThere 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.replaceableUse:&prompt.user; man command
]]>Appearance:&prompt.user; man commandreplaceable 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: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.]]>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.Quoting system errorsYou might want to show errors generated by FreeBSD.
Mark these with errorname. This
indicates the exact error that appears.errornameUse:Panic: cannot mount root ]]>
Appearance:Panic: cannot mount rootImagesImage 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
Makefiles 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.Image formatsWe currently support two formats for images. The format you
should use will depend on the nature of your image.For images that are primarily vector based, such as network
diagrams, time lines, and similar, use Encapsulated Postscript, and
make sure that your images have the .eps
extension.For bitmaps, such as screen captures, use the Portable Network
Graphic format, and make sure that your images have the
.png extension.These are the only formats in which images
should be committed to the CVS repository.Use the right format for the right image. It is to be expected
that your documentation will have a mix of EPS and PNG images. The
Makefiles ensure that the correct format image
is chosen depending on the output format that you use for your
documentation. Do not commit the same image to the
repository in two different formats.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.MarkupThe markup for an image is relatively simple. First, markup a
mediaobject. The mediaobject
can contain other, more specific objects. We are concerned with
two, the imageobject and the
textobject.You should include one imageobject, and two
textobject elements. The
imageobject will point to the name of the image
file that will be used (without the extension). The
textobject elements contain information that will
be presented to the user as well as, or instead of, the
image.There are two circumstances where this can happen.When the reader is viewing the documentation in HTML. In
this case, each image will need to have associated alternate
text to show the user, typically whilst the image is loading, or
if they hover the mouse pointer over the image.When the reader is viewing the documentation in plain text.
In this case, each image should have an ASCII art equivalent to
show the user.An example will probably make things easier to understand.
Suppose you have an image, called fig1, that
you want to include in the document. This image is of a rectangle
with an A inside it. The markup for this would be as
follows.<mediaobject>
<imageobject>
<imagedata fileref="fig1">
</imageobject>
<textobject>
<literallayout class="monospaced">+---------------+
| A |
+---------------+</literallayout>
</textobject>
<textobject>
<phrase>A picture</phrase>
</textobject>
</mediaobject>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 should contain a
literallayout element, where the
class attribute is set to
monospaced. This is your opportunity to
demonstrate your 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 should contain a
single phrase element. The contents of this
will become the alt attribute for the image
when this document is converted to HTML.Makefile entriesYour 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.Images and chapters in subdirectoriesYou must be careful when you separate your documentation into
smaller files (see ) in
different directories.Suppose you have a book with three chapters, and the chapters
are stored in their own directories, called
chapter1/chapter.sgml,
chapter2/chapter.sgml, and
chapter3/chapter.sgml. If each chapter has
images associated with it, I suggest you place those images in each
chapter's subdirectory (chapter1/,
chapter2/, and
chapter3/).However, if you do this you must include the directory names in
the IMAGES variable in the
Makefile, and you must
include the directory name in the imagedata
element in your document.For example, if you have chapter1/fig1.png,
then chapter1/chapter.sgml should
contain<mediaobject>
<imageobject>
<imagedata fileref="chapter1/fig1">
</imageobject>
…
</mediaobject>The directory name must be included in the
fileref attributeThe Makefile must contain…
IMAGES= chapter1/fig1.png
…Then everything should just work.LinksLinks are also in-line elements.Linking to other parts of the same documentLinking 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 sectionsIntroductionThis is the introduction. It contains a subsection,
which is identified as well.Sub-sect 1This is the subsection.
]]>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.anchorThis paragraph has an embedded
link target in it. It will not show up in
the document.]]>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.Using xrefAssume that this fragment appears somewhere in a document that
includes the id example;More information can be found
in .
More specific information can be found
in .]]>The text of the link will be generated automatically, and will
look like (emphasised 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.Using linkAssume that this fragment appears somewhere in a document that
includes the id example.More information can be found in
the first chapter.
More specific information can be found in
this section.]]>This will generate the following
(emphasised 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 documents on the WWWLinking 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.ulinkUse:Of course, you could stop reading this document and
go to the FreeBSD
home page instead.]]>Appearance:Of course, you could stop reading this document and go to the
FreeBSD home page
instead.