8.2. Understanding `Makefile`s in the Documentation Tree
Prev | Chapter 8. The Documentation Build Process | Next

## 8.2. Understanding `Makefile`s in the Documentation Tree

There are three main types of `Makefile`s in the FreeBSD Documentation Project tree.

- Subdirectory `Makefile`s simply pass commands to those directories below them.

- Documentation `Makefile`s describe the document(s) that should be produced from this directory.

- Make includes are the glue that perform the document production, and are usually of the form `doc.`xxx`.mk`.

### 8.2.1. Subdirectory `Makefile`s

These `Makefile`s usually take the form of:

SUBDIR =articles SUBDIR+=books COMPAT_SYMLINK = en DOC_PREFIX?= ${.CURDIR}/.. .include "${DOC_PREFIX}/share/mk/doc.project.mk"

In quick summary, the first four non-empty lines define the make variables, `SUBDIR`, `COMPAT_SYMLINK`, and `DOC_PREFIX`.

The first `SUBDIR` statement, as well as the `COMPAT_SYMLINK` statement, shows how to assign a value to a variable, overriding any previous value.

The second `SUBDIR` statement shows how a value is appended to the current value of a variable. The `SUBDIR` variable is now `articles books`.

The `DOC_PREFIX` assignment shows how a value is assigned to the variable, but only if it is not already defined. This is useful if `DOC_PREFIX` is not where this `Makefile` thinks it is - the user can override this and provide the correct value.

Now what does it all mean? `SUBDIR` mentions which subdirectories below this one the build process should pass any work on to.

`COMPAT_SYMLINK` is specific to compatibility symlinks (amazingly enough) for languages to their official encoding (`doc/en` would point to `en_US.ISO-8859-1`).

`DOC_PREFIX` is the path to the root of the FreeBSD Document Project tree. This is not always that easy to find, and is also easily overridden, to allow for flexibility. `.CURDIR` is a make builtin variable with the path to the current directory.

The final line includes the FreeBSD Documentation Project's project-wide make system file `doc.project.mk` which is the glue which converts these variables into build instructions.

### 8.2.2. Documentation `Makefile`s

These `Makefile`s set a bunch of make variables that describe how to build the documentation contained in that directory.

Here is an example:

MAINTAINER=nik@FreeBSD.org DOC?= book FORMATS?= html-split html INSTALL_COMPRESSED?= gz INSTALL_ONLY_COMPRESSED?= # SGML content SRCS= book.xml DOC_PREFIX?= ${.CURDIR}/../../.. .include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"

The `MAINTAINER` variable is a very important one. This variable provides the ability to claim ownership over a document in the FreeBSD Documentation Project, whereby you gain the responsibility for maintaining it.

`DOC` is the name (sans the `.xml` extension) of the main document created by this directory. `SRCS` lists all the individual files that make up the document. This should also include important files in which a change should result in a rebuild.

`FORMATS` indicates the default formats that should be built for this document. `INSTALL_COMPRESSED` is the default list of compression techniques that should be used in the document build. `INSTALL_ONLY_COMPRESS`, empty by default, should be non-empty if only compressed documents are desired in the build.

### Note:

We covered optional variable assignments in the previous section.

The `DOC_PREFIX` and include statements should be familiar already.

Prev | Up | Next
Chapter 8. The Documentation Build Process | Home | 8.3. FreeBSD Documentation Project Make Includes

This, and other documents, can be downloaded from http://ftp.FreeBSD.org/pub/FreeBSD/doc/

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.