Files and directories in the doc/ tree follow a structure meant to: Make it easy to automate converting the document to other formats. Promote consistency between the different documentation organizations, to make it easier to switch between working on different documents. Make it easy to decide where in the tree new documentation should be placed. In addition, the documentation tree must accommodate documents in many different languages and encodings. It is important that the documentation tree structure does not enforce any particular defaults or cultural preferences. There are two types of directory under doc/, each with very specific directory names and meanings. Directory Usage share Contains files that are not specific to the various translations and encodings of the documentation. Contains subdirectories to further categorize the information. For example, the files that comprise the &man.make.1; infrastructure are in share/mk, while the additional XML support files (such as the &os; extended DocBook DTD) are in share/xml. lang.encoding One directory exists for each available translation and encoding of the documentation, for example en_US.ISO8859-1/ and zh_TW.UTF-8/. The names are long, but by fully specifying the language and encoding we prevent any future headaches when a translation team wants to provide documentation in the same language but in more than one encoding. This also avoids problems that might be caused by a future switch to Unicode. These directories contain the documents themselves. The documentation is split into up to three more categories at this level, indicated by the different directory names. Directory Usage articles Documentation marked up as a DocBook article (or equivalent). Reasonably short, and broken up into sections. Normally only available as one XHTML file. books Documentation marked up as a DocBook book (or equivalent). Book length, and broken up into chapters. Normally available as both one large XHTML file (for people with fast connections, or who want to print it easily from a browser) and as a collection of linked, smaller files. man For translations of the system manual pages. This directory will contain one or more manN directories, corresponding to the sections that have been translated. Not every lang.encoding directory will have all of these subdirectories. It depends on how much translation has been accomplished by that translation team. This section contains specific notes about particular documents managed by the FDP. books/handbook/ The Handbook is written in DocBook XML using the &os; DocBook extended DTD. The Handbook is organized as a DocBook book. The book is divided into parts, each of which contains several chapters. chapters 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. Post questions about Handbook organization to the &a.doc;. 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, 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="kernelconfig" ... chapter Then it will be called chapter.xml in the kernelconfig directory. In general, the entire contents of the chapter are in this one 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. The localized version of these images should be placed in the same directory as the XML sources for each chapter. Namespace collisions are 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. Do not name chapters or directories after their ordering within the Handbook. This ordering can change as the content within the Handbook is reorganized. Reorganization should be possible without renaming files, unless entire chapters are being promoted or demoted within the hierarchy. The chapter.xml files are not complete XML documents that can be built individually. They can only be built as parts of the whole Handbook.