README

############################################################
              GnuCash Docs README file
------------------------------------------------------------

This is the user documentation (docs) module for GnuCash. Written in
DocBook v4.5 (not 5.x series) they can be accessed under
* directly without any conversion:
** Linux: from Yelp (the Gnome help browser)

* after conversion:
** MacOs: html
** Windows: chm
** mobiles: mobi
** eBook readers: epub
** paper: pdf

If you wish to obtain a copy of the documentation in one of the latter formats,
see below under Other Formats.

Requirements
############
* cmake with
** ninja or
** make

* libxml2
* libxslt [Debian packed the required xsltproc in a separate package, 
           which depends on libxslt]
* docbook-xsl
* docbook-dtds
* yelp (for viewing)

Optional for translators:
* gnome-doc-utils (contains xml2po for the use of po editors like in the italian translation)

Additional Requirements for Generating Mobipocket:

* Calibre (https://www.calibre-ebook.com/)

Additional Requirements for Generating chm on Windows:

* MSYS2 (https://www.msys2.org/)
** MinGW32 or MinGW64
** cmake on MinGW32 or MinGW64 (not cmake for MSYS2)
** libxsl on MinGW32 or MinGW64 (not libxsl for MSYS2)
** docbook-xsl on MinGW32 or MinGW64 (not docbook-xsl for MSYS2)
* HTML Help Workshop (https://www.microsoft.com/en-us/download/details.aspx?id=21138 for Win XP - 8)
Microsoft stopped providing HTML Help Workshop installer files. You can download from WayBack Machine instead.
https://web.archive.org/web/20110712222004/http://msdn.microsoft.com:80/en-us/library/ms669985

They are installed by windows bootstrap scripts for GnuCash except HTML Help Workshop. See
  https://github.com/Gnucash/gnucash-on-windows/
for details.

Additonal Requirements for Generating PDF:

* Apache fop  >= 0.95

** FontBox
  from the Apache PDFBox [https://pdfbox.apache.org/download.cgi]
  can handle OpenType fonts, which are as default used for the russian PDF.
  Some distributions call it [lib]fontbox[-java].

Notes
#####

The GnuCash docs team is actively seeking contributors. Even if you
only have time for reviewing, editing or translating the existing docs this
can help. PLEASE let us know via IRC or the gnucash-devel mailing list what
you can work on or help with.

See also:
* https://wiki.gnucash.org/wiki/Documentation_Update_Instructions
* https://wiki.gnucash.org/wiki/Translation

Other Formats
#############

GnuCash-docs is written using docbook-xml. This allows it to be
outputted to alternative formats using external tools.

The documentation source can be converted into HTML, PDF, EPUB, or MOBI
format using such tools as xsltproc and fop.


Note: if you use external tools to render HTML, remember to bring the images
from figures and icons along with the final HTML. The browser will expect to find
the figures and images directory directly beneath the HTML directory as follows:
/path_to/gnucash-docs/html/
/path_to/gnucash-docs/html/figures/
/path_to/gnucash-docs/html/images/

--------------------------

You can generate the documentation in html, pdf, epub and mobi
using the build system that comes with the sources.

For cmake the commands are
  cd gnucash-docs
  mkdir build && cd build
  # If you don't need mobi
  cmake [options…]
  # or, if you need mobi
  cmake -DWITH_MOBI=ON [options…]

To generate the documentation in html format, run

  make html

To generate the documentation in pdf format, instead run

  make pdf

To generate the documentation in epub format, instead run

  make epub

To generate the documentation in mobi format, instead run

  make mobi
  (Note: mobi is generated from epub, so this generates epub files as well.)

If you only wish to generate a subset of the documentation, you can. However
the way to do so depends on the build system:

There are specific targets for each document. The target is of the form
<language>-<doc>-<type>.

For example to only generate the English concepts guide:

  make C-guide-html
  make C-guide-pdf
  make C-guide-epub
  make C-guide-mobi

depending on the output format you require.

In addition one could generate all documents in these formats for one language
at once by omitting the document specifier in the target.

For example:

  make C-html

will generate the html version of all documents in English. At the time of
writing this, there are two documents in English, namely guide and manual
so these two will be built.

* Running syntax checks by xmllint
-----------------
You can also run xmllint on all documents or a specific document with the command

  make check # for toplevel check
  make de-manual-check # for a cmake check for one specific document
                       # in this example - the German help manual

* 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 C/guide/
xmlto -o html-dir html index.docbook

(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 C/manual/
xmlto html-nochunks index.docbook


Known Problems
##############

- See the full list: 
https://bugs.gnucash.org/buglist.cgi?quicksearch=product%3DDocumentation

- Please report any new problems to Gnucash's Bugzilla at 
https://bugs.gnucash.org/describecomponents.cgi?product=Documentation. Then
choose a component.

- Feel free to append your fixes and improvements also there or open a pull
request. Only docs about future features should go in branch master.
So here is the link for branch stable:
https://github.com/Gnucash/gnucash-docs/.

- With any problems you have, you can contact us in the following ways:

* quick questions via IRC
** en: irc://irc.gimp.net/gnucash 
: see https://wiki.gnucash.org/wiki/IRC

* translation related questions preferable via the local mailing lists
** de: https://lists.gnucash.org/mailman/listinfo/gnucash-de
** es: https://lists.gnucash.org/mailman/listinfo/gnucash-es
** fr: https://lists.gnucash.org/mailman/listinfo/gnucash-fr
** it: https://lists.gnucash.org/mailman/listinfo/gnucash-it
** nl: https://lists.gnucash.org/mailman/listinfo/gnucash-nl
** pt: https://lists.gnucash.org/mailman/listinfo/gnucash-br
: or your recent translator

* other user questions should go to
** en: https://lists.gnucash.org/mailman/listinfo/gnucash-user

* finally contributor questions via
** en: https://lists.gnucash.org/mailman/listinfo/gnucash-devel

Thanks
your GnuCash Documentation Team


Original Author: 
Chris Lyttle
<chris@wilddev.net>