DocBook Makefile Templates

mw@miwie.in-berlin.de

Revision History
Revision 0.1.16 2001-04-19

Legal Notice

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no invariant sections, with no Front-Cover texts and no Back-Cover Texts.

1. Introduction

This document tries to describe the files and usage of the DocBook Makefile Templates which are heavily based on the makefiles for the FreeBSD Documentation Project.

I adapted the original FreeBSD Makefiles for use on Debian/GNU Linux systems. If anyone supplies the appropriate values for other Linux distributions, I will add them to the corresponding file (look at doc.os.mk).

These makefiles are Berkeley Makefiles so you need a Berkeley compatible version of make. On Debian/GNU Linux systems pmake can be used. On other systems watch out for bmake.

Feedback is always welcome!

1.1. Files

Following you find a short description of the main files of the distribution.

pmake.mk

Master makefile. Most users will only edit this file (or a copy of it). See below for a more detailled description.

doc.local.mk

Included if found in current working directory and holds local extensions. Can e.g. be used for additional automatic graphic file conversion. For details see Local extensions.

doc.project.mk

Includes the rest of the Makefiles.

doc.os.mk

Holds all operating system specific variables and their values (pathnames, etc.). Known operating system currently are FREEBSD and DEBIAN.

doc.images.mk

Builds targets for automatic conversion of graphic files.

doc.docbook.mk

Holds main part.

doc.subdir.mk

Contains the default targets for building subdirectories.

doc.install.mk

Provides variables defining the default ownership, location, and installation method.

freebsd.dsl

Default styleheet file. Make all your customizations in this file.

2. Usage

2.1. Putting files in place

In general there are two ways to put the files in place on your system. Use one of the listed possibilities:

• Copy all *.mk files to your working directory.

• Copy all *.mk files (except doc.local.mk) to a directory which is searched by your version of Berkeley Make (/usr/share/mk/ on Debian).

2.2. Master Makefile

You should edit the file pmake.mk (or a copy of it) to hold the specific values for your documentation project. You may rename it e.g. to Makefile, this let's you just run pmake without a command line argument -f pmake.mk for setting the name of the Makefile.

The variables in the supplied version of pmake.mk are commented so you should be able to guess what they mean.

The most important operators for assigning values to variables are:

=

Assign the value to the variable, overriding any previous value.

+=

Append the value to the current value of the variable.

?=

Assign the value to the variable if it is not already defined.

Most likely you will only use the operator = in your Master Makefile. Experienced users may use ?= if they plan to override some variables from the command line.

2.2.1. Required variables

The following variables need to hold correct project specific values:

DOC

Set this to the filename of your document without extension.

Default: none

FORMATS

List all output formats (space separated) which should be generated by invoking the build process without a given target.

Possible values: html html.tar html-split html-split.tar txt rtf ps pdf tex dvi tar pdb

Default: none

IMAGES

List all graphics files used in the document, including filename extension.

Default: empty

SRCS

List here all source files of your documentation project. This value is used for checking whether all targets are up-to-date and creating tarballs of your project.

Default: none

OS

If you are on a Debian/GNU Linux system, set this to DEBIAN. The operating system specific values like file and pathnames are controlled by this variable.

Possible values: FREEBSD, DEBIAN

Default: FREEBSD

2.2.2. Optional variables

The following variables are optional and control the build process.

DOCBOOKSUFFIX

Set the document filename extension here if your document uses a filename extension other than the default.

Default: sgml

DSLHTML

Filename (including pathname if necessary) to the DSSSL stylesheet file for HTML output.

Default: ./freebsd.dsl

DSLPRINT

Filename (including pathname if necessary) to the DSSSL stylesheet file for print output.

Default: ./freebsd.dsl

INSTALL_COMPRESSED

Set this to the extension of the compression utility you want to use for compressing output files.

Possible values: gz bz2 zip

Default: none

GEN_INDEX

If defined, index.sgml will be added to the list of dependencies for source files, and collateindex.pl will be run to generate index.sgml.

Currently the generation of index.sgml does not work yet for PDF/PS output!

Default: empty

If set, use openjade to process the document. Using the default stylesheets this allows for creating outlines (bookmarks) which make the navigation easier.

PREFIX

Default: /usr

PALMDOCTITLE

Used as the title for the prc/pdb target.

Default: name of the main document.

2.3. Including graphics files

Following the guidelines which Nik Clayton explains in detail in his posting to the DocBook ML from 10 Feb 2001 the Makefiles assume that all used graphic files are referenced in their <imagedata> tags without a filename extension. The backend drivers choose the most acceptable format. For the necessary customization of the styleheet file see the next section.

The following lines shows how to edit your source file:

  
All files listed in the IMAGES variable are converted to the needed formats. This automatic conversion step may not fully work yet in all cases.

tbd.

2.4. Stylesheet customization

You definitely want to customize the output of your DocBook document. You can do this by editing the stylesheet file freebsd.dsl. Look carefully over this file, most variables have meaningful comments so you should be able to figure out what they mean.

More experienced users should additionally look at the original DocBook DSSSL customization files for print and HTML output (dbparam.dsl). If you find a variable which isn't yet referenced in freebsd.dsl just copy and paste it and set its value accordingly.

On Debian systems you find these files in /usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/html/ and /usr/lib/sgml/stylesheet/dsssl/docbook/nwalsh/print/).

2.4.1. Detailled description of freebsd.dsl

The default stylesheet customization file basically is divided into 5 parts: output.html, output.print, output.html.images, output.print.pdf, and a section for both HTML and print stylesheets. Each part is conditionally included by corresponding command line arguments to (open)jade (e.g. -i output.print.pdf).

tbd.

2.5. Building

After editing the master makefile building the desired outpout formats is simply invoking make like:

  $pmake -f pmake.mk  For building formats other than the ones listed in FORMAT just type e.g.:  $ pmake -f pmake.mk PROJECT.ps 
To create a tarball with all sourcefiles type: