| Firebird Docset → Firebird Docwriters' Docs → 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 needed to build the HTML and PDF documents come as Java JARs, 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 compiled libraries in CVS, especially if their sources are already managed elsewhere (they're all open-source tools). So nowadays we don't commit new tool versions to CVS anymore. Instead, we 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.
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. Same check applies: there should be a subdir bin underneath it containing an executable file java (without the .exe this time).
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, most PDF files will need some – tedious – 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 section on 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. But this is something that will be discussed in the Firebird Docwriting Howto. Using the -Drootid argument is typically something that's done by docwriters, not by casual builders.
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
In the future, more base sets may be added.
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 Docset → Firebird Docwriters' Docs → Firebird Docbuilding Howto → Building the Firebird docs |