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 郵遞論壇.
The Makefile
defines some variables that
affect how the SGML 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:
<chapter id="kernelconfiguration"> ... </chapter>
then it will be called chapter.xml
in
the kernelconfiguration
directory. In
general, the entire contents of the chapter will be held in this
file.
When the HTML version of the Handbook is produced, this will
yield kernelconfiguration.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. Moving them into
separate directories prepares for future plans for the Handbook.
Specifically, it will soon be possible to include images in each
chapter. It makes more sense for each image to be stored in a
directory with the text for the chapter than to try to keep the
text for all the chapters, and all the images, in one large
directory. 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 SGML 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 SGML 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.
All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.