2.2. The Document Build System

2.2. The Document Build System
Prev	Chapter 2. How Modules Work	Next

The build system can render the document into another format such as HTML or PDF, using make(1)^[2] and shell scripts. Authors need no prior experience with either shell scripts or a make(1).

2.2.1. The Document `Makefile`

Each individual document has its own Makefile, which only needs to be a few lines long. The document Makefile content is designed for cut and paste operations.

Example 2.2, “Sample Document Makefile” below shows the whole Makefile for a simple document with two files and two translations.

DOCBASE         = example-doc
PRI_LANG        = en_US
DOC_ENTITIES    = doc-entities

define XMLFILES_template
XMLFILES-${1}   = ${1}/example-doc.xml \
                  ${1}/para.xml
endef

define find-makefile-common
for d in docs-common ../docs-common ../../docs-common; do 
if [ -f $$d/Makefile.common ]; then echo "$$d/Makefile.common"; break; fi; done 
endef
include $(shell $(find-makefile-common))

Example 2.2. Sample Document Makefile

Do not be concerned with some of the more complicated syntax such as the XMLFILES_template stanza. An explanation for this template appears a few paragraphs below.

Makefile Variables

Variable	Explanation
`DOCBASE`	This variable contains the name for the main (parent) XML document. Follow convention by naming your document after the module name.
`PRI_LANG`	This variable contains the ISO code for the original version of the document, such as `en_US`.
`DOC_ENTITIES`	This variable contains a listing of any files containing entity definitions. The Fedora Documentation Project uses a special XML format to record document-specific entities, so they can be translated and built on the fly like any other XML document. An example is shown later in this guide.
`XMLFILES_template`	This template allows the build tools to work with the document in multiple languages once it is translated. The `${1}` marking is a variable used to substitute the appropriate language. This template is not terribly complicated. For a new module, duplicate this section exactly except for the actual filenames. Prepend the text `${1}/`, in place of the language code directory name, to each filename in your document.

	Files Exempt From Listing
	Do not include the document-specific entities XML file or the `rpm-info.xml` file, which will be discussed later in this guide.

The final section, beginning with define, locates the main Makefile.common for the build system. This Makefile.common file contains all the make(1) targets and rules to actually build the document and the various archives.

2.2.2. The Document `rpm-info.xml`

Each document module's primary language directory contains a file called rpm-info.xml. This file contains document-specific metadata used to generate revision history, copyright, and contributor information. It follows a DTD specification included with the rest of the build system tools.

^[2]In Linux and Fedora documentation, references to commands often include a number inside parentheses. This number represents the section of manpages that includes documentation for that command. To read the manpage for make(1), use the command man 1 make.