README

------------------------------------------------------------
 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