r19340 - htdocs/trunk - Clarify the section on documentation writing

Geert Janssens gjanssens at code.gnucash.org
Wed Jul 7 07:56:41 EDT 2010


Author: gjanssens
Date: 2010-07-07 07:56:41 -0400 (Wed, 07 Jul 2010)
New Revision: 19340
Trac: http://svn.gnucash.org/trac/changeset/19340

Modified:
   htdocs/trunk/docs.phtml
Log:
Clarify the section on documentation writing

Modified: htdocs/trunk/docs.phtml
===================================================================
--- htdocs/trunk/docs.phtml	2010-07-06 16:52:44 UTC (rev 19339)
+++ htdocs/trunk/docs.phtml	2010-07-07 11:56:41 UTC (rev 19340)
@@ -88,31 +88,40 @@
 
 <h2><?php echo T_("Documentation Development");?></h2>
 
-<h3><?php echo T_("Interesting Links");?></h3>
-<?php echo T_("The following links are for further sites that can help with the documentation and review process.");?>
+<h3><?php echo T_("Introduction");?></h3>
+<p><?php echo T_("The GnuCash documentation is stored in xml files. More precisely, it uses the GNOME2 XML docbook system. This is a relatively flexible system that takes xml files as input and can generate documentation in several different output formats (html, pdf,...).");?></p>
+<p><?php echo T_("If you wish to review or write GnuCash documentation, you will need to know xml. Some basic knowledge of the docbook system may be useful as well");?></p>
+<p><?php echo T_("The following links are for further sites that can help with the documentation and review process.");?>
 <ul>
 <li><a href='http://www.docbook.org'> DocBook: The Definitive Guide.</a></li>
 <li><a href='http://www.sagehill.net/docbookxsl/'>DocBook XSL: The Complete Guide</a>.</li>
 <li><a href='http://developer.gnome.org/projects/gup/hig/2.0/'> GNOME Human Interface Guidelines</a></li>
-</ul>
+</ul></p>
+<p><?php echo T_("We suggest also subscribing to ");?><a href='mailto:gnucash-devel at lists.gnucash.org'>gnucash-devel</a>.</p>
 
-<h3><?php echo T_("For both reviewers and documentation writers");?></h3>
-<?php echo T_("Please read the following guides. The new docs are based on the GNOME2 XML docbook system. Everyone wishing to help please follow these guides where possible when reviewing and/or writing docs.");?></p>
+<h3><?php echo T_("Gnome Documentation guidelines");?></h3>
+<?php echo T_("As stated earlier, the new docs are based on the GNOME2 XML docbook system. Everyone wishing to help please follow these guides where possible when reviewing and/or writing docs.");?></p>
 <ul>
 <li><a href='http://developer.gnome.org/projects/gdp/styleguide.html'>The GNOME Documentation Style Guide</a></li>
 <li><a href='http://developer.gnome.org/projects/gdp/handbook.html'>The GNOME Handbook of Writing Software Documentation</a></li>
 </ul>
-<p><?php echo T_("We suggest also subscribing to ");?><a href='mailto:gnucash-devel at lists.gnucash.org'>gnucash-devel</a>.</p>
 
-<h3><?php echo T_("Reviewers");?></h3>
-<p><?php echo T_("Please check out the documentation module from the GnuCash svn - gnucash-docs. For those not familiar with svn, the GnuCash wiki has a <a href='http://wiki.gnucash.org/wiki/Subversion'>description.</a> 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.");?></p>
-<p><?php echo T_("The best way of retaining comments about docs in an easy to find way for everyone would be to use <a href='http://bugzilla.gnome.org/'>bugzilla.gnome.org</a> to file the bugs under documentation. This can also be done using bug-buddy.");?></p>
+<h3><?php echo T_("Where to get the documentation source");?></h3>
+<p><?php echo T_("You will need a recent copy of the documentation source. For this you can check out the documentation module from the GnuCash svn. Reviewers could also start from the <a href='http://sourceforge.net/projects/gnucash/files/gnucash-docs/'>current docs tarball</a>.");?></p>
+<p><?php echo T_("For those not familiar with svn, the GnuCash wiki has a <a href='http://wiki.gnucash.org/wiki/Subversion'>description</a> tailored to the GnuCash code. To get the documentation source instead of the program source, replace 'gnucash' with 'gnucash-docs' in the mentioned svn commands, like this:");?></p>
+<pre>svn checkout http://svn.gnucash.org/repo/gnucash-docs/trunk gnucash-docs</pre>
 
 <h3><?php echo T_("Writers");?></h3>
-<p><?php echo T_("Also checkout the docs svn as above. The usual procedure for contributors to GnuCash is to initially submit patches to the <a href='mailto:gnucash-devel at lists.gnucash.org'>gnucash-devel</a> mailing list. We will handle getting the patches added into svn until you are given an account. You can also add the patch to a bug report in bugzilla if you wish.");?></p>
+<p><?php echo T_("Get a copy of the documentation source as described above and start making changes. When you are satisfied with your changes you can create a patch by running the following command in the base directory of the documentation (usually gnucash-docs, unless you renamed it:");?></p>
+<pre>svn diff > my-patch-name.patch</pre>
+<p><?php echo T_("The usual procedure for contributors to GnuCash is to initially submit patches to the <a href='mailto:gnucash-devel at lists.gnucash.org'>gnucash-devel</a> mailing list. We will handle getting the patches added into svn until you are given an account. You can also add the patch to a bug report in <a href='http://bugzilla.gnome.org/'>bugzilla.gnome.org</a> if you wish.");?></p>
 <p><?php echo T_("Please let other writers know which section you wish to tackle. Please forward this to <a href='mailto:gnucash-devel at lists.gnucash.org'>gnucash-devel</a> so that people can say 'hey I'm doing that already' or 'go ahead and do it'.");?></p>
 <p><?php echo T_("You may also want to retain 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");?></p>
     
+<h3><?php echo T_("Reviewers");?></h3>
+<p><?php echo T_("Get a copy of the documentation source as described above and start commenting on it.");?></p>
+<p><?php echo T_("The best way of retaining comments about docs in an easy to find way for everyone would be to use <a href='http://bugzilla.gnome.org/'>bugzilla.gnome.org</a> to file the bugs under documentation. This can also be done using bug-buddy.");?></p>
+
 </div>
 <?php include("externals/footer.phtml"); ?>
 



More information about the gnucash-changes mailing list