This section contains specific notes about particular documents managed by the FDP.
The Handbook is written to comply with the FreeBSD DocBook extended DTD.
The Handbook is organized as a DocBook
book
. It is then divided into
part
s, each of which may contain several
chapter
s. chapter
s are
further subdivided into sections (sect1
)
and subsections (sect2
,
sect3
) and so on.
There are a number of files and directories within the
handbook
directory.
The Handbook's organization may change over time, and this document may lag in detailing the organizational changes. If you have any questions about how the Handbook is organized, please contact the FreeBSD documentation project mailing list.
The Makefile
defines some
variables that affect how the XML source is converted to
other formats, and lists the various source files that
make up the Handbook. It then includes the standard
doc.project.mk
file, to bring in the
rest of the code that handles converting documents from
one format to another.
This is the top level document in the Handbook. It contains the Handbook's DOCTYPE declaration, as well as the elements that describe the Handbook's structure.
book.xml
uses parameter
entities to load in the files with the
.ent
extension. These files
(described later) then define general
entities that are used throughout the rest of the
Handbook.
Each chapter in the Handbook is stored in a file
called chapter.xml
in a separate
directory from the other chapters. Each directory is
named after the value of the id
attribute on the chapter
element.
For example, if one of the chapter files contains:
Then it will be called
chapter.xml
in the
kernelconfig
directory. In general,
the entire contents of the chapter will be held in this
file.
When the XHTML version of the Handbook is produced,
this will yield kernelconfig.html
.
This is because of the id
value, and is
not related to the name of the directory.
In earlier versions of the Handbook the files were
stored in the same directory as
book.xml
, and named after the value
of the id
attribute on the file's
chapter
element. Now, it is possible
to include images in each chapter. Images for each
Handbook chapter are stored within share/images/books/handbook
.
Note that localized version of these images should be
placed in the same directory as the XML sources for each
chapter. Namespace collisions would be inevitable, and it
is easier to work with several directories with a few
files in them than it is to work with one directory that
has many files in it.
A brief look will show that there are many directories
with individual chapter.xml
files,
including basics/chapter.xml
,
introduction/chapter.xml
, and
printing/chapter.xml
.
Chapters and/or directories should not be named in a fashion that reflects their ordering within the Handbook. This ordering might change as the content within the Handbook is reorganized; this sort of reorganization should not (generally) include the need to rename files (unless entire chapters are being promoted or demoted within the hierarchy).
Each chapter.xml
file will not
be a complete XML document. In particular, they will not
have their own DOCTYPE lines at the start of the
files.
This is unfortunate as it makes it impossible to treat these as generic XML files and simply convert them to HTML, RTF, PS, and other formats in the same way the main Handbook is generated. This would force you to rebuild the Handbook every time you want to see the effect a change has had on just one chapter.
This, and other documents, can be downloaded from http://ftp.FreeBSD.org/pub/FreeBSD/doc/
For questions about FreeBSD, read the
documentation before
contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.