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