Chapter 4. Documentation Directory Structure
Prev		Next

Chapter 4. Documentation Directory Structure

Table of Contents

4.1. The Top Level, doc/
4.2. The lang.encoding/ Directories
4.3. Document-Specific Information

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.

4.1. The Top Level, `doc/`

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 make(1) infrastructure are in share/mk, while the additional XML support files (such as the FreeBSD 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.

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 make(1) infrastructure are in `share/mk`, while the additional XML support files (such as the FreeBSD 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.

Prev		Next
3.7. Subversion References	Home	4.2. The `lang.encoding/` Directories

Chapter 4. Documentation Directory Structure

4.1. The Top Level, doc/

4.1. The Top Level, `doc/`