Hacking on GnuCash Documentation Guidelines
===========================================
This document is an introduction to hacking the GnuCash documentation.
For both reviewers and documentation writers;
Please read the following guides:
http://library.gnome.org/devel/gdp-handbook/stable/
http://library.gnome.org/devel/gdp-style-guide/stable/
Other useful references;
The following links are for further sites that can help with the
documentation and review process.
http://www.docbook.org (has a comprehensive online guide to docbook)
http://library.gnome.org/devel/hig-book/stable/ (GNOME Human Interface
Guidelines)
I suggest also subscribing to gnucash-devel, but this is not absolutely
necessary.
Reviewers;
Please check out the documentation module from the GnuCash SVN -
gnucash-docs. For those not familiar with svn, the gnucash website has a
description at http://www.gnucash.org/en/hacking.phtml The only change
to get the docs is to change the checkout gnucash to checkout
gnucash-docs. You can also start from the current docs tarball.
I think the best way of retaining comments about docs in an easy to find
way for everyone would be to use bugzilla.gnome.org to file the bugs
under documentation. This can also be done using bug-buddy.
Writers;
Also checkout the docs svn as above. The usual procedure for
contributors to GnuCash is to initially submit patches to the
gnucash-patches mailing list, though I will also accept patches
submitted to me directly. I will handle getting the patches added into
SVN. You can also add the patch to a bug report in bugzilla if you wish.
I would like writers to also let other know their intentions of which
section they wish to tackle. Please forward this to gnucash-devel so
that people can say 'hey I'm doing that already' or some such.
You may also want to retail a local copy of the old documentation to
refer to when writing. This still has a lot of useful information in it
which hasn't been transferred to the new docs.
NOTE: The id used in the <chapter> and <sect1> tags are important as they define
the name used when the html pages are generated. Please be careful with these.
<chapter> and <sect1> tags are also used to create the sidebar index in yelp
and are an important bonus to ease-of-use of the final documentation.
Chris Lyttle
28th May 2006
--------------------
SGML tweaks;
There are a couple of common tweaks in the XML files to allow SGML tools to
operate - for PDF generation. The tweaks are minor but common (and to those
familiar with XML a touch bizarre / annoying). If necessary, I can add a
Perl script to do the syntax changes automatically, but for now these are
the changes:
1. Avoid using the XML empty tag, specify the closing tag.
e.g. <para></para> instead of </para />
2. Avoid a newline after <entry> tags.
e.g. <entry><para> instead of <entry>\n<para>
3. Avoid underscores in id attribute values.
e.g. id="getting-started" instead of id="getting_started"
5. Use <chapter> and <sect1>.
These are minor and don't affect the normal XML content in any way.
(OK, the loss of < /> adds some extra characters.) However, the problem
with these is the sheer number of tags that use the pre-tweaked syntax.
SGML tools can deal with small numbers of these errors (commonly <200),
so this is an advisory. If you're editing the XML, please consider this
advice and make my life a little easier when it comes to PDF's.
Thanks.
Neil Williams
<linux@codehelp.co.uk>
9th March 2005.
--------------------
Generating PDF
The GnuCash documentation build system can generate pdfs from the
guide's and help manual's xml source files, provided you have the proper
tools available on your system. This functionality was introduced by
Tom Browder (<tom.browder@gmail.com>) and improved by
Geert Janssens (<janssens-geert@telenet.be>).
Other than xsltproc (which is already required to build html documentation)
you also need Apache fop 0.95 or more recent.
At the time of this writing, you can install fop straight from any of the
current distros' package repositories, or at least fop is available in one
of the addon repositories.
* Fedora 12 and up: fop is in the main repository
* Debian Lenny: fop 0.95 has been backported
* Debian Squeeze and up: fop is in the main repository
* CentOS 5: fop can be installed via EPEL testing
* Ubuntu 9.10 and up: fop is in the universe repository
If your distro doesn't ship fop you can still install it manually. It
is available at http://xmlgraphics.apache.org/fop
and it requires:
a. Sun Java JDK >= 1.4
available at: http://java.sun.com/javase/downloads/index.jsp
(I chose the "JDK 6 Update 7" download.)
b. ant >= 1.7
available at: http://ant.apache.org
