7.2. Understanding Makefiles in the Documentation tree

7.2.1. Subdirectory Makefiles

These directories 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 overridable, 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.

7.2.2. Documentation Makefiles

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

Here is an example:

    [email protected]
    
    DOC?= book
    
    FORMATS?= html-split html
    
    INSTALL_COMPRESSED?= gz
    INSTALL_ONLY_COMPRESSED?=
    
    # SGML content
    SRCS=  book.sgml
    
    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 .sgml 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.

The DOC_PREFIX and include statements should be familiar already.