The Handbook is written to comply with the FreeBSD DocBook extended DTD. The Handbook is organised as a DocBook book. It is then divided into parts, each of which may contain several chapters. chapters are further subdivided into sections (sect1) and subsections (sect2, sect3) and so on. The Handbook (and its translations) are in the doc/language/handbook subdirectory of the main CVS repository. language corresponds to the ISO language code for that translation, en for English, ja for Japanese, and so on. There are a number of files and directories within the handbook directory. The Handbook's organisation may change over time, and this document may lag in detailing the organisational changes. If you have any questions about how the Handbook is organised, please contact the FreeBSD Documentation Project, doc@FreeBSD.ORG. The Makefile defines the rules that are used to convert the Handbook from its source form (DocBook) to a number of other target formats (including HTML, PostScript, and plain text). A more detailed description of the Makefile is in . 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. handbook.sgml 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.sgml 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.sgml 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 handbook.sgml, and named after the value of the id attribute on the file's chapter element. Moving them in to 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 and 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.sgml files, including basics/chapter.sgml, introduction/chapter.sgml, and printing/chapter.sgml. 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 reorganised; this sort of reorganistion should not (generally) include the need to rename files (unless entire chapters are being promoted or demoted within the hierarchy). Each chapter.sgml file will not be a complete SGML document. In particular, they will not have their own DOCTYPE line at the start of the file. This is unfortunate for two reasons; 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 as had on just one chapter. Emacs' sgml-mode can not use it to determine the DTD to use, losing useful benefits of sgml-mode (element completion, automatic validation, and so on). To keep the source for the Handbook consistent when many different people are editing it, please follow these style conventions. Tags are entered in lower case, <para>, not <PARA>. Text that appears in SGML contexts is generally written in upper case, <!ENTITY…>, and <!DOCTYPE…>, not <!entity…> and <!doctype…>. Each file starts with indentation set at column 0, regardless of the indentation level of the file which might contain this one. Every start tag increases the indentation level by 2 spaces, and every end tag decreases the indentation level by 2 spaces. Content within elements should be indented by two spaces if the content runs over more than one line. For example, the source for this section looks something like; Each file starts with indentation set at column 0, regardless of the indentation level of the file which might contain this one. Every start tag increases the indentation level by 2 spaces, and every end tag decreases the indentation level by 2 spaces. Content within elements should be indented by two spaces if the content runs over more than one line. ... ]]> If you use Emacs or Xemacs to edit the files then sgml-mode should be loaded automatically, and the Emacs local variables at the bottom of each file should enforce these styles. When committing changes, do not commit changes to the content at the same time as changes to the formatting. This is so that the teams that convert the Handbook to other languages can quickly see what content has actually changed in your commit, without having to decide whether a line has changed because of the content, or just because it has been refilled. For example, if you have added two sentances to a paragraph, such that the line lengths on the paragraph now go over 80 columns, first commit your change with the too-long line lengths. Then fix the line wrapping, and commit this second change. In the commit message for the second change, be sure to indicate that this is a whitespace-only change, and that the translation team can ignore it.