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. The Handbook is a bit outdated right now as it refers to writing SGML based documentation and I have moved the new docs to the GNOME2 XML docbook based system.Its basic structure is still relevant, however. I would like everyone wishing to help to follow these guides where possible when reviewing and/or writing docs. http://developer.gnome.org/projects/gdp/styleguide.html http://developer.gnome.org/projects/gdp/handbook.html 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://developer.gnome.org/projects/gup/hig/1.0/ (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.