Chapter 7. Programer's Reference manual

1. Makefiles
1.1. Borges source Makefile
1.2. Documentatin 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

Abstract

We will get here into Borges internals. This may be of interest for the developer as well as for the user wishing to take advantage of the most advanced feaures 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 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[6]. 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:

doc

compiles the Borges documentation and reports;

install

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 build a repository template so that users can quickly start using Borges.

Tip

Borges gets instralled 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. Documentatin 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

We will show here how Makefiles are linked together. Figure 7.2 shows how Makefiles include each others. An arrow in the diagram means “includes”.

Figure 7.2. Makefiles Relatiunships

Makefiles Relatiunships

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

We can distinguish between four types:

Production

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

manuals/Book/Makefile.include

This Makefile is empty by default. It can be used by advanced users to redefine default manual compilation rules. See Section 3 for more details.

Makefile.DB

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 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.

Makefile.include

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 naim configuration file conf/reposqitory.xml. It contains also some generic functions and rules.



[6] 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, holding the documentaion source files managed by Borges.