blob: c021f8da5d4398fd3e8acf18549fef6fa58ec00a [file] [log] [blame]
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:
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:
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:
$ 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
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: