Firebird Documentation IndexFirebird Docbuilding Howto → Building the Firebird docs
Firebird Home Firebird Home Prev: Getting the manual module from SFFirebird Documentation IndexUp: Firebird Docbuilding HowtoNext: Keeping the module up to date

Building the Firebird docs

Where to get Java 2
Where to get the tools
How to set up the environment for the build
Building the HTML and PDF 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:

  1. Where to get Java 2

  2. Where to get the tools

  3. How to set up the environment for the doc build process

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

Where to get Java 2

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.

Where to get the tools

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.

How to set up the environment for the build

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.

Building the HTML and PDF docs

If you've made it here in one piece, you are finally ready to build the Firebird docs. Here's what to do:

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

  2. If you are in a graphical environment, open a command window.

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

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

Notes

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

Warning

If your local copy of the manual module is placed in a path that contains spaces or other non-alphanum, non-underscore characters, the PDF build may fail because an intermediate file is placed in a newly created path with the same name, except that all the “offending” characters are replaced with their URL-encodings: space becomes %20, etc.

The monohtml build too (monohtml is the same as html, but as one big web page) will wind up in the urlencoded equivalent of the path. But the images that go with the page are placed in the original path. All this is caused by a Java class that performs some of the build tasks and converts path names to URLs in the process.

The best way to avoid these problems is to place the manual module in a path that contains only unaccented letters, digits and/or underscores. The second best way is to make the URL-encoded version of the path a symlink to the real path. Once you have set up the symlink, all the future builds will go fine. (This may not work on Windows, however.)

Building non-English sets with -Dsfx

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.

Warning

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.

Building subsets with -Did

The examples given so far all produce the entire docset (for one language). Usually, this is not what you want. To build a specific document – e.g. a book or an article – use the -Did argument.

With the -Did argument, you must supply the ID of the element you want to build, for example:

build pdf -Did=fbutils

build pdf -Dsfx=fr -Did=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.

Building a different base set with -Dbase

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, -Dbase (pun intended), whose value should be “rlsnotes” to build the Release Notes:

build pdf -Dbase=rlsnotes

build pdf -Dbase=rlsnotes -Did=rlsnotes20

build pdf -Dbase=rlsnotes -Dsfx=fr

Meanwhile, two other base sets have been added: papers and refdocs.

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-<base>, 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-<base>/<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.

Setting default values in build.xml

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 base to rlsnotes in the build file, you can build the default docset like this:

build html -Dbase=firebirddocs

Building the docs – conclusion

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.

Prev: Getting the manual module from SFFirebird Documentation IndexUp: Firebird Docbuilding HowtoNext: Keeping the module up to date
Firebird Documentation IndexFirebird Docbuilding Howto → Building the Firebird docs