| |
| ------------------------------------------------------------ |
| About this README |
| ------------------------------------------------------------ |
| |
| This README is intended to document the build process of the Apache Guacamole |
| manual for technical users who wish to contribute or who simply wish to build |
| the manual themselves. |
| |
| The latest version of the manual is provided on the Guacamole web site, and |
| snapshot copies of each release are included in the release archives: |
| |
| http://guacamole.incubator.apache.org/ |
| |
| |
| ------------------------------------------------------------ |
| What is guacamole-manual? |
| ------------------------------------------------------------ |
| |
| The guacamole-manual package is the base documentation for the entire Guacamole |
| stack. It is written in DocBook, an XML schema commonly used for authoring |
| manuals and technical documentation. |
| |
| The build process involves running the Guacamole manual XML through an XSLT |
| processor called "xsltproc", applying the standard DocBook XSL stylesheets. |
| |
| |
| ------------------------------------------------------------ |
| Building the manual |
| ------------------------------------------------------------ |
| |
| |
| 1) Ensure the DocBook XSL stylesheets are installed |
| |
| Most Linux distributions will provide a "docbook-xsl" or similarly-named |
| package which install the DocBook stylesheets in a system-wide manner. You |
| will need to either install these packages, or download the DocBook XSL |
| stylesheets yourself: |
| |
| https://sourceforge.net/projects/docbook/files/docbook-xsl/ |
| |
| 2) Ensure the DOCBOOK_PATH environment variable is set |
| |
| The manual build process depends on an environment variable, DOCBOOK_PATH, |
| which points to the directory in which the DocBook XSL files can be found. |
| |
| This will be the directory that contains the following files: |
| |
| fo/docbook.xsl |
| html/chunk.xsl |
| |
| $ export DOCBOOK_PATH=/usr/share/sgml/docbook/xsl-ns-stylesheets-1.78.1 |
| |
| 3) Ensure xsltproc and fop are installed |
| |
| If you do not have xsltproc, the manual will not build. The provided |
| Makefile depends entirely on using xsltproc to process the Guacamole manual |
| XML through the installed DocBook stylesheets. |
| |
| Although not required for building the HTML manual, if you do not have fop |
| (Apache FOP), the PDF version of the manual cannot be built. The build |
| process uses fop to transform a ".fo" file into the PDF. |
| |
| 4) Run make |
| |
| $ make |
| |
| The manual will now be built using xsltproc. Once complete, the entire |
| HTML version of the manual will be available within the "html" directory in |
| the root directory of the source tree, and the PDF version will be |
| available within the "book" directory as "gug.pdf". |
| |
| The default build target, "all", will build both the HTML and PDF versions |
| of the manual. If you only wish to build the HTML manual, you can specify |
| the "html" target explicitly: |
| |
| $ make html |
| |
| Similarly, if you only wish to build the PDF, you can force this by |
| explicitly specifying the "book" target: |
| |
| $ make book |
| |
| |
| ------------------------------------------------------------ |
| Reporting problems |
| ------------------------------------------------------------ |
| |
| Please report any bugs encountered by opening a new issue in the JIRA system |
| hosted at: |
| |
| https://issues.apache.org/jira/browse/GUACAMOLE |
| |
