############################################################
          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). If you wish an html version
'make html' will convert them for you and leave the html files in
a subdirectory of the doc called <docname> (eg the html for help 
would be in help/C/gnucash-help).

Requirements
############

libxml2/libxslt
docbook-xsl
scrollkeeper >=0.3.4
yelp (for viewing)

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.

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/

		================================

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

		==============================

SGML-based tools:
----------------

(Note these tools and the sgml docs are no longer being updated)
If you have docbook-utils installed, you can convert this documentation
into other formats like PDF, DVI, TXT, texi, RTF. docbook-utils is SGML
based and so a SGML header file is provided. The content files are still
XML based - this doesn't cause problems for conversion to HTML but to
generate PDF's validity errors need to be suppressed. 

Use -e no-valid to suppress SGML validity errors.

Currently, there are also problems incorporating the images into the 
PDF versions. However, unlike the XML/XSL tools, docbook-utils will 
generate a valid PDF, albeit without images.

Note that the docs are designed for XML/XSL. Allowing them to function
with SGML tools requires a few syntax tweaks. You may get errors reported
but as long as the majority of the tweaks are in place, the conversion
will succeed. Syntax errors are not suppressed with '-e -no-valid',
only validity errors (like _ instead of - in id attributes).

Examples:
---------
Convert the GnuCash guide to a single HTML file:
cd guide/C/
docbook2html -e no-valid -u gnucash-guide.sgml
cd help/C/
docbook2html -u gnucash-help.sgml

Convert the GnuCash guide into a PDF:
cd guide/C/
docbook2pdf -e no-valid gnucash-guide.sgml

Convert the GnuCash Help Manual into DVI:
cd help/C/
docbook2dvi -e no-valid gnucash-help.sgml

One workaround for the images is to convert to a single HTML file and
use Print to PDF File from your web browser. Bear in mind that the single
HTML file is v.large and each PDF, without images, goes to over 100 pages.


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.

- Most of the information (although still relevant) refers to the 1.8 version.

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>

