############################################################
GnuCash Docs 2.0.x README file.
------------------------------------------------------------
This is the docs module for GnuCash. The docs can be accessed
from Yelp (the GNOME2 help browser) directly without any conversion.
If you wish to obtain a copy of the documentation in another format,
like html, pdf or others, see below under Other Formats.
Requirements
############
* libxml2/libxslt
* docbook-xsl
* scrollkeeper >=0.3.4
* yelp (for viewing)
Additonal Requirements for Generating PDF:
* Apache fop >= 0.95
Notes
#####
The GnuCash docs team is actively seeking contributors. Even if you
only have time for reviewing or editing the existing docs this can
help. PLEASE let me know via the gnucash-devel mailing list what
you can work on or help with.
This release of the docs module only uses the docbook-xsl stylesheets
to convert the docs to html. This uses stylesheets are part of this
distribution. You still need, however, a working docbook-xsl setup to
build and install these docs.
Other Formats
#############
GnuCash-docs is written using docbook-xml. This allows it to be
outputted to alternative formats using external tools.
DocBook comes in two flavours - xml and sgml. GnuCash uses the xml flavour.
The documentation source comes with built-in commands to generate html or
pdf output. For other formats, you will need to use external tools.
Note: if you use external tools to render HTML, remember to bring the images
from figures/ along with the final HTML. The browser will expect to find
the figures/ directory directly beneath the HTML directory:
~/gnucash-docs/html/
~/gnucash-docs/html/figures/
* html and pdf
--------------
You can generate the documentation in html or pdf using the autotools
based build system that comes with the sources.
cd gnucash-docs
./autogen.sh
./configure
=> This will tell you if you are missing some required tools.
To generate the documentation in html format, run
make html
To generate the documentation in pdf format, instead run
make pdf
If you only wish to generate a subset of the documentation, you can
go into the directory for that subset and run the above make commands
from there. For example to only generate the English concepts guide,
cd guide/C
make html
or
cd guide/C
make pdf
depending on the output format you require.
* XML/XSL-based tools:
----------------------
If you have xmlto installed, this can be used to convert to other formats
but problems have been experienced with PDF generation. If you output
an XML-FO format using xmlto, you could use FOP to convert to PDF - this
step requires Java. See man xmlto for more information.
Formats available with xmlto include:
dvi fo html htmlhelp html-nochunks javahelp man
pdf ps txt xhtml xhtml-nochunks
The problems with pdf apply equally to dvi AND ps output. Each gives a
long error output ending with: ! Emergency stop.
manpage output only works if manpages are outlined in the XML.
There are no manpages in gnucash-docs.
xmlto uses xsltproc - the same tool and the same stylesheets as the main
make and install.
Examples:
To convert the GnuCash Tutorial and Concepts Guide DocBook XML document
to HTML and store the resulting HTML files in a separate directory use:
cd guide/C/
xmlto -o html-dir html gnucash-guide.xml
(html-dir/ will be created if it does not already exist.)
To convert the GnuCash Help Manual DocBook XML document to a single
HTML file in the current directory use:
cd help/C/
xmlto html-nochunks gnucash-help.xml
Known Problems
##############
Please send feedback to gnucash-devel@gnucash.org for any difficulties,
hints or suggestions with the docs. There are a few known problems.
- Help documentation missing documentation for multi-currency support,
Business module and OFX import. Menu description incomplete.
- Guide needs some updates still.
That's it for now! Please report any problems to the GNOME bugzilla at
http://bugzilla.gnome.org. Or alternately email me or preferably the
devel list with any problems you have.
Thanks
Chris Lyttle
<chris@wilddev.net>
