Abstract
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.
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.
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 builds a repository template so that users can quickly start using Borges.
Tip
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.
The diagram below shows how the different Makefiles provided by Borges are distributed in the implementation repository.
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”.
All paths are relative to the project root directory 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, “Adding/changing Manuals Rules” 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, “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.
- 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 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.