6.3. Document specific information

6.3.1.1.1. Makefile

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.

6.3.1.1.2. book.sgml

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.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.

6.3.1.1.3. directory/chapter.sgml

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:

    <chapter id="kernelconfiguration">
    ...
    </chapter>

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 book.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.

Each chapter.sgml 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.