Difference between revisions of "Documentation Improvement"

From GnuCash
Jump to: navigation, search
(Step 8 Proofread in HTML - remove duplication)
(Background Overview)
(25 intermediate revisions by 6 users not shown)
Line 1: Line 1:
'''''[Due to the the width of browser pages, all readers are invited to adjust page width to reading comfort by installing this free tool: "http:// lab dot arc90 dot com/experiments/readability/"]'''''
 
 
 
''These instructions describe the process to change both the GnuCash "Guide"  
 
''These instructions describe the process to change both the GnuCash "Guide"  
 
and the GnuCash "Help" manuals as well as any other parts of GnuCash documentation. If you are interested in translating the documentation, you should read [[Translation#How_to_translate_the_GnuCash_guide_and.2For_help_files]], too.''
 
and the GnuCash "Help" manuals as well as any other parts of GnuCash documentation. If you are interested in translating the documentation, you should read [[Translation#How_to_translate_the_GnuCash_guide_and.2For_help_files]], too.''
Line 6: Line 4:
 
==Preface and Introduction -- What to expect==
 
==Preface and Introduction -- What to expect==
  
The recommendation of experienced programmers who work with code and related documentation is to ''obtain a copy of the full set of the most recent documentation''. Nightly builds can be seen at [http://svn.gnucash.org/docs/ http://svn.gnucash.org/docs/]. Besides having the modules you think you will need to change, you will easily be able to update other files, if you discover additional places requiring a modification.
+
The material in the documentation set uses the same software management tools that are used for the program itself. This ensures that changes are made consistently and reliably. It does, however, require that documentation contributors learn and use several tools to engage the process. The tools and the process are outlined in this page.
 +
 
 +
===Background Overview===
 +
 
 +
To set up, you will ''obtain a copy of the full set of the most recent documentation''. You can obtain a full set using the version control system git (see below). Once you have all the documentation you can make changes in any part of the documents that might need them. The most current documents can be seen at [http://code.gnucash.org/docs/ http://code.gnucash.org/docs/].  
  
In addition, other persons could be making changes to parts of the documentation at the same time you are.  You will need to make sure any changes (others have made following your acquiring a set of the documentation) are included in what you will install.
+
Since others could be making changes to the documentation at the same time you are, you will need to make sure that any changes that others have made in the interim are included in what you will install. The version control system git is used to ensure that everyone's changes can be incorporated efficiently into one final set of source files.
  
After obtaining your full set of the documentation, you will be ''inserting your modifications'' into the proper places in the set of documents. Modules in the set are formatted using XML. Later in processing, the XML modules are converted to HTML versions for online easy viewing. As a documentation support person, your task is to shepherd your enhancements through all stages from start to finish.
+
Any changes you make will be inserted into your local copies of the source documentation files. These source files use a special markup in XML to provide structure. Later in the process, the XML files are converted to other versions (HTML, PDF, etc.) for viewing. As a documentation support person, your task is to shepherd your modifications through all stages from start to finish.
  
At each stage ''changes must be validated'' to assure that intended changes occur, and other unexpected changes found are understood and either accepted or rejected after proper analysis.
+
At each stage, you must validate your changes to assure that they are both valid and have the intended effect, and you must address any errors or unexpected changes that are found.
  
 
Since your changes will be carried out by software, there is a difference determination process that identifies exactly what and where changes will be made.  This process permits you to be sure that only what you intend will actually be installed.
 
Since your changes will be carried out by software, there is a difference determination process that identifies exactly what and where changes will be made.  This process permits you to be sure that only what you intend will actually be installed.
  
For the sake of quality control there is a ''review process'' that you must use in order to make your change "official".  The above brief description when executed results in a file of changes.  These changes must be explained as to their purpose.  Accompanying the explanation in words is everything that makes up the substance of the change.  The term for this is "patch".  Whether you introduce a major restructuring or a small tweak, every thing is a "patch".
+
For the sake of quality control there is a review process that you must use in order to make your change official.   
 +
 
 +
The above brief description when executed results in a file of changes.  These changes must be explained as to their purpose.  Accompanying the explanation in words is everything that makes up the substance of the change.  The term for this is "patch".  Whether you introduce a major restructuring or a small tweak, every thing is a "patch".
  
 
Creation of the explanation and the content of the change you are making are combined in a ''bugzilla'' event, otherwise called a "bug".  In this usage bug means a statement of what is changing and why along with the content that will be the change when approved and applied to all the places needed.  It does not necessarily mean a problem is being corrected, enhancements are handled as bugs too.
 
Creation of the explanation and the content of the change you are making are combined in a ''bugzilla'' event, otherwise called a "bug".  In this usage bug means a statement of what is changing and why along with the content that will be the change when approved and applied to all the places needed.  It does not necessarily mean a problem is being corrected, enhancements are handled as bugs too.
Line 25: Line 29:
 
   
 
   
 
As your first act in getting started, become very familiar with the references given in the [[Documentation_Update_Instructions#References_to_Supporting_Technologies_Used|REFERENCES]] section below.
 
As your first act in getting started, become very familiar with the references given in the [[Documentation_Update_Instructions#References_to_Supporting_Technologies_Used|REFERENCES]] section below.
 +
 +
==The Make Utility==
 +
Like the programs, the documentation is built using the '''make''' utility.
 +
 +
In the ''make'' build system there are three important directories:
 +
* the source directory
 +
* the build directory
 +
* the installation directory (which can also be more than one directory all under a special directory called the prefix-directory)
 +
 +
The ''source'' directory is where your source files are. I.e. '''gnucash-docs''' (the clone of our github repository) with all its subdirectories on your system for documentation. If you want to make changes to the documentation source, you do this in the source directory structure, not the build directory structure.
 +
 +
The ''build'' directory is a directory used by the build system to store all files/objects that are generated by the build system. '''make''' is always executed in the build directory or a sub-directory of the build directory. Each make ''recipe'' results in at least one such file or object.
 +
 +
The ''installation'' directory is the location where the generated objects should finally end up when using ''make install''.
 +
 +
For the GnuCash documentation, the make command ''must'' be used with a ''target'' argument which determines which type(s) of the documentation are built. E.g. '''make html''' builds the html files which allow the documentation to be viewed in a web browser. (If no target is specified, make does nothing because the xml files are both the source and the target which yelp needs to display the documentation.) What '''make''' actually does is specified in the contents of make files. These are files called '''Makefile''' (or '''Makefile.am''') and exist in multiple directories of the documentation repository. What they do depends on which directory is current when the ''make'' command is executed. In general, the lower down the build directory tree, the more specific the scope. By changing the current directory, ''make'' can build:
 +
* Both the Help & Guide
 +
* Either the Help or Guide
 +
* Just the Help or Guide for a specific language
 +
As building the documentation can take a while, it is best to only build what is needed for your changes.
 +
 +
Typical '''targets''' of the ''make target'' command used for the documentation are:
 +
  make check                # use xmllint to validate xml files
 +
  make html                # use xsltproc to build the html (web browser) documentation
 +
  make pdf                  # use xsltproc to build the pdf documentation
 +
  make mobi                # use xsltproc to build the mobi documentation
 +
  make epub                # use xsltproc to build the mobi documentation
 +
There are additional installation dependencies required for building the pdf and mobi formats.
 +
See [http://wiki.gnucash.org/wiki/Documentation_Release_Process#Other_documentation_formats].
 +
 +
To install the built documentation where it can be used for testing the interaction with GnuCash programs:
 +
  make install              # See [[#Step 11 Test Documentation in Linux]].
  
 
==The Documentation Change Process -- What and How it happens==
 
==The Documentation Change Process -- What and How it happens==
Line 31: Line 67:
  
 
'''N.B.:''' The instructions below are for a non-committer preparing a patch. If you have commit privileges in the gnucash-docs repository, the git commands you use will be somewhat different. Please see [[Git]]. If you're not familiar with using git, you'll find more details on basic commands and links to documentation there as well. You may prefer one of the many Git GUIs to the command-line instructions here, especially if you use Microsoft Windows.
 
'''N.B.:''' The instructions below are for a non-committer preparing a patch. If you have commit privileges in the gnucash-docs repository, the git commands you use will be somewhat different. Please see [[Git]]. If you're not familiar with using git, you'll find more details on basic commands and links to documentation there as well. You may prefer one of the many Git GUIs to the command-line instructions here, especially if you use Microsoft Windows.
 +
  
 
===Step 1 Create a Bugzilla Bug for the Documentation Change===
 
===Step 1 Create a Bugzilla Bug for the Documentation Change===
Line 46: Line 83:
  
 
===Step 2 Git Clone===
 
===Step 2 Git Clone===
Use this command exactly as written to download a full set of documentation files from [https://github.com github] to your own computer .
+
If you are new to using git, you may find it useful to read [[Git_For_Newbies]] for more information about specific git commands, how they are used in the process of modifying GnuCash, and how to submit changes for review using pull requests (preferred) instead of patches. If you already familiar with git, The [[Git]] page may be more suitable.
<pre>git clone https://github.com/Gnucash/gnucash-docs gnucash-docs</pre> The terminal command will cause the documentation to be copied to your computer under the name you specify in the command. <br /> Executing the command assumes that [https://github.com git] has previously been installed successfully on your computer. <br /> If the system finds that git is not installed, it ignores your request. Linux will then reply with the correct command to download and install the package, while Windows will say something like:
+
 
:'git' is not recognized as an internal or external command, operable program or batch file.
+
For simplicity, this page assumes the local repository will be in folder /home/$USER/code/gnucash-docs, but it can be wherever the user prefers.
If you need to install git with a Linux package manager, make note of the module(s) that it tells you should be deleted.  Also, note the command it provides to delete such module(s).  Next install git with the install command given.  Note any instructions given during the install process and carry them out.  Finally, use the instruction first noted that tells you what module(s) to remove and carry out the remove instruction. <br /><br /> In the git command "gnucash-docs" is the directory name where the checkout process places the full set of documentation modules.  You can use that name or some other.  Remember that the bash shell is case sensitive when typing commands and providing names. <br /> Avoid merge conflicts and merge commits by always using <pre>git pull --rebase</pre> to update your local repository. <br />  
+
  cd /home/$USER/code
 +
 
 +
Use this command exactly as written to download a full set of documentation files from [https://github.com github] to your own computer.
 +
  git clone https://github.com/Gnucash/gnucash-docs gnucash-docs
 +
The terminal command will cause the documentation to be copied to your computer under the name you specify in the command. <br /> Executing the command assumes that [https://github.com git] has previously been installed successfully on your computer. <br /> If the system finds that git is not installed, it ignores your request. Linux will then reply with the correct command to download and install the package, while Windows will say something like:
 +
:<tt>'git' is not recognized as an internal or external command, operable program or batch file.</tt>
 +
If you need to install git with a Linux package manager, make note of the module(s) that it tells you should be deleted.  Also, note the command it provides to delete such module(s).  Next install git with the install command given.  Note any instructions given during the install process and carry them out.  Finally, use the instruction first noted that tells you what module(s) to remove and carry out the remove instruction. <br /><br /> In the git command "gnucash-docs" is the directory name where the checkout process places the full set of documentation modules.  You can use that name or some other.  Remember that the bash shell is case sensitive when typing commands and providing names. <br /> Avoid merge conflicts and merge commits by always using  
 +
  git pull --rebase
 +
to update your local repository. <br />
  
===Step 3 Find Update Location===
+
===Step 3 Generate configure Script===
Find the place in the documentation that you want to change; identify the file(s) that need to be changed to accomplish your documentation objective. Your changes should roughly follow the [http://library.gnome.org/devel/gdp-style-guide/stable/ GNOME Documentation Style Guide] of the [https://live.gnome.org/DocumentationProject/ GNOME Documentation Project].
+
This step checks that various ''make'' utilities (autoconf, libtoolize & automake) are installed and builds the '''configure''' script and the '''Makefile.in''' files from the '''configure.ac''' and '''Makefile.am''' files. '''Makefile.in''' files are pseudo Makefile's used by the ''configure'' script with lots of variables that still need final setting.
 +
  cd /home/$USER/code/gnucash-docs
 +
  ./autogen.sh  # autogen.sh is *always* run in the top-level *source* directory
 +
'''autogen.sh''' is platform independent and is used to initiate the whole build system for a given project.
 +
 
 +
As a rule of thumb, autogen.sh should be run the first time you want to initialize the build system and sometimes after changes are made in configure.ac or Makefile.am files. Frequently those changes are auto detected though. Running autogen.sh when it's not necessary doesn't do harm but it will make the next build take longer.
 +
 
 +
The first time autogen.sh is run, it may complain about missing packages autoconf, libtoolize or automake. You can usually install the generic packages of the same name using your distribution's package manager. You'll probably also need to install xsltproc. For example, in Ubuntu:
 +
  sudo apt-get install autoconf libtoolize automake xsltproc
 +
 
 +
===Step 4 Make a Build Directory Structure and the Makefiles===
 +
Create a ''build'' directory structure to keep the built documentation files separate from the repository directories. This page assumes the ''build'' directory is called '''build''' and is a subdirectory of the repository but that does not have to be so. It can be called whatever suits you, and even be wherever it suits you. Some people create it as a subdirectory to the source directory. Others have it in a completely different location, say to have all builds together under one directory. That is a matter of preference.
 +
  cd /home/$USER/code/gnucash-docs
 +
  mkdir build    # only needed if not previously created
 +
  cd build      # configure must be run from the "build" directory
 +
 
 +
'''Note''': If you intend to test invoking help from GnuCash programs, you should add the '''--prefix=...''' option to the configure command below now to save having to rerun it later. See [[#Step 11 Test Documentation in Linux]].
 +
 
 +
If your build directory is a subdirectory of your repository
 +
  ../configure
 +
Otherwise (depending on where your repository is)
 +
  /home/$USER/code/gnucash-docs/configure  # or use a relative path to run your repository configure script
 +
 
 +
The ''../configure'' command above will recreate the gnucash-docs directory structure under the current directory (build) but without the source files. It then looks up the installation location for all tools and libraries used and creates the required '''Makefile'''s from the '''Makefile.in''' files. It can enable or disable certain options in the Makefiles based on its findings. ''configure'' can also take extra command line options that can alter what it will include in the Makefiles. You can see these options by running '''configure --help'''. Most of them are not relevant for us, except for the few we invented ourselves like '''--with-mobi'''.
 +
 
 +
'''configure''' must be run right after autogen.sh. Running it when not really required has no negative side-effect other than that the next build may take longer because more objects will be rebuilt.
 +
 
 +
===Step 5 Find Update Location===
 +
Find the place in the documentation that you want to change (in the repository, not the build directories); identify the file(s) that need to be changed to accomplish your documentation objective. Your changes should roughly follow the [http://library.gnome.org/devel/gdp-style-guide/stable/ GNOME Documentation Style Guide] of the [https://live.gnome.org/DocumentationProject/ GNOME Documentation Project].
  
 
This means you have to read the documentation to find exactly where  
 
This means you have to read the documentation to find exactly where  
Line 80: Line 153:
 
interested in has already had a mention or treatment.
 
interested in has already had a mention or treatment.
  
===Step 4 Draft your Update in a Text File===
+
===Step 6 Draft your Update in a Text File===
If your changes are few and easily formulated, you should be able to skip this step and proceed to [[#Step 5 - place the draft changes in XML files]].
+
If your changes are few and easily formulated, you should be able to skip this step and proceed to [[#Step 7 - place the draft changes in XML files]].
  
 
For substantive changes to the documentation it is frequently helpful to develop your ideas in a separate temporary text file. Use a text editor such as [http://www.jedit.org jEdit], which is available for both Linux and Windows operating systems. jEdit has an XML plugin so can also be used for editing XML files.  
 
For substantive changes to the documentation it is frequently helpful to develop your ideas in a separate temporary text file. Use a text editor such as [http://www.jedit.org jEdit], which is available for both Linux and Windows operating systems. jEdit has an XML plugin so can also be used for editing XML files.  
  
===Step 5 Place the Draft Changes in XML Files===
+
===Step 7 Place the Draft Changes in XML Files===
Insert your changes into the XML file(s) affected. Make your changes fit the XML tags in the manner of the existing documentation.  Adjust your XML tag structure so that the finished structure appears properly and as you intended in the HTML version of the documentation. Doing this might be easier by using a [http://www.dmoz.org/Computers/Data_Formats/Markup_Languages/XML/Tools/Editors/ specific XML Editor]. [http://sourceforge.net/projects/sernafree.mirror/ Serna-Free] is a more-or-less free [http://en.wikipedia.org/wiki/DocBook DocBook] editor which is much easier to use than a plain XML editor, but it introduces a lot of extraneous changes which must be removed before preparing a commit or patch ''You may have to return to this step should step 6 reveal a less than desirable arrangement of the data.''
+
Insert your changes into the XML file(s) affected.  
It will help translators to update their work, if you add a comment pair around your change, e.g.: <pre><!-- New in 2.6.6 (2015): --> your new or changed text <!-- End of New in 2.6.6 (2015) --></pre>
+
 
 +
Note: Edit the source files in the repository directories, not in the ''build'' directories. The various ''make'' commands (run from the build directories), will copy the files from the repository to the build directories.
 +
 
 +
Make your changes fit the XML tags in the manner of the existing documentation.  Adjust your XML tag structure so that the finished structure appears properly and as you intended in the HTML version of the documentation. Doing this might be easier by using a [http://www.dmoz.org/Computers/Data_Formats/Markup_Languages/XML/Tools/Editors/ specific XML Editor]. [http://sourceforge.net/projects/sernafree.mirror/ Serna-Free] is a more-or-less free [http://en.wikipedia.org/wiki/DocBook DocBook] editor which is much easier to use than a plain XML editor, but it introduces a lot of extraneous changes which must be removed before preparing a commit or patch ''You may have to return to this step should step 8 reveal a less than desirable arrangement of the data.''
 +
It will help translators to update their work, if you add a comment pair around your change, e.g.:  
 +
<pre><!-- New in 2.6.6 (2015): --> your new or changed text <!-- End of New in 2.6.6 (2015) --></pre>
  
 
Because the source documents are saved in XML - or to be more precise [[Glossary#D|DocBook]] - code, all changes need to be added to the source modules in that manner.  Small changes can be made directly into the XML file itself.  Larger and extensive changes may first be prepared in a text editor and later inserted into the module(s) in their proper places.  Resources for XML are listed in the [[#References to Supporting Technologies Used|References]] section for this step.
 
Because the source documents are saved in XML - or to be more precise [[Glossary#D|DocBook]] - code, all changes need to be added to the source modules in that manner.  Small changes can be made directly into the XML file itself.  Larger and extensive changes may first be prepared in a text editor and later inserted into the module(s) in their proper places.  Resources for XML are listed in the [[#References to Supporting Technologies Used|References]] section for this step.
Line 96: Line 174:
  
 
Apply the modules structural concepts to your own text after you have cut and pasted it into the XML file.  This is done by using the various '''XML tags''' in the existing text: ''chapter'', ''segment'', ''sect1'', ''sect2'', ''orderedlist'', ''list item'', ''para'' (to name just a few) and the corresponding closing tags. You should also use the '''Definitions''' ''<!ENTITY ...>'' from the main file where ever possible.
 
Apply the modules structural concepts to your own text after you have cut and pasted it into the XML file.  This is done by using the various '''XML tags''' in the existing text: ''chapter'', ''segment'', ''sect1'', ''sect2'', ''orderedlist'', ''list item'', ''para'' (to name just a few) and the corresponding closing tags. You should also use the '''Definitions''' ''<!ENTITY ...>'' from the main file where ever possible.
 +
 +
If you are adding or deleting an xml file, for example adding a new chapter or appendix, you also need to update files [guide|help]/[language]/gnucash-{guide|help}.xml and [guide|help]/[language]/Makefile.am. There is no need to update Makefile.in as this is generated by running autogen.sh.
  
 
;Note: if your update adds new modules to the full set of documentation, you should review all modules in the directory in which you are working (gnucash-docs/help/C or gnucash-docs/guide/C) to determine what changes,if any, need to be made to modules outside your original assessment in step 2.
 
;Note: if your update adds new modules to the full set of documentation, you should review all modules in the directory in which you are working (gnucash-docs/help/C or gnucash-docs/guide/C) to determine what changes,if any, need to be made to modules outside your original assessment in step 2.
Line 101: Line 181:
 
You can find an introduction to [http://www.docbook.org DocBook] in [http://docbook.org/tdg51/en/html/ch02.html Creating DocBook Documents].
 
You can find an introduction to [http://www.docbook.org DocBook] in [http://docbook.org/tdg51/en/html/ch02.html Creating DocBook Documents].
  
===Step 6 Validate XML Changes===
+
===Step 8 Validate XML Changes===
Test that your xml file has no syntax errors by running ''xmllint'' on the '''main file''' ''gnucash-{guide|help}.xml''.  
+
'''xmllint''' (invoked by '''make check''' in the appropriate build directory or sub-directory) is used to test that your xml file has no syntax errors or incorrect references to internal sections. The program ''xmllint'' is part of the package '''libxml'''.
[The program ''xmllint'' is part of the package '''libxml'''.]
+
 
 +
''xmllint'' starts with the main file ''gnucash-{guide|help}.xml''. The main file references the other xml files in the directory so all are checked.
 +
 
 +
In a Terminal, change directory to the place where the changed modules are located:
  
Change directory to the place where the changed modules are located.  For example, if the module you are changing is in the <tt>guide/C</tt> directory, and you had downloaded the documentation files to a directory called <tt>GC-docs</tt>, then you would <tt>cd</tt> to the directory <tt>C-docs/guide/C.</tt>  It is when you are inside that high-level directory that you execute the command.
+
For example, if you had downloaded the documentation files to a directory called <tt>/home/$USER/code/gnucash-docs</tt> and created a build directory called <tt>/home/$USER/code/gnucash-docs/build</tt>:
 
 
The file <tt>gnucash-guide.xml</tt> is found in the <tt>C</tt> subdirectory of <tt>GC-docs/guide/C</tt>.  Similarly, the file <tt>gnucash-help.xml</tt> would be in <tt>GC-docs/help/C</tt>.
 
  
Use this command in a terminal, with either ''gnucash-help.xml'' or ''gnucash-guide.xml'' as appropriate
+
To validate all the guide xml files for only the ''C'' (English) language:
<pre>xmllint --valid --noout gnucash-guide.xml</pre>
+
  cd /home/$USER/code/gnucash-docs/build/guide/C
Repeatedly perform this step until no xml errors are found.
+
To validate all the guide xml files for all languages:
 +
  cd /home/$USER/code/gnucash-docs/build/guide
 +
To validate all the guide and help xml files:
 +
  cd /home/$USER/code/gnucash-docs/build
 +
 
 +
Then:
 +
  make check
 +
 
 +
If there are any errors, fix them and repeat this step until no errors are found.
  
 
Then move on to the next step.  If you become unable to identify an XML error, then send an email to the developers' list mailto:gnucash-devel@gnucash.org If asking for help, provide as much information as possible, including the results of the <tt>xmllint</tt> command.
 
Then move on to the next step.  If you become unable to identify an XML error, then send an email to the developers' list mailto:gnucash-devel@gnucash.org If asking for help, provide as much information as possible, including the results of the <tt>xmllint</tt> command.
Line 117: Line 206:
 
If your module(s) are free of XML errors, then the command returns no errors or warnings (if running in a terminal) or an empty file (if redirecting output to a file).
 
If your module(s) are free of XML errors, then the command returns no errors or warnings (if running in a terminal) or an empty file (if redirecting output to a file).
  
===Step 7 Ensure Only the Changes you Expect Have Been Made===
+
===Step 9 Ensure Only the Changes you Expect Have Been Made===
 
This following command will show any changes to unstaged files
 
This following command will show any changes to unstaged files
<pre>git diff</pre>
+
  git diff
Also check status
+
Git status will list all files with differences to the last commit, in categories staged, unstaged, and unknown to git but not matching an ignore pattern.
<pre>git status</pre>
+
  git status
  
===Step 8 Proofread in HTML===
+
===Step 10 Proofread in HTML===
  
After the XML has been tested for integrity using xmllint and the  
+
After the XML has been tested for integrity using xmllint (make check) and the  
 
difference file has been determined to contain correct changes and only
 
difference file has been determined to contain correct changes and only
 
those, then the Guide or Help must be recreated in HTML and the results  
 
those, then the Guide or Help must be recreated in HTML and the results  
examined in your browser to verify that the online version of the Guide presents an  
+
examined in your browser to verify that the online version presents an  
 
appearance and reads as expected.
 
appearance and reads as expected.
  
Build the Guide or Help file in HTML. Use this command exactly as written in a terminal (NOTE: there must be a space following the directory name 'output_html/' in the command below):
+
Build the Guide or Help file in HTML. Use this command exactly as written in a terminal, from the appropriate directory within the build directory structure:
<pre>xsltproc -o output_html/ ../../xsl/general-customization.xsl gnucash-guide.xml
+
  make html
or
 
xsltproc -o output_html/ ../../xsl/general-customization.xsl gnucash-help.xml</pre>
 
  
:"output_html" is a directory that will automatically be created and filled with the files the command creates.  The directory name can be anything that makes sense to the person executing the command (output_html or something you choose).
+
The above ''make'' command will run ''xsltproc'' and use an XSL stylesheet (.../xsl/general-customization.xsl) to turn the raw input XML into the output HTML that comprises the online version of the Guide or Help.
 
 
:Note the '/' following the file name 'output_html'. When that character is in place, the directory (output_html) is created and  HTML modules placed in it.  When not present, the output_html modules are placed in the current directory.  Be sure to retain that '/' in its proper place!.
 
  
:The command segment (“../../xsl/general-customization.xsl”) is a relative path to the XSL stylesheet used to turn the raw input XML into the output HTML that comprises the online version of the Guide or Help. This command segment must be used exactly as written here.
+
The built html files with be placed in an automatically created directory, which if using the example directories will be:
 +
  /home/$USER/code/gnucash-docs/build/<guide|help>/C/gnucash-<guide|help>
  
If you wish to view images, screenshots, icons or figures of any kind while checking your changes in your browser, 2 symbolic links need to be created so the image files can be found. Run this quick fix (3 command lines in sequence) in a terminal:
+
Review the results in your browser; if you need to make changes, do so, then check, rebuild and review again.
 
 
<pre>cd output_html
 
ln -s ../figures
 
ln -s ../../../stylesheet
 
</pre>
 
 
 
Review the results in your browser; if you need to make changes, do so, then rebuild and review again.
 
  
 
It's amazing how errors which are obscure in XML--''everything is obscure in XML''--become blindingly obvious when rendered in the browser. Look for spelling errors, formatting oddness, incomplete tags, and missing or incorrect entities.
 
It's amazing how errors which are obscure in XML--''everything is obscure in XML''--become blindingly obvious when rendered in the browser. Look for spelling errors, formatting oddness, incomplete tags, and missing or incorrect entities.
Line 155: Line 234:
 
To view the results in a web browser, in a file manager (or for Windows: Windows Explorer/File Explorer) double click on either:
 
To view the results in a web browser, in a file manager (or for Windows: Windows Explorer/File Explorer) double click on either:
  
<pre>help/C/output_html/help.html
+
  /home/$USER/code/gnucash-docs/build/help/C/gnucash-help/help.html
 
or
 
or
guide/C/output_html/index.html
+
  /home/$USER/code/gnucash-docs/build/guide/C/gnucash-guide/index.html
</pre>
+
 
 +
 
 +
Once your inspection shows that the online Guide/Help is now acceptable in all respects, you should make certain that the build directory and its contents are not included in any respect in your patch.
 +
 
 +
If you are using ''build'' as the name of your build subdirectory in your repository directory, as in this example, it is not necessary to remove the build directory as the <repository>/.gitignore file includes '''build*''', so git will ignore it.
  
Once your inspection shows that the online Guide/Help is now acceptable in all respects, you should make certain that the output_html directory and its contents are not included in any respect in your patch.  To do that, before building the patch, remove the directory by this terminal command:
+
To remove the build directory structure, before building the patch, use this terminal command:
  
:<pre>rm -rf output_html</pre>
+
  rm -rf "/home/$USER/code/gnucash-docs/build"
  
===Step 9 Test Documentation in Linux===
+
===Step 11 Test Documentation in Linux===
  
For our purposes, &ldquo;Linux&rdquo; means any system that&rsquo;s not Windows or Mac OS X. GnuCash uses Yelp, the GNOME documentation browser, to display its help--both the User Manual and the Concepts Guide. This documentation gets installed in the standard GNOME help directory hierarchy. If you want to test the changes you just made to the documentation without interfering with the already-installed versions, you need to (1) install a development version of GnuCash locally, (2) install the changed documentation locally, and (3) tell (1) where to find (2).
+
For our purposes, &ldquo;Linux&rdquo; means any system that&rsquo;s not Windows or Mac OS X. GnuCash uses Yelp, the GNOME documentation browser, to display its help--both the User Manual and the Concepts Guide. This documentation gets installed in the standard GNOME help directory hierarchy. Although not tested, it's very likely that a cygwin environment on Windows or a fink/homebrew/macports environment on OS X can equally be configured to run these documentation tests. GnuCash as installed from the Windows Installer package or the OS X/Quarz dmg on the other hand can not.
  
Note that you can't test changes to the docs in this way with the 2.4
+
Aside from the above limitations you can test the documentation changes with any installed gnucash, version 2.6 or higher. Of course if you have written context help for a feature that is not present in your installed version of gnucash, you won't be able to test the direct context help button for that feature. You will however still be able to open the new help or guide in general from your installed (2.6+) version of gnucash.
series of releases. GnuCash only started using the system described
 
[[#7.3 Tell development GnuCash where to find docs|below]] ''after'' the
 
2.4 series. So if you want to test interaction between GnuCash and the
 
help system, you really do need to do it with a development version of
 
GnuCash.
 
  
If you don&rsquo;t want to test interaction with GnuCash, see [[#7.3 Tell development GnuCash where to find docs|below]] for a way to do that.
+
If you want to test the changes you just made to the documentation without interfering with the already-installed versions, you need to install a development version of GnuCash locally first.
  
====9.1 Install Development GnuCash Locally====
+
To test the changes,
 +
(1) install the changed documentation locally, and (2) tell your (locally) installed (2.6+) version of gnucash where to find it.
  
Build and install GnuCash locally as per [[Building]]. Let&rsquo;s say you&rsquo;ve installed in /home/$USER/code/gnucash-install.
 
  
====9.2 Install Updated Documentation Locally====
+
If you don&rsquo;t want to test interaction with GnuCash, see [[#11.3 Tell Development GnuCash Where to Find Docs|below]] for a way to do that.
  
<pre>
+
====11.1 Install Development GnuCash Locally====
$ pwd
+
''Remember this can be skipped if you prefer and have version 2.6+ of gnucash installed. It's only required to run context help tests.''
/home/$USER/code/gnucash-docs
 
$ ./autogen.sh # First time only, when building from repository copy
 
$ ./configure --prefix=/home/$USER/code/gnucash-docs-install # And your other preferred options....
 
$ make install
 
</pre>
 
  
====9.3 Tell Development GnuCash Where to Find Docs====
+
Without any special configuration the default installation directory will be /usr/local/... on Linux based systems. This is usually not a good location during development (or documentation changing), because this would interfere with your stable, running system and that's generally not what you want on a modern system where installing software is usually done via a package manager. So for development purposes we need to tell the build system to use another final location. This is done by running ''configure'' with the --prefix option. The installation directory should meet the following requirements:
 +
* it should be a writable location for the user that runs ''make install''
 +
* it should not be in the default paths /usr or /usr/local
  
<pre>
+
Build and install GnuCash locally as per [[Building]]. Let's say you've installed GnuCash in
$ GCASH=/home/$USER/code/gnucash-install # For convenience&rsquo; sake
+
  /home/$USER/code/gnucash-install
$ GCASHDOCS=/home/$USER/code/gnucash-docs-install # For convenience&rsquo; sake
+
 
$ XDG_DATA_DIRS="$GCASHDOCS/share:$XDG_DATA_DIRS" $GCASH/bin/gnucash &
+
====11.2 Install Updated Documentation Locally====
</pre>
+
 
 +
Let's say you wish to build your modified documentation in
 +
  /home/$USER/code/gnucash-docs-install
 +
 
 +
These are the commands for that:
 +
  $ cd /home/$USER/code/gnucash-docs
 +
  $ ./autogen.sh # First time only, when building from repository copy
 +
  $ ./configure --prefix=/home/$USER/code/gnucash-docs-install # Add any other needed options...
 +
  $ make install
 +
 
 +
====11.3 Tell Development GnuCash Where to Find Docs====
 +
  $ GCASH=/home/$USER/code/gnucash-install         # For convenience if you built gnucash yourself, otherwise:
 +
  $ GCASH=/usr                                      # For convenience if you use a default installed gnucash
 +
  $ GCASHDOCS=/home/$USER/code/gnucash-docs-install # For convenience
 +
  $ XDG_DATA_DIRS="$GCASHDOCS/share:$XDG_DATA_DIRS:/usr/local/share:/usr/share" $GCASH/bin/gnucash &
  
 
That last line, with XDG_DATA_DIRS, is the crux of it. That environment variable tells GnuCash, among other things, where to look for the documentation. In fact, it tells any tool which uses Yelp (and Yelp itself) where to look for documentation. For example, try the following:
 
That last line, with XDG_DATA_DIRS, is the crux of it. That environment variable tells GnuCash, among other things, where to look for the documentation. In fact, it tells any tool which uses Yelp (and Yelp itself) where to look for documentation. For example, try the following:
 
+
  $ XDG_DATA_DIRS="$GCASHDOCS/share:$XDG_DATA_DIRS" yelp ghelp:gnucash-help &
<pre>
 
$ XDG_DATA_DIRS="$GCASHDOCS/share:$XDG_DATA_DIRS" yelp ghelp:gnucash-help &
 
</pre>
 
  
 
That should open up your development-version GnuCash docs without first starting GnuCash itself. Handy if you don&rsquo;t need to test GnuCash along with the docs--i.e., if you&rsquo;re just updating sections that are already ''in'' the docs.
 
That should open up your development-version GnuCash docs without first starting GnuCash itself. Handy if you don&rsquo;t need to test GnuCash along with the docs--i.e., if you&rsquo;re just updating sections that are already ''in'' the docs.
  
====9.4 Conclusion====
+
====11.4 Conclusion====
  
 
Now you can update both your local GnuCash and GnuCash docs freely and test their interaction.
 
Now you can update both your local GnuCash and GnuCash docs freely and test their interaction.
  
===Step 10 Add any Extra Files===
+
===Step 12 Add any Extra Files===
If you have added any files (e.g. illustrations) that should be included in your patch, add (stage) them to git as well:
+
Git automatically tracks changes to files it knows are part of the repository. If you have added any files (xml or others e.g. illustrations) that should be included in your commit, add (stage) them by:
<pre>git add path/to/file </pre>
+
  git add path/to/file
 +
Note:  Do '''NOT''' add file(s) from your ''build'' directory structure.
  
This is another way to check your changes. Unless you're a programmer, you're probably not well practiced at examining diffs. If you have touched several files, the first thing to check is
+
Here is another way to check your changes. Unless you're a programmer, you're probably not well practiced at examining diffs. If you have touched several files, the first thing to check is
 
   git status -uno
 
   git status -uno
 
The <tt>-uno</tt> tells it to show only the repository files affected by your changes; all of the build products are ignored. Of course, if you've made a new file, that's ignored too, so make sure that all of the files you worked on ''and only those files'' are in the list. You can add new files with  
 
The <tt>-uno</tt> tells it to show only the repository files affected by your changes; all of the build products are ignored. Of course, if you've made a new file, that's ignored too, so make sure that all of the files you worked on ''and only those files'' are in the list. You can add new files with  
Line 222: Line 309:
 
   git checkout path/to/ignored-file
 
   git checkout path/to/ignored-file
  
===Step 11 Commit your Changes===
+
===Step 13 Commit your Changes===
 
Once you're satisfied with your changes, it's time to commit them.
 
Once you're satisfied with your changes, it's time to commit them.
 
You can commit everything that's been changed with
 
You can commit everything that's been changed with
Line 230: Line 317:
 
  git commit
 
  git commit
 
If you need to make further changes, you can update your commit instead of creating a new one with
 
If you need to make further changes, you can update your commit instead of creating a new one with
<pre>git commit -a --amend</pre>
+
  git commit -a --amend
  
 
There are even finer-grained ways to pick out bits and pieces to group into a commit, but they're beyond the scope of this tutorial.
 
There are even finer-grained ways to pick out bits and pieces to group into a commit, but they're beyond the scope of this tutorial.
  
 
When you make a commit git will open a screen editor; which one depends on how you set your environment. The default on most Unixes is ''vi'', but you can select a different one with the $EDITOR environment variable. Use the editor to make a good commit message. It should have a one-line (< 80 character) summary followed by a blank line, and a brief description of the change and its motivation. Don't get carried away here: If you need more than a couple of lines it should have been a smaller change.
 
When you make a commit git will open a screen editor; which one depends on how you set your environment. The default on most Unixes is ''vi'', but you can select a different one with the $EDITOR environment variable. Use the editor to make a good commit message. It should have a one-line (< 80 character) summary followed by a blank line, and a brief description of the change and its motivation. Don't get carried away here: If you need more than a couple of lines it should have been a smaller change.
 +
 +
The release announcement comes from commit messages, so include any information that should be passed on.
 +
You could even say ''This needs to be mentioned in the release announcement'' followed by the text you want in the announcement.
 +
 +
To add extra information to a previously pushed commit message, make some trivial change to a comment and write a commit message using the same subject line as the previous commit.
  
 
If required, you can check ''committed'' changes to a particular file with
 
If required, you can check ''committed'' changes to a particular file with
<pre>git log -p path/to/file</pre>
+
  git log -p path/to/file
  
===Step 12 Ensure your Local Copy of the Repository is the Same as on Github===
+
===Step 14 Ensure your Local Copy of the Repository is the Same as on Github===
 
A patch should always be made against the most recent revision of the gnucash-docs project in github, so the next step is to get the latest version and re-apply your changes to it:
 
A patch should always be made against the most recent revision of the gnucash-docs project in github, so the next step is to get the latest version and re-apply your changes to it:
 
   git pull --rebase
 
   git pull --rebase
Line 257: Line 349:
 
There are other tools that can simplify cleaning up conflicted files, but they're beyond the scope of this tutorial.
 
There are other tools that can simplify cleaning up conflicted files, but they're beyond the scope of this tutorial.
  
After resolving your conflicts and recommitting, it's wise to re-do steps 5 - 8 to make sure that everything wound up the way you want it.
+
After resolving your conflicts and recommitting, it's wise to re-do steps 8 - 10 to make sure that everything wound up the way you want it.
  
===Step 13 Prepare your Patch===
+
===Step 15 Prepare your Patch===
Once everything is tested and you're confident that your changes are correct, you're ready to make a patch.
+
Once everything is tested and committed, and you're confident that your changes are correct, you're ready to make a patch.
 
A patch file needs to be created for each commit. Each patch file will be named '0001-<your-summary>', substituting the first line from your commit message for <your-summary>, with spaces replaced by hyphens.
 
A patch file needs to be created for each commit. Each patch file will be named '0001-<your-summary>', substituting the first line from your commit message for <your-summary>, with spaces replaced by hyphens.
 
For example, if one of your commits had a summary "Better explanation of trading accounts",
 
For example, if one of your commits had a summary "Better explanation of trading accounts",
Line 266: Line 358:
  
 
Check how many commits you have made with
 
Check how many commits you have made with
<pre>git status</pre>
+
  git status
You can make patches of all commits between HEAD and the origin branch pointer, which is usually what you want, with  
+
You can make patches, 1 for each commit, for all commits which are in the current branch but not in the origin branch, with
<pre>git format-patch</pre>
+
  git format-patch origin
 
Or if you have done only 1 commit, create a patch from your latest commit with
 
Or if you have done only 1 commit, create a patch from your latest commit with
<pre>git format-patch HEAD^</pre>
+
  git format-patch HEAD^
 
Or if you have done more than 1 commit, create a patch file for each commit with
 
Or if you have done more than 1 commit, create a patch file for each commit with
<pre>git format-patch -n</pre> where n is the number of commits for which patches should be created.
+
  git format-patch -n
 +
where n is the number of commits for which patches should be created.
  
===Step 14 Publish your Authorship===
+
===Step 16 Publish your Authorship===
  
 
The first page, which can also be shown as ''About'' of the document is in the file '''<tt>gnucash-</tt>{<tt>guide</tt>|<tt>help</tt>}<tt>-C.omf</tt>'''. OMF means [http://en.wikipedia.org/wiki/Open_Media_Framework Open Media Framework]. Add a maintainer section with your data and check the other items like the date, which also needs an update.
 
The first page, which can also be shown as ''About'' of the document is in the file '''<tt>gnucash-</tt>{<tt>guide</tt>|<tt>help</tt>}<tt>-C.omf</tt>'''. OMF means [http://en.wikipedia.org/wiki/Open_Media_Framework Open Media Framework]. Add a maintainer section with your data and check the other items like the date, which also needs an update.
Line 280: Line 373:
 
Add your name and email address to the file AUTHORS. Create a separate patch for this change and ask to apply this patch also on gnucash/DOCUMENTERS - in both ''maint'' and ''master'' branches. The AUTHORS file can usually be shown in the packet manager while gnucash/DOCUMENTERS is shown in GnuCashs About->Credits->Documenters
 
Add your name and email address to the file AUTHORS. Create a separate patch for this change and ask to apply this patch also on gnucash/DOCUMENTERS - in both ''maint'' and ''master'' branches. The AUTHORS file can usually be shown in the packet manager while gnucash/DOCUMENTERS is shown in GnuCashs About->Credits->Documenters
  
===Step 15 Attach Patch to Bug===
+
===Step 17 Attach Patch to Bug===
Attach your patch file(s) to a [[http://bugzilla.gnome.org GnuCash bug report]] and you're done!
+
Attach your patch file(s) to a [[http://bugzilla.gnome.org GnuCash bug report]] and you're done! The relevant people will be automatically notified by email.
  
 
==References to Supporting Technologies Used==
 
==References to Supporting Technologies Used==
Line 291: Line 384:
 
[2] https://github.com
 
[2] https://github.com
 
   
 
   
===Step 4===
+
===Step 6===
 
[3]  http://www.jedit.org/
 
[3]  http://www.jedit.org/
 
   
 
   
===Step 5===
+
===Step 7===
 
[4]  http://en.wikipedia.org/wiki/DocBook
 
[4]  http://en.wikipedia.org/wiki/DocBook
  
Line 352: Line 445:
 
   identify -format "%w x %h %x x %y" IMAGE_NAME.FORMAT
 
   identify -format "%w x %h %x x %y" IMAGE_NAME.FORMAT
  
:The following bash script can be used to automatically ''calculate and assign the right value of dpi to a list of png files''. To use it create a new file and copy the following text into it. Save it with a descriptive name (e.g. adjust-dpi), close and make the file executable (<tt>chmod +x adjust-dpi</tt> on linux). Move this file in the "figures" folder and run it from the command line (i.e. type <tt>./adjust-dpi</tt>).
+
:For your convenience a bash script has been added in the gnucash-docs repository that can automatically ''calculate and assign the right value of dpi to a list of png files''. It is stored in the '''util''' subdirectory of the repository. To use it open a command line and run the script from the proper figures directory. For example:
 +
 
 +
  cd guide/pt/figures
 +
  ../../../util/adjust-dpi.sh
 +
 
 +
:To add your image to the List of Figures at the start of the Help or Tutorial and Concepts Guide, put your screenshot in a figure tag. For example:
  
# make a list file of all the png figures
+
  <figure pgwide="1">
ls *.png > list
+
    <title>This is the text that will appear in the List of Figures</title>
+
    <screenshot>
for figure in `cat list`;
+
    ...
do
+
    </screenshot>
# read width in pixel for the figure
+
  </figure>
width=$(identify -format "%w" "$figure")
 
# if the width is less than 90x14cm/2,54
 
if [ "$width" -lt 496 ]; then
 
  dpi=90
 
  # convert dpi from pixelsperinch to pixelspercentimeter
 
  dpi_cm=$(echo "scale=2; $dpi/2.54" | bc)
 
  # read the existing dpi from figure as XX PixelsPerCentimeter
 
  existing_dpi=$(identify -format "%x" "$figure")
 
  # set the future dpi of figure as XX PixelsPerCentimeter
 
  future_dpi="$dpi_cm PixelsPerCentimeter"
 
  # apply new dpi only if it's changed from the existing
 
  if [ "$existing_dpi" != "$future_dpi" ]; then
 
    convert -units PixelsPerInch -density "$dpi" "$figure" "$figure"
 
    echo "File $figure converted to $dpi dpi"
 
  fi
 
# if the width is more than 144x14cm/2,54
 
else
 
  if [ "$width" -gt 793 ]; then
 
    # set the new dpi in function of the image size
 
    dpi=$(echo "scale=0; $width*2.54/14" | bc)
 
    # convert dpi from pixelsperinch to pixelspercentimeter
 
    dpi_cm=$(echo "scale=2; $dpi/2.54" | bc)
 
    # read the existing dpi from figure as XX PixelsPerCentimeter
 
    existing_dpi=$(identify -format "%x" "$figure")
 
    # set the future dpi of figure as XX PixelsPerCentimeter
 
    future_dpi="$dpi_cm PixelsPerCentimeter"
 
    # apply new dpi only if it's changed from the existing
 
    if [ "$existing_dpi" != "$future_dpi" ]; then
 
      convert -units PixelsPerInch -density "$dpi" "$figure" "$figure"
 
      echo "File $figure converted to $dpi dpi"
 
    fi
 
# for figures with width between 496px and 793px use a dpi of 144
 
  else
 
    dpi=144
 
    # convert dpi from pixelsperinch to pixelspercentimeter
 
    dpi_cm=$(echo "scale=2; $dpi/2.54" | bc)
 
    # read the existing dpi from figure as XX PixelsPerCentimeter
 
    existing_dpi=$(identify -format "%x" "$figure")
 
    # set the future dpi of figure as XX PixelsPerCentimeter
 
    future_dpi="$dpi_cm PixelsPerCentimeter"
 
    # apply new dpi only if it's changed from the existing
 
    if [ "$existing_dpi" != "$future_dpi" ]; then
 
      convert -units PixelsPerInch -density 144 "$figure" "$figure"
 
      echo "File $figure converted to 144 dpi"
 
    fi
 
  fi
 
fi
 
done
 
echo "Done!"
 
  
 
== Maintenance ==
 
== Maintenance ==
Line 416: Line 465:
 
===Text conventions===
 
===Text conventions===
 
* There are variable definitions in the main file, which must be used e.g. for future changes to revision numbers, gnucash-guide.xml defines variable '''vers-stable'''
 
* There are variable definitions in the main file, which must be used e.g. for future changes to revision numbers, gnucash-guide.xml defines variable '''vers-stable'''
:<pre><!ENTITY vers-stable "2.6.6"></pre>
+
:<tt><!ENTITY vers-stable "2.6.6"></tt>
 
:and appendixa.xml uses this variable like
 
:and appendixa.xml uses this variable like
:<pre>The process works on &vers-stable; datafiles, and ought to</pre>
+
:<tt>The process works on &vers-stable; datafiles, and ought to</tt>
 
* All accounts named must be tagged with <emphasis>: e.g. <emphasis>Expenses:Tax</emphasis>
 
* All accounts named must be tagged with <emphasis>: e.g. <emphasis>Expenses:Tax</emphasis>
 +
* Hyphens and dashes:
 +
: To represent a negative number or subtraction:
 +
:: The typographically correct symbol to use is &minus; (U+2212, <tt>&amp;minus;</tt>). The ASCII hyphen-minus - (U+002d) is commonly used and is also fine. Whichever you use, be consistent, at least on the whole page.
 +
:: Examples:
 +
::: Number negative 1 (&minus;1): <tt>&amp;minus;1</tt>
 +
::: Formula GROSS_SALE &minus; TOTALBUY: <tt>GROSS_SALE &amp;minus; TOTALBUY</tt>
 +
:: See http://www.thepunctuationguide.com/index.html for guidance on using English language punctuation,  including  <tt>&amp;ndash;</tt> and <tt>&amp;mdash;</tt>.
  
 
* In the current state of this page there are many more. Have a look at the recently reworked chapters. If you have some free time, add them here.
 
* In the current state of this page there are many more. Have a look at the recently reworked chapters. If you have some free time, add them here.
Line 430: Line 486:
 
* text besides icon
 
* text besides icon
 
* font: Sans. 9 point for application and 11 point for window title
 
* font: Sans. 9 point for application and 11 point for window title
 +
 +
 +
[[Category:Documentation]]
 +
 +
[[Category:Translation]]

Revision as of 08:36, 22 January 2017

These instructions describe the process to change both the GnuCash "Guide" and the GnuCash "Help" manuals as well as any other parts of GnuCash documentation. If you are interested in translating the documentation, you should read Translation#How_to_translate_the_GnuCash_guide_and.2For_help_files, too.

Preface and Introduction -- What to expect

The material in the documentation set uses the same software management tools that are used for the program itself. This ensures that changes are made consistently and reliably. It does, however, require that documentation contributors learn and use several tools to engage the process. The tools and the process are outlined in this page.

Background Overview

To set up, you will obtain a copy of the full set of the most recent documentation. You can obtain a full set using the version control system git (see below). Once you have all the documentation you can make changes in any part of the documents that might need them. The most current documents can be seen at http://code.gnucash.org/docs/.

Since others could be making changes to the documentation at the same time you are, you will need to make sure that any changes that others have made in the interim are included in what you will install. The version control system git is used to ensure that everyone's changes can be incorporated efficiently into one final set of source files.

Any changes you make will be inserted into your local copies of the source documentation files. These source files use a special markup in XML to provide structure. Later in the process, the XML files are converted to other versions (HTML, PDF, etc.) for viewing. As a documentation support person, your task is to shepherd your modifications through all stages from start to finish.

At each stage, you must validate your changes to assure that they are both valid and have the intended effect, and you must address any errors or unexpected changes that are found.

Since your changes will be carried out by software, there is a difference determination process that identifies exactly what and where changes will be made. This process permits you to be sure that only what you intend will actually be installed.

For the sake of quality control there is a review process that you must use in order to make your change official.

The above brief description when executed results in a file of changes. These changes must be explained as to their purpose. Accompanying the explanation in words is everything that makes up the substance of the change. The term for this is "patch". Whether you introduce a major restructuring or a small tweak, every thing is a "patch".

Creation of the explanation and the content of the change you are making are combined in a bugzilla event, otherwise called a "bug". In this usage bug means a statement of what is changing and why along with the content that will be the change when approved and applied to all the places needed. It does not necessarily mean a problem is being corrected, enhancements are handled as bugs too.

After creating your patch and presenting it in a bugzilla bug, usually a developer watching the bugzilla patchreport will review it. If you see no reaction in the next days, you can inform them also on their list and ask for the review and approval. Your email should list a brief statement of what your bug is about. You also provide the Bugzilla bug ID number so it can be found and reviewed easily.

If everything is accepted without requiring further work, your patch will be applied to the main set of documentation by a developer and you will be notified of that action.

As your first act in getting started, become very familiar with the references given in the REFERENCES section below.

The Make Utility

Like the programs, the documentation is built using the make utility.

In the make build system there are three important directories:

  • the source directory
  • the build directory
  • the installation directory (which can also be more than one directory all under a special directory called the prefix-directory)

The source directory is where your source files are. I.e. gnucash-docs (the clone of our github repository) with all its subdirectories on your system for documentation. If you want to make changes to the documentation source, you do this in the source directory structure, not the build directory structure.

The build directory is a directory used by the build system to store all files/objects that are generated by the build system. make is always executed in the build directory or a sub-directory of the build directory. Each make recipe results in at least one such file or object.

The installation directory is the location where the generated objects should finally end up when using make install.

For the GnuCash documentation, the make command must be used with a target argument which determines which type(s) of the documentation are built. E.g. make html builds the html files which allow the documentation to be viewed in a web browser. (If no target is specified, make does nothing because the xml files are both the source and the target which yelp needs to display the documentation.) What make actually does is specified in the contents of make files. These are files called Makefile (or Makefile.am) and exist in multiple directories of the documentation repository. What they do depends on which directory is current when the make command is executed. In general, the lower down the build directory tree, the more specific the scope. By changing the current directory, make can build:

  • Both the Help & Guide
  • Either the Help or Guide
  • Just the Help or Guide for a specific language

As building the documentation can take a while, it is best to only build what is needed for your changes.

Typical targets of the make target command used for the documentation are:

 make check                # use xmllint to validate xml files
 make html                 # use xsltproc to build the html (web browser) documentation
 make pdf                  # use xsltproc to build the pdf documentation
 make mobi                 # use xsltproc to build the mobi documentation
 make epub                 # use xsltproc to build the mobi documentation

There are additional installation dependencies required for building the pdf and mobi formats. See [1].

To install the built documentation where it can be used for testing the interaction with GnuCash programs:

 make install              # See #Step 11 Test Documentation in Linux.

The Documentation Change Process -- What and How it happens

To write GnuCash documentation the following steps must be completed in the order given. When executing any command listed, do not use quotations of any sort around the commands.

N.B.: The instructions below are for a non-committer preparing a patch. If you have commit privileges in the gnucash-docs repository, the git commands you use will be somewhat different. Please see Git. If you're not familiar with using git, you'll find more details on basic commands and links to documentation there as well. You may prefer one of the many Git GUIs to the command-line instructions here, especially if you use Microsoft Windows.


Step 1 Create a Bugzilla Bug for the Documentation Change

  1. Create a bugzilla bug if one does not already exist
    • At this URL, register yourself to create an account.
    • After your account has been created, Login to the section of bugzilla reserved for GnuCash.
    • Enter your userid and password and press 'login'.
    • After logging in you are at this page and you can start the bug creation process by answering the questions on the page.
      • Bug Version, use
        • git-maint if your patch should be included in the next release of the current stable series.
        • git-master if your patch should be included in next release of the current unstable series, and eventually in the subsequent stable series.
      • In the comment box, explain the nature of the bug fix.
    • When you press commit, bugzilla creates the bug and a unique id for it.
  2. Note the bug number. You will be listed as wanting to be notified any time there is an update to the bug. Monitor it until it is confirmed and installed to the master branch.

Step 2 Git Clone

If you are new to using git, you may find it useful to read Git_For_Newbies for more information about specific git commands, how they are used in the process of modifying GnuCash, and how to submit changes for review using pull requests (preferred) instead of patches. If you already familiar with git, The Git page may be more suitable.

For simplicity, this page assumes the local repository will be in folder /home/$USER/code/gnucash-docs, but it can be wherever the user prefers.

 cd /home/$USER/code

Use this command exactly as written to download a full set of documentation files from github to your own computer.

 git clone https://github.com/Gnucash/gnucash-docs gnucash-docs

The terminal command will cause the documentation to be copied to your computer under the name you specify in the command.
Executing the command assumes that git has previously been installed successfully on your computer.
If the system finds that git is not installed, it ignores your request. Linux will then reply with the correct command to download and install the package, while Windows will say something like:

'git' is not recognized as an internal or external command, operable program or batch file.

If you need to install git with a Linux package manager, make note of the module(s) that it tells you should be deleted. Also, note the command it provides to delete such module(s). Next install git with the install command given. Note any instructions given during the install process and carry them out. Finally, use the instruction first noted that tells you what module(s) to remove and carry out the remove instruction.

In the git command "gnucash-docs" is the directory name where the checkout process places the full set of documentation modules. You can use that name or some other. Remember that the bash shell is case sensitive when typing commands and providing names.
Avoid merge conflicts and merge commits by always using

 git pull --rebase

to update your local repository.

Step 3 Generate configure Script

This step checks that various make utilities (autoconf, libtoolize & automake) are installed and builds the configure script and the Makefile.in files from the configure.ac and Makefile.am files. Makefile.in files are pseudo Makefile's used by the configure script with lots of variables that still need final setting.

 cd /home/$USER/code/gnucash-docs
 ./autogen.sh   # autogen.sh is *always* run in the top-level *source* directory

autogen.sh is platform independent and is used to initiate the whole build system for a given project.

As a rule of thumb, autogen.sh should be run the first time you want to initialize the build system and sometimes after changes are made in configure.ac or Makefile.am files. Frequently those changes are auto detected though. Running autogen.sh when it's not necessary doesn't do harm but it will make the next build take longer.

The first time autogen.sh is run, it may complain about missing packages autoconf, libtoolize or automake. You can usually install the generic packages of the same name using your distribution's package manager. You'll probably also need to install xsltproc. For example, in Ubuntu:

 sudo apt-get install autoconf libtoolize automake xsltproc

Step 4 Make a Build Directory Structure and the Makefiles

Create a build directory structure to keep the built documentation files separate from the repository directories. This page assumes the build directory is called build and is a subdirectory of the repository but that does not have to be so. It can be called whatever suits you, and even be wherever it suits you. Some people create it as a subdirectory to the source directory. Others have it in a completely different location, say to have all builds together under one directory. That is a matter of preference.

 cd /home/$USER/code/gnucash-docs
 mkdir build    # only needed if not previously created
 cd build       # configure must be run from the "build" directory

Note: If you intend to test invoking help from GnuCash programs, you should add the --prefix=... option to the configure command below now to save having to rerun it later. See #Step 11 Test Documentation in Linux.

If your build directory is a subdirectory of your repository

 ../configure

Otherwise (depending on where your repository is)

 /home/$USER/code/gnucash-docs/configure   # or use a relative path to run your repository configure script

The ../configure command above will recreate the gnucash-docs directory structure under the current directory (build) but without the source files. It then looks up the installation location for all tools and libraries used and creates the required Makefiles from the Makefile.in files. It can enable or disable certain options in the Makefiles based on its findings. configure can also take extra command line options that can alter what it will include in the Makefiles. You can see these options by running configure --help. Most of them are not relevant for us, except for the few we invented ourselves like --with-mobi.

configure must be run right after autogen.sh. Running it when not really required has no negative side-effect other than that the next build may take longer because more objects will be rebuilt.

Step 5 Find Update Location

Find the place in the documentation that you want to change (in the repository, not the build directories); identify the file(s) that need to be changed to accomplish your documentation objective. Your changes should roughly follow the GNOME Documentation Style Guide of the GNOME Documentation Project.

This means you have to read the documentation to find exactly where the error is or the best place to insert the additional information that improves the understanding of how the feature works or what its purpose is in the software.

Experienced developers instruct that you should focus first on the modules in either of these two directories (found in the step 1 downloaded files): gnucash-docs/help/C or gnucash-docs/guide/C.

Trying to open each file in each of those directories will show whether there are any errors in the modules you downloaded. If you find errors, ask a more experienced person whether these should first be corrected before proceeding with your updates. You can do that by email to gnucash-devel@gnucash.org. If you choose this method, be sure to be a subscriber to that list in order to receive a prompt answer. If you are not a subscriber, then your email will wait for the list manager to find the time to address emails received from non-subscribers.

It will be useful to have either a printed copy or a PDF copy [3] of the documentation available for reference. The PDF is often useful, because it allows using FIND (ctrl-F) to search for key words. This can be important to assure yourself that you have covered the existing places in the documentation where the issue you are interested in has already had a mention or treatment.

Step 6 Draft your Update in a Text File

If your changes are few and easily formulated, you should be able to skip this step and proceed to #Step 7 - place the draft changes in XML files.

For substantive changes to the documentation it is frequently helpful to develop your ideas in a separate temporary text file. Use a text editor such as jEdit, which is available for both Linux and Windows operating systems. jEdit has an XML plugin so can also be used for editing XML files.

Step 7 Place the Draft Changes in XML Files

Insert your changes into the XML file(s) affected.

Note: Edit the source files in the repository directories, not in the build directories. The various make commands (run from the build directories), will copy the files from the repository to the build directories.

Make your changes fit the XML tags in the manner of the existing documentation. Adjust your XML tag structure so that the finished structure appears properly and as you intended in the HTML version of the documentation. Doing this might be easier by using a specific XML Editor. Serna-Free is a more-or-less free DocBook editor which is much easier to use than a plain XML editor, but it introduces a lot of extraneous changes which must be removed before preparing a commit or patch You may have to return to this step should step 8 reveal a less than desirable arrangement of the data. It will help translators to update their work, if you add a comment pair around your change, e.g.:

<!-- New in 2.6.6 (2015): --> your new or changed text <!-- End of New in 2.6.6 (2015) -->

Because the source documents are saved in XML - or to be more precise DocBook - code, all changes need to be added to the source modules in that manner. Small changes can be made directly into the XML file itself. Larger and extensive changes may first be prepared in a text editor and later inserted into the module(s) in their proper places. Resources for XML are listed in the References section for this step.

Review the inserted and corrected text to verify that it is presented within the proper XML tags, using existing tags as a guide.

If text exceeds the vertical text border guides, you should not be alarmed that text outside the vertical border guides would be lost. These border guides show up when the XML module is opened, but are length of line indicators and not warnings that text should be moved within the guides.

Apply the modules structural concepts to your own text after you have cut and pasted it into the XML file. This is done by using the various XML tags in the existing text: chapter, segment, sect1, sect2, orderedlist, list item, para (to name just a few) and the corresponding closing tags. You should also use the Definitions <!ENTITY ...> from the main file where ever possible.

If you are adding or deleting an xml file, for example adding a new chapter or appendix, you also need to update files [guide|help]/[language]/gnucash-{guide|help}.xml and [guide|help]/[language]/Makefile.am. There is no need to update Makefile.in as this is generated by running autogen.sh.

Note
if your update adds new modules to the full set of documentation, you should review all modules in the directory in which you are working (gnucash-docs/help/C or gnucash-docs/guide/C) to determine what changes,if any, need to be made to modules outside your original assessment in step 2.

You can find an introduction to DocBook in Creating DocBook Documents.

Step 8 Validate XML Changes

xmllint (invoked by make check in the appropriate build directory or sub-directory) is used to test that your xml file has no syntax errors or incorrect references to internal sections. The program xmllint is part of the package libxml.

xmllint starts with the main file gnucash-{guide|help}.xml. The main file references the other xml files in the directory so all are checked.

In a Terminal, change directory to the place where the changed modules are located:

For example, if you had downloaded the documentation files to a directory called /home/$USER/code/gnucash-docs and created a build directory called /home/$USER/code/gnucash-docs/build:

To validate all the guide xml files for only the C (English) language:

 cd /home/$USER/code/gnucash-docs/build/guide/C

To validate all the guide xml files for all languages:

 cd /home/$USER/code/gnucash-docs/build/guide

To validate all the guide and help xml files:

 cd /home/$USER/code/gnucash-docs/build

Then:

 make check

If there are any errors, fix them and repeat this step until no errors are found.

Then move on to the next step. If you become unable to identify an XML error, then send an email to the developers' list mailto:gnucash-devel@gnucash.org If asking for help, provide as much information as possible, including the results of the xmllint command.

If your module(s) are free of XML errors, then the command returns no errors or warnings (if running in a terminal) or an empty file (if redirecting output to a file).

Step 9 Ensure Only the Changes you Expect Have Been Made

This following command will show any changes to unstaged files

 git diff

Git status will list all files with differences to the last commit, in categories staged, unstaged, and unknown to git but not matching an ignore pattern.

 git status

Step 10 Proofread in HTML

After the XML has been tested for integrity using xmllint (make check) and the difference file has been determined to contain correct changes and only those, then the Guide or Help must be recreated in HTML and the results examined in your browser to verify that the online version presents an appearance and reads as expected.

Build the Guide or Help file in HTML. Use this command exactly as written in a terminal, from the appropriate directory within the build directory structure:

 make html

The above make command will run xsltproc and use an XSL stylesheet (.../xsl/general-customization.xsl) to turn the raw input XML into the output HTML that comprises the online version of the Guide or Help.

The built html files with be placed in an automatically created directory, which if using the example directories will be:

 /home/$USER/code/gnucash-docs/build/<guide|help>/C/gnucash-<guide|help>

Review the results in your browser; if you need to make changes, do so, then check, rebuild and review again.

It's amazing how errors which are obscure in XML--everything is obscure in XML--become blindingly obvious when rendered in the browser. Look for spelling errors, formatting oddness, incomplete tags, and missing or incorrect entities.

To view the results in a web browser, in a file manager (or for Windows: Windows Explorer/File Explorer) double click on either:

 /home/$USER/code/gnucash-docs/build/help/C/gnucash-help/help.html

or

 /home/$USER/code/gnucash-docs/build/guide/C/gnucash-guide/index.html


Once your inspection shows that the online Guide/Help is now acceptable in all respects, you should make certain that the build directory and its contents are not included in any respect in your patch.

If you are using build as the name of your build subdirectory in your repository directory, as in this example, it is not necessary to remove the build directory as the <repository>/.gitignore file includes build*, so git will ignore it.

To remove the build directory structure, before building the patch, use this terminal command:

 rm -rf "/home/$USER/code/gnucash-docs/build"

Step 11 Test Documentation in Linux

For our purposes, “Linux” means any system that’s not Windows or Mac OS X. GnuCash uses Yelp, the GNOME documentation browser, to display its help--both the User Manual and the Concepts Guide. This documentation gets installed in the standard GNOME help directory hierarchy. Although not tested, it's very likely that a cygwin environment on Windows or a fink/homebrew/macports environment on OS X can equally be configured to run these documentation tests. GnuCash as installed from the Windows Installer package or the OS X/Quarz dmg on the other hand can not.

Aside from the above limitations you can test the documentation changes with any installed gnucash, version 2.6 or higher. Of course if you have written context help for a feature that is not present in your installed version of gnucash, you won't be able to test the direct context help button for that feature. You will however still be able to open the new help or guide in general from your installed (2.6+) version of gnucash.

If you want to test the changes you just made to the documentation without interfering with the already-installed versions, you need to install a development version of GnuCash locally first.

To test the changes, (1) install the changed documentation locally, and (2) tell your (locally) installed (2.6+) version of gnucash where to find it.


If you don’t want to test interaction with GnuCash, see below for a way to do that.

11.1 Install Development GnuCash Locally

Remember this can be skipped if you prefer and have version 2.6+ of gnucash installed. It's only required to run context help tests.

Without any special configuration the default installation directory will be /usr/local/... on Linux based systems. This is usually not a good location during development (or documentation changing), because this would interfere with your stable, running system and that's generally not what you want on a modern system where installing software is usually done via a package manager. So for development purposes we need to tell the build system to use another final location. This is done by running configure with the --prefix option. The installation directory should meet the following requirements:

  • it should be a writable location for the user that runs make install
  • it should not be in the default paths /usr or /usr/local

Build and install GnuCash locally as per Building. Let's say you've installed GnuCash in

 /home/$USER/code/gnucash-install

11.2 Install Updated Documentation Locally

Let's say you wish to build your modified documentation in

 /home/$USER/code/gnucash-docs-install

These are the commands for that:

 $ cd /home/$USER/code/gnucash-docs
 $ ./autogen.sh # First time only, when building from repository copy
 $ ./configure --prefix=/home/$USER/code/gnucash-docs-install # Add any other needed options...
 $ make install

11.3 Tell Development GnuCash Where to Find Docs

 $ GCASH=/home/$USER/code/gnucash-install          # For convenience if you built gnucash yourself, otherwise:
 $ GCASH=/usr                                      # For convenience if you use a default installed gnucash
 $ GCASHDOCS=/home/$USER/code/gnucash-docs-install # For convenience
 $ XDG_DATA_DIRS="$GCASHDOCS/share:$XDG_DATA_DIRS:/usr/local/share:/usr/share" $GCASH/bin/gnucash &

That last line, with XDG_DATA_DIRS, is the crux of it. That environment variable tells GnuCash, among other things, where to look for the documentation. In fact, it tells any tool which uses Yelp (and Yelp itself) where to look for documentation. For example, try the following:

 $ XDG_DATA_DIRS="$GCASHDOCS/share:$XDG_DATA_DIRS" yelp ghelp:gnucash-help &

That should open up your development-version GnuCash docs without first starting GnuCash itself. Handy if you don’t need to test GnuCash along with the docs--i.e., if you’re just updating sections that are already in the docs.

11.4 Conclusion

Now you can update both your local GnuCash and GnuCash docs freely and test their interaction.

Step 12 Add any Extra Files

Git automatically tracks changes to files it knows are part of the repository. If you have added any files (xml or others e.g. illustrations) that should be included in your commit, add (stage) them by:

 git add path/to/file

Note: Do NOT add file(s) from your build directory structure.

Here is another way to check your changes. Unless you're a programmer, you're probably not well practiced at examining diffs. If you have touched several files, the first thing to check is

 git status -uno

The -uno tells it to show only the repository files affected by your changes; all of the build products are ignored. Of course, if you've made a new file, that's ignored too, so make sure that all of the files you worked on and only those files are in the list. You can add new files with

 git add path/to/new-file

and revert files that you didn't mean to change with

 git checkout path/to/ignored-file

Step 13 Commit your Changes

Once you're satisfied with your changes, it's time to commit them. You can commit everything that's been changed with

git commit -a

or you can commit a few files at a time with

git add path/to/file
git commit

If you need to make further changes, you can update your commit instead of creating a new one with

 git commit -a --amend

There are even finer-grained ways to pick out bits and pieces to group into a commit, but they're beyond the scope of this tutorial.

When you make a commit git will open a screen editor; which one depends on how you set your environment. The default on most Unixes is vi, but you can select a different one with the $EDITOR environment variable. Use the editor to make a good commit message. It should have a one-line (< 80 character) summary followed by a blank line, and a brief description of the change and its motivation. Don't get carried away here: If you need more than a couple of lines it should have been a smaller change.

The release announcement comes from commit messages, so include any information that should be passed on. You could even say This needs to be mentioned in the release announcement followed by the text you want in the announcement.

To add extra information to a previously pushed commit message, make some trivial change to a comment and write a commit message using the same subject line as the previous commit.

If required, you can check committed changes to a particular file with

 git log -p path/to/file

Step 14 Ensure your Local Copy of the Repository is the Same as on Github

A patch should always be made against the most recent revision of the gnucash-docs project in github, so the next step is to get the latest version and re-apply your changes to it:

 git pull --rebase

Most of the time this will work with no changes needed, but if someone else has committed a change in the same files that you did you'll get conflicts.

Conflict Resolution

git status will tell you which files have conflicts, and when you open one of them it will be marked with lines like

<<<<<<HEAD
...
======
...
>>>>>>Your change summary

You'll have to edit each file with conflicts to remove those lines and get the section in between to read the way you want. After you've fixed up a file, use git add path/to/filename to register the changes and when you've fixed them all and added them to the index, use git commit to re-commit them. This time in the editor you'll see a line

Conflicts:

followed by a list of the files with conflicts. Be sure to remove those lines from the file, since you've resolved the conflicts.

There are other tools that can simplify cleaning up conflicted files, but they're beyond the scope of this tutorial.

After resolving your conflicts and recommitting, it's wise to re-do steps 8 - 10 to make sure that everything wound up the way you want it.

Step 15 Prepare your Patch

Once everything is tested and committed, and you're confident that your changes are correct, you're ready to make a patch. A patch file needs to be created for each commit. Each patch file will be named '0001-<your-summary>', substituting the first line from your commit message for <your-summary>, with spaces replaced by hyphens. For example, if one of your commits had a summary "Better explanation of trading accounts", the corresponding patch file name would be 0001-Better-explanation-of-trading-accounts.patch.

Check how many commits you have made with

 git status

You can make patches, 1 for each commit, for all commits which are in the current branch but not in the origin branch, with

 git format-patch origin

Or if you have done only 1 commit, create a patch from your latest commit with

 git format-patch HEAD^

Or if you have done more than 1 commit, create a patch file for each commit with

 git format-patch -n

where n is the number of commits for which patches should be created.

Step 16 Publish your Authorship

The first page, which can also be shown as About of the document is in the file gnucash-{guide|help}-C.omf. OMF means Open Media Framework. Add a maintainer section with your data and check the other items like the date, which also needs an update.

Add your name and email address to the file AUTHORS. Create a separate patch for this change and ask to apply this patch also on gnucash/DOCUMENTERS - in both maint and master branches. The AUTHORS file can usually be shown in the packet manager while gnucash/DOCUMENTERS is shown in GnuCashs About->Credits->Documenters

Step 17 Attach Patch to Bug

Attach your patch file(s) to a [GnuCash bug report] and you're done! The relevant people will be automatically notified by email.

References to Supporting Technologies Used

Step 1

[1] http://wiki.gnucash.org/wiki/Bugzilla

Step 2

[2] https://github.com

Step 6

[3] http://www.jedit.org/

Step 7

[4] http://en.wikipedia.org/wiki/DocBook

[5] http://www.docbook.org/ DocBook: The Definitive Guide

Some Distributions have it as a package named like docbook-tdg.

[6] http://www.tldp.org/LDP/LDP-Author-Guide/html/tools-edit.html

[7] http://www.netlingo.com/tips/html-code-cheat-sheet.php

[8] http://wiki.gnucash.org/wiki/Git

Images and screenshots

Screenshots for GnuCash documentation must be submitted in .png format or in .svg where applicable. It is better if you can use a theme similar to "clearlooks" for linux in order to keep consistency with existing images. The screenshots and images added to the GnuCash documentation must fit for two purposes: video printing (e.g. GNOME yelp) and paper printing (pdf creation). While the former has limits on image width in pixel (generally 510px) this limitation should be avoided for the latter.

  • Both requirements are met by using a doubled <imageobject> tag as shown next:
           <imageobject role="html">
             <imagedata fileref="figures/Help_Pref_AccntPeriod.png" format="PNG"
                        srccredit="Cristian Marchi" width="510px"></imagedata>
           </imageobject>
           <imageobject role="fo">
             <imagedata fileref="figures/Help_Pref_AccntPeriod.png" format="PNG"
                        srccredit="Cristian Marchi"></imagedata>
           </imageobject>
The "html" attribute refers to display visualization of the screenshots (the width is limited to 510px) while the "fo" attribute refers to pdf printing.
So when you take a screenshot for inclusion in the GnuCash documentation, it should not be resized to 510 pixel width. Instead you should leave it as is, add the "html" attribute and fix the width to 510px as shown above (note that the width tag is not necessary if the image has a width smaller than 510px).
  • You need to accomplish another step in order to prepare the captured screenshot for printing: change the dpi (dot per inch) of the image. The dpi is a printing resolution and is just a tag in the image (the higher the dpi is, the better the image will be printed on paper). The printing size, dpi and image pixel dimensions are in this relation:
size = pixels / dpi
So if you have a screenshot that is 800x560 pixels with a dpi of 80 you will have the screenshot in the pdf output displayed as 800/80 x 560/80 inches = 10 x 7 inches = 25 x 17,5 cm. (1 inch is about 2,5 cm)
The available space in the A4 format pdf output is at max 15 cm so you can resize the screenshot by changing it's dpi. Normally (if you take a screenshot when the GnuCash window is almost at it's minimum) this value is set to 144 (see the GnuCash help figures). When the dpi is 144 our example screenshot will be printed as 800/144 x 560/144 inches = 14 x 10 cm and will stay inside the available areas.
If the screenshot you are going to add to documentation is wider than 850 pixels, you should increase the dpi above 144 so that it's printed size remains less than 15 cm.
So how can the dpi of an image be changed?
Two ways:
  • Open the screenshot in The Gimp and select Image->Print Size. In the dialog that will open set the X and Y resolution to the desired dpi (check that the unit in the right is set to the desired value - normally pixels/in). Press "Ok" and save the image.
  • A faster approach uses Imagemagick a library for images manipulation. From a terminal window issue the following command:
 convert -units PixelsPerInch -density DPI IN OUT 
where DPI is the desired dpi value (e.g. 144), IN is the input image filename and OUT the output filename (that could be the same as IN).
To convert the dpi of a bunch of images do this from a linux terminal:
ls *.png > list
for i in `cat list`; do convert -units PixelsPerInch -density 144 "$i" "$i"; done
The first line creates the file "list" with a list of all png files in the current directory
The second and third lines applies a dpi of 130 to all images listed in the "list" file
Imagemagick let's you also see sizes and Pixels per inch from the command line:
 identify -format "%w x %h %x x %y" IMAGE_NAME.FORMAT
For your convenience a bash script has been added in the gnucash-docs repository that can automatically calculate and assign the right value of dpi to a list of png files. It is stored in the util subdirectory of the repository. To use it open a command line and run the script from the proper figures directory. For example:
 cd guide/pt/figures
 ../../../util/adjust-dpi.sh
To add your image to the List of Figures at the start of the Help or Tutorial and Concepts Guide, put your screenshot in a figure tag. For example:
 <figure pgwide="1">
   <title>This is the text that will appear in the List of Figures</title>
   <screenshot>
   ...
   </screenshot>
 </figure>

Maintenance

In this section are collected all the standards used to work on documentation.

Text conventions

  • There are variable definitions in the main file, which must be used e.g. for future changes to revision numbers, gnucash-guide.xml defines variable vers-stable
<!ENTITY vers-stable "2.6.6">
and appendixa.xml uses this variable like
The process works on &vers-stable; datafiles, and ought to
  • All accounts named must be tagged with <emphasis>: e.g. <emphasis>Expenses:Tax</emphasis>
  • Hyphens and dashes:
To represent a negative number or subtraction:
The typographically correct symbol to use is − (U+2212, &minus;). The ASCII hyphen-minus - (U+002d) is commonly used and is also fine. Whichever you use, be consistent, at least on the whole page.
Examples:
Number negative 1 (−1): &minus;1
Formula GROSS_SALE − TOTALBUY: GROSS_SALE &minus; TOTALBUY
See http://www.thepunctuationguide.com/index.html for guidance on using English language punctuation, including &ndash; and &mdash;.
  • In the current state of this page there are many more. Have a look at the recently reworked chapters. If you have some free time, add them here.

Graphics conventions

all screenshots of the GnuCash windows must be captured under a GNOME Desktop environment with the following settings:

  • GNOME desktop environment
  • Clearlooks theme
  • text besides icon
  • font: Sans. 9 point for application and 11 point for window title