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