forked from Gnucash/gnucash-htdocs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
develdocs.phtml
87 lines (74 loc) · 7.62 KB
/
develdocs.phtml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
<?php
include("lang.php");
$title = T_("Writing Documentation");
include("emulate_globals_on.php");
include("externals/header.phtml");
include("externals/menu.phtml");
?>
<div id="content">
<h1><?php echo T_("Writing GnuCash Documentation");?></h1>
<p class="justify"><?php echo 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.");?></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>GNOME2 XML 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='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://library.gnome.org/devel/hig-book/stable/'> GNOME Human Interface Guidelines</a></li>
<li><a href='http://wiki.gnucash.org/wiki/Translation#How_to_translate_the_GnuCash_guide_and.2For_help_files'>How_to_translate_the_GnuCash_guide_and/or_help_files</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='http://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 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://library.gnome.org/devel/gdp-handbook/stable/'>The GNOME Handbook of Writing Software Documentation</a></li>
<li><a href='http://library.gnome.org/devel/gdp-style-guide/stable/'>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='http://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='http://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 documentation component for the <span class=\"gnucash\">GnuCash</span> project in <a href='http://bugzilla.gnome.org/'>Gnome's bugzilla database</a> and send an email to <a href='mailto:gnucash-devel@gnucash.org'>gnucash-devel</a> mailing list to inform other developers on your work. See also <a href='http://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='http://bugzilla.gnome.org/'>bugzilla.gnome.org</a> to file the bugs under documentation. This can also be done using bug-buddy.");?></p>
</div>
</div>
<?php include("externals/footer.phtml"); ?>