Chapter 7. Programmer's Reference manual

1. Makefiles
1.1. Borges source Makefile
1.2. Documentation Projects Makefiles
1.3. Makefiles in Action
2. The Way a Manual is Generated
3. Adding/changing Manuals Rules
4. Supporting Another DTD than DocBook
5. Notes on Borges Installation
5.1. Installing Borges on an Unusual Path
5.2. Adapting Borges to unusual Environment


Here we will get into the Borges internals. This may be of interest for the developer as well as for the user wishing to take advantage of the most advanced features of Borges.

If something is not clear enough below, or if you wish to know more, use the source Luke. If there's something you definitely do not understand, ask on Borges mailing list.

1. Makefiles

We will list here the different Makefiles available in Borges source repository and in the implemented repositories[5]. We will detail the way those Makefiles are generated, distributed, etc.

1.1. Borges source Makefile

There's only one usable Makefile here. You'll find it at the root of the repository.

This Makefile has two main targets:


compiles the Borges documentation and reports;


installs Borges on a system so that users of that system can start documentation projects on it, using Borges. It installs all the scripts and Makefile's and builds a repository template so that users can quickly start using Borges.


Borges gets installed in /usr/share by default (/usr/share/Borges/). You can change that by passing the TARGET parameter to make. For example if you wish to relocate Borges to /home/joe/test/Borges/ just run make install TARGET=/home/joe/test

You may have noticed that Borges does not need compilation. Indeed all scripts are in Perl or bash and do not need compilation.

1.2. Documentation Projects Makefiles

1.2.1. What Goes Where

The diagram below shows how the different Makefiles provided by Borges are distributed in the implementation repository.

1.2.2. Who Calls Who

The following diagram shows how the Makefiles found in the Borges source repository (on the left) gets distributed into an imaginary project (on the right) with two books Book1 and Book2 in two languages en and fr

Figure 7.1. Distributing Makefiles

Distributing Makefiles

1.3. Makefiles in Action

Here we show you how Makefiles are linked together. Figure 7.2, “Makefiles Relationships” shows how Makefiles include each other. An arrow in the diagram means “includes”.

Figure 7.2. Makefiles Relationships

Makefiles Relationships

All paths are relative to the project root directory unless otherwise stated.

We can distinguish between four types:


The Makefiles on the left are the ones actually used to perform tasks on manuals, modules, images, etc.


This Makefile is empty by default. It can be used by advanced users to redefine default manual compilation rules. See Section 3, “Adding/changing Manuals Rules” for more details.


This Makefile contains the rules to actually transform source XML DocBook files to any desired output format (PDF, HTML, etc.). Advanced users may choose to develop their own Makefile.XXX to support another DTD. See Section 4, “Supporting Another DTD than DocBook” for more details on how to do that.

To determine which Makefile is used to generate output formats, the system looks for the <makefile> element(s) in conf/repository.xml and sets the OUTPUTS variable accordingly in the root Makefile.include described below.


This Makefile is automatically generated by the root Makefile. It contains useful information for all other Makefiles, extracted from the environment and notably from the main configuration file conf/reposqitory.xml. It also contains some generic functions and rules.

[5] It is important to distinguish between the Borges source repository, which is the repository holding all the Borges code maintained by its developers; and a simple implementation of Borges, which is a documentation project repository, containing the documentation source files managed by Borges.