| Firebird Documentation Index → Firebird Docbuilding Howto → Building the Firebird docs |
|
|
|
Several Java tools are used to produce the HTML and PDF docs from the DocBook XML source. Therefore, you need a recent version of Java 2 installed on your system.
In the next subsections we will show you:
Where to get Java 2
Where to get the tools
How to set up the environment for the doc build process
How to build the HTML and PDF docs
If you already have a recent version of Java 2 installed, you may skip the first step.
Download and install only one of the following:
Java 2 Runtime Environment, Standard Edition – often abbreviated as J2RE SE.
Go to http://www.java.com/ and follow the links to the download pages. Get the version for your own OS. Clicking on a "Download" or "Get it now" link may lead to windows popping up, asking you if it's OK that Sun Microsystems installs stuff on your computer. If you agree, practically everything will be installed automatically. If that makes you feel uneasy, you can also download the installation program manually and run it yourself.
Java 2 Software Development Kit, Standard Edition – or J2SDK SE.
This is a much larger package, and it also contains the J2RE SE. If you want the SDK, go to http://java.sun.com/j2se/ and get the latest stable version. When you have to choose between JRE and SDK, take the SDK. (Yes, you can also get the J2RE from here, but you can get it easier and quicker from the link in the first option.) Download the installation program and run it.
If you don't understand the difference between the two, go for the first option: the Java 2 Runtime Environment. You don't need the SDK to build the Firebird docs.
The tools and libraries needed to build the HTML and PDF documents
come as Java JARs and
ZIP archives, and we used to keep them all in our
CVS repository so they landed automatically in the right place when you
checked out the manual module. However, it's bad practice to keep large
binaries in CVS, especially if their sources are already managed
elsewhere (they're all open-source tools). So nowadays we keep these
binaries out of CVS and place them on the Firebird website for you to
download.
After checking out the manual module, look in the manual/lib directory. It contains a file
_readme_libs.txt with exact instructions on
downloading and installing the missing libraries. Likewise,
_readme_tools.txt in manual/tools tells you where to download
some required tools.
The build scripts need an environment variable
JAVA_HOME pointing to the Java 2 install
directory.
On Windows, this is typically something of the form
C:\Program Files\Java\j2re1.4.2_01. To be sure,
check if there's a directory called bin
underneath it, and if this bin subdir contains
the file java.exe
On Linux, it may be /usr/lib/java/jre or
/usr/java/j2sdk, or... well, it can be a lot of
things. The same check applies: it should have a subdir
bin containing an executable file
java (without the .exe
extension here).
If you're lucky, the JAVA_HOME envar is already
present and correct. If not, you have to set it yourself, e.g. under
Windows with set JAVA_HOME=C:\Program
Files\Java\j2re1.4.2_01 or under Linux/bash with
export JAVA_HOME=/usr/lib/java/jre. (Note: these
paths are just examples; they may or may not be the same as
yours.)
Tip: make the JAVA_HOME envar permanent so you
won't have to set it again and again. How to do this depends on your OS.
Consult its documentation if necessary.
If you've made it here in one piece, you are finally ready to build the Firebird docs. Here's what to do:
If you haven't done so already, this is the moment to read the
ReadMe file that lives in the
manual directory. It may contain important
information not (yet) included in this Howto.
If you are in a graphical environment, open a command window.
Unless the ReadMe instructs you
otherwise, go to the folder manual/src/build
and give the command
build (in Windows), or
./build.sh (in Linux)
If everything was set up correctly, you now get a number of
output lines ending with BUILD SUCCESSFUL, and
mentioning some build targets (things you can
build).
Now you can build something more substantial, e.g.
build html or
build pdf or
build docs
Whatever you build will wind up in the directory tree under
manual/dist
If you build the PDF target, you will receive tons of
error messages. You can safely ignore them, as long as one of
the last lines reads BUILD
SUCCESSFUL.
Due to limitations in the build software, some PDF files may need manual post-processing before they are presentable. For your own use they're OK though, in the sense that “everything's in there”. If you do want to fix them up, read the topic Improving the PDF near the end of this guide.
To build documentation sets in non-English languages (in so far
as they are available) use the -Dsfx argument
and supply the language code, e.g.:
build pdf -Dsfx=es
build html -Dsfx=fr
Non-English output will go into subdirectories like
manual/dist/pdf/ru,
manual/dist/html/fr, etc.
If you don't specify -Dsfx, the English
set will be built.
Not all language sets contain the same amount of documentation. This depends on docwriters' and translators' activity. Usually, the English set will be the most complete and the most up-to-date.
The examples given so far all produce the entire docset (for one
language). If you want to build only part of it – e.g. a book, or an
article – use the -Drootid argument. This is
especially handy when building PDF targets, because otherwise the
entire set will wind up in one big, monstrous file.
With the -Drootid argument, you must
supply the ID of the element you want to build, for example:
build pdf -Drootid=fbutils
build pdf -Dsfx=fr -Drootid=qsg15-fr
How do you know the ID? You can find it in the DocBook XML
sources. Look for the id
attributes on elements such as book, article, and chapter. To find out more about this
subject, consult the Firebird Docwriting
Guide.
As you can see from the last example, command-line arguments can be combined.
Since January 2006, the Firebird Release Notes have been
integrated with the manual module, but they constitute a base set of
their own, parallel to the default
“firebirddocs” set. This has given
rise to yet another command-line parameter,
-Dbasename, whose value should be
“rlsnotes” to build the Release
Notes:
build pdf -Dbasename=rlsnotes
build pdf -Dbasename=rlsnotes -Drootid=rlsnotes20
build pdf -Dbasename=rlsnotes -Dsfx=fr
Meanwhile, another base set has been added:
papers.
The output from alternative base sets is written to the same
folders as usual, except in one case: the multi-file
html target output is placed in
manual/dist/html-<basename>, to avoid
mixing files from different base sets and so that the sets'
index.html files don't overwrite each other.
Non-English sets go into
manual/dist/html-<basename>/<sfx>.
For instance, the English HTML Release Notes are written to
manual/dist/html-rlsnotes, the French notes to
manual/dist/html-rlsnotes/fr.
Rendering monohtml and
pdf into the same folder as the default set
causes no problems, as these targets generate single-file outputs,
each with a unique filename.
Do you often find yourself building the same base set, language
version, and/or subset? Then you may want to set the corresponding
parameter value(s) in the build control file
build.xml, so you don't have to type them on the
command line every time. Instructions can be found near the top of
build.xml, at the beginning of the
init target.
If you make use of this feature, you can still build the other
stuff by overriding your personal settings at the command line. For
instance, if you have set basename to
rlsnotes in the build file, you can build the
default docset like this:
build html -Dbasename=firebirddocs
That's it – you are now a certified Firebird doc builder. Congratulations!
If you want to write or translate docs for the Firebird Project yourself, also read the Firebird Docwriting Guide.
|
| Firebird Documentation Index → Firebird Docbuilding Howto → Building the Firebird docs |