develdocs.phtml

<?php 
include("emulate_globals_on.php");
include("lang.php");
$title = T_("Writing Documentation");
$description = T_("If you are interested in improving the <span class=\"gnucash\">GnuCash</span> documentation, you have come to the right place. This page will provide you with the necessary information to get started.");
$page = $_SERVER['PHP_SELF'];
include("externals/header.phtml");
include("externals/menu.phtml");
?>

<div id="content">

<h1><?php echo T_("Writing GnuCash Documentation");?></h1>

<p class="justify"><?=$description?></p>

<p class="justify"><?php echo T_("Just as the <span class=\"gnucash\">GnuCash</span> application has been developed over time by volunteers, so too has the documentation been written by volunteer developers and users to help others learn how <span class=\"gnucash\">GnuCash</span> works. This collaborative effort has resulted in the creation of two major documents, the <b>Help Manual</b> and the <b>Tutorial and Concepts Guide</b>.");?></p>

<p class="justify"><?php echo T_("The <span class=\"gnucash\">GnuCash</span> community welcomes assistance in maintaining and improving both the program and its documentation. If you are interested in helping write, edit or translate <span class=\"gnucash\">GnuCash</span>'s documentation, this page gives guidance on how to get set up to join the effort.");?></p>

<div class="dialog note">
<p class="justify"><?php echo T_("The <span class=\"gnucash\">GnuCash</span> documentation can be viewed and downloaded from the <a href=\"docs.phtml\">Documentation page</a>.");?></p>
</div>

<div class="featurecontainer">
<div class="featureborder">
<h2 class="featuretitle"><?php echo T_("Introduction");?></h2>
</div>
<p class="justify"><?php echo T_("The <span class=\"gnucash\">GnuCash</span> documentation is stored in <b>xml</b> files. More precisely, it uses the <b>docbook system</b>. 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 class="justify"><?php echo T_("If you wish to review or write <span class=\"gnucash\">GnuCash</span> documentation, you will need to know xml. Some basic knowledge of the docbook system may be useful as well.");?></p>
<p class="justify"><?php echo T_("The following links are for further sites that can help with the documentation and review process.");?></p>
<ul>
<li><a href='https://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='https://library.gnome.org/devel/hig-book/stable/'> GNOME Human Interface Guidelines</a></li>
<li><a href='https://wiki.gnucash.org/wiki/Translation#Translating_the_GnuCash_Guide_and_Help'>Translating_the_GnuCash_Guide_and_Help</a>: <?php echo T_("While this <span class=\"gnucash\">GnuCash</span> wiki page is really about translating the documentation, it holds some useful information on working with docbook files.");?></li>
<li><a href='https://wiki.gnucash.org/wiki/Documentation_Update_Instructions'> Documentation_Update_Instructions</a>: <?php echo T_("A detailed guide on how to work with documentation (update and maintenance).");?></li>
</ul>
<p class="justify"><?php echo T_("We suggest also subscribing to");?> <a href='mailto:gnucash-devel@gnucash.org'>gnucash-devel</a>.</p>
</div>

<div class="featurecontainer">
<div class="featureborder">
<h2 class="featuretitle"><?php echo T_("Gnome Documentation guidelines");?></h2>
</div>
<p class="justify"><?php echo T_("As stated earlier, the new docs are based on the docbook system. Everyone wishing to help please follow these guides where possible when reviewing and/or writing docs.");?></p>
<ul> <!-- with Gnome 3 the next disappeared -->
<li><del><a href='https://library.gnome.org/devel/gdp-handbook/stable/'>The GNOME Handbook of Writing Software Documentation</a></del> <?php echo T_("No longer available") ?></li>
<li><a href='https://developer.gnome.org/gdp-style-guide/'>The GNOME Documentation Style Guide</a></li>
</ul>
</div>

<div class="featurecontainer">
<div class="featureborder">
<h2 class="featuretitle"><?php echo T_("Where to get the documentation source");?></h2>
</div>
<p class="justify"><?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-docs git repository. Reviewers could also start from the <a href='https://sourceforge.net/projects/gnucash/files/gnucash-docs/'>current docs tarball</a>.");?></p>
<p class="justify"><?php echo T_("For those not familiar with git, the <span class=\"gnucash\">GnuCash</span> wiki has a <a href='https://wiki.gnucash.org/wiki/Git'>description</a> tailored to the <span class=\"gnucash\">GnuCash</span> code. To get the documentation source instead of the program source, replace 'gnucash' with 'gnucash-docs' in the mentioned git commands, like this:");?></p>
<pre class="command">git clone https://github.com/Gnucash/gnucash-docs.git</pre>
<div class="dialog note">
<p class="justify"><?php echo T_("There are two major <span class=\"gnucash\">GnuCash</span> documentation packages to help users: the <b>Help Manual</b> and the <b>Tutorial and Concepts Guide</b>. With the above command, the source code of both will be downloaded.");?></p>
</div>
</div>

<div class="featurecontainer">
<div class="featureborder">
<h2 class="featuretitle"><?php echo T_("Writers");?></h2>
</div>
<p class="justify"><?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 class="command">git diff > my-patch-name.patch</pre>
<p class="justify"><?php echo T_("Next attach your patch to a bug report against the proper component for the Documentation product in <a href='https://bugs.gnucash.org/'><span class=\"gnucash\">GnuCash</span>' bug database</a>. See also <a href='https://wiki.gnucash.org/wiki/Bugzilla'>GnuCash' wiki page on bugzilla</a> for more details about patch submission.");?></p>
<div class="dialog note">
<p class="justify"><?php echo T_("<b>NOTE:</b> It used to be ok also to send your patch directly to the gnucash-devel list. This is discouraged now, as a patch is easily forgotten between the many list discussions. Attach patches to bugs in Bugzilla instead (either an existing bug or a new one). If you insist on sending a patch to gnucash-devel, it should be attached, not inlined.");?></p>
<p class="justify"><?php echo T_("Please let other writers know which section you wish to tackle. Please forward this to <a href='mailto:gnucash-devel@gnucash.org'>gnucash-devel</a> so that people can say 'hey I'm doing that already' or 'go ahead and do it'.");?></p>
<p class="justify"><?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>
</div>
</div>

<div class="featurecontainer">
<div class="featureborder">
<h2 class="featuretitle"><?php echo T_("Reviewers");?></h2>
</div>   
<p class="justify"><?php echo T_("Get a copy of the documentation source as described above and start commenting on it.");?></p>
<p class="justify"><?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='https://bugs.gnucash.org/'>bugs.gnucash.org</a> to file the bugs under documentation. This can also be done using bug-buddy.");?></p>
</div>

</div>

<?php include("externals/footer.phtml"); ?>