| Firebird Documentation Index → Firebird Docbuilding Howto → Building the Firebird docs with Gradle |
|
|
|
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 installed on your system.
In the next subsections we will show you:
Where to get Java
How to set up the environment for the doc build process
How to build the HTML and PDF docs
If you already have recent version of Java installed, you may skip the first step.
Download and install:
Java Development Kit, Standard Edition version 8 or earlier – or JDK SE.
This is a much larger package, and it also contains the JRE SE. If you want the JDK, go to https://www.oracle.com/technetwork/java/javase/downloads/index.html or to https://adoptopenjdk.net/ and get the latest stable version. When you have to choose between JRE and JDK, take the JDK. Download the installation program and run it.
The build scripts need an environment variable JAVA_HOME pointing to the
Java install directory.
On Windows, this is typically something of the form C:\Program
Files\Java\jdk1.8.0_232. 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/jdk, 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\jdk1.8.0_232 or under Linux/bash with export
JAVA_HOME=/usr/lib/java/jdk. (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.md file that lives in the firebird-documentation 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.md instructs you otherwise, go to the folder
firebird-documentation/ and give the command
gradlew (in Windows), or
./gradlew (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.
gradlew docbookHtml or
gradlew docbookPdf
Whatever you build will wind up in the directory tree under firebird-documentation/build
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.
If your local copy of the firebird-documentation repository 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 best way to avoid these problems is to place the firebird-documentation repository 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.)
To build documentation sets in non-English languages (in so far as they are available)
use the --language argument and supply the language code,
e.g.:
gradlew docbookPdf --language=es
gradlew docbookHtml --language=fr
Non-English output will go into subdirectories like firebird-documentation/build/pdf-firebirddocs-ru, firebird-documentation/build/html-firebirddocs-fr, etc.
If you don't specify --language, 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). Usually,
this is not what you want. To build a specific document – e.g. a book or an article – use
the --docId argument.
With the --docId argument, you must supply the ID of the
element you want to build, for example:
gradlew docbookPdf --docId=fbutils
gradlew docbookPdf --language=fr --docId=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
firebird-documentation repository, 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, --baseName (pun intended), whose
value should be “rlsnotes” to build the Release
Notes:
gradlew docbookPdf --baseName=rlsnotes
gradlew docbookPdf --baseName=rlsnotes --docId=rlsnotes20
gradlew docbookPdf --baseName=rlsnotes --language=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
firebird-documentation/build/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
firebird-documentation/build/html-<baseName>-<language>.
For instance, the English HTML Release Notes are written to firebird-documentation/build/html-rlsnotes, the French notes to
firebird-documentation/build/html-rlsnotes-fr.
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 with Gradle |