| |
| ------------------------------------------------------------ |
| 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.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 |
| |
| |
| ------------------------------------------------------------ |
| Building and viewing the manual using Docker |
| ------------------------------------------------------------ |
| |
| The guacamole-manual package includes a Dockerfile that can be used to build |
| an Apache httpd Docker image that contains the Guacamole user manual. |
| |
| By building and running the resulting container, a developer can work on the |
| user manual without the need to install docbook and related dependencies on |
| his/her workstation. The resulting container can also be used to serve the |
| manual to Guacamole users on a network. |
| |
| Docker CE version 1.6 or later is required to build the image. |
| |
| Build the Guacamole manual container image by running the following command in |
| the directory that contains this Dockerfile: |
| |
| $ docker image build -t guacamole/manual . |
| |
| Run the resulting container using the following command: |
| |
| $ docker container run -p 8080:80 guacamole/manual |
| |
| You'll see some startup messages from Apache httpd on your terminal when you |
| start up the container. Once the container is running you can then view the |
| HTML version of the manual by accessing http://localhost:8080 using your web |
| browser. |
| |
| If another process on the host is already using port 8080, you will need to |
| change the corresponding argument in the command used to start the container. |
| |
| As a developer working on the documentation, it will be necessary to stop the |
| container and run the build again each time you wish to see changes you've |
| made to the documentation source. |
| |
| By default, the container image will contain only the HTML variant of the |
| Guacamole user manual. If you also wish to serve the PDF variant, use the |
| following command to build container image |
| |
| $ docker image build --build-arg TARGET=all -t guacamole/manual . |
| |
| You can view the PDF variant of the manual by accessing |
| http://localhost:8080/gug.pdf using your web browser. |
| |
| |
| ------------------------------------------------------------ |
| 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 |
| |