Difference between revisions of "Documentation Improvement"

From GnuCash
Jump to: navigation, search
(Images and screenshots - editorial corrections to improve readability)
m (After Merge: Verification: typo)
 
(197 intermediate revisions by 6 users not shown)
Line 1: Line 1:
These instructions describe the process to change both the ''Tutorial & Concepts Guide'' and the ''Help'' manuals as well as other parts of GnuCash documentation.  
+
[[Category:Documentation Development]]
 +
These instructions describe the process to change the ''Tutorial & Concepts Guide'' and the ''Help'' manuals. Finally they should consist of:
 +
:A: Technical Refeference: Help, in future: Manual
 +
:B.1: didactical Tutorial
 +
:B.2: task oriented Guide
  
If you are interested in translating the documentation, you should read [[Translation#Translating_the_GnuCash_Guide_and_Help|Translating the GnuCash Guide and Help]], too.
+
If you are interested in translating the documentation, you should also read [[Documentation Translation]].
 +
 
 +
For coordination of changes see [[Documentation Schedule]].
  
 
==Preface and Introduction -- What to expect==
 
==Preface and Introduction -- What to expect==
  
The documentation update process uses the same software management tools that are used for updating 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.
+
The documentation update process uses the same software management tools that are used for updating the program itself. This ensures that changes are made consistently and reliably. This includes using a [{{URL:wp}}Version_control version control] system (VCS)'' to coordinate contributions from disparate sources, as well as using [{{URL:wp}}DocBook DocBook], a semantic markup language for technical documentation based on ''eXtended Markup Language (XML)'' for the actual edits. It also requires contributors to check their contributions for compatibility by ''compiling'' the documentation before final submission.  
  
Since others could be making changes to the documentation at the same time you are, the GnuCash documentation process employs a ''version control system (VCS),'' called ''git'' to coordinate the disparate contributions. ''Git'' ensures that your changes and those of any others are incorporated efficiently into one final set of source files.
+
'''These aspects require that documentation contributors learn and use several specialized tools to engage the process.'''  
  
Before you begin editing the documentation, you need to inform others of your intention to edit the documentation. You do this for GnuCash documentation by ''submitting a bug'' using the online bug tracking system, [https://bugzilla.gnome.org/ bugzilla]. There, you add a Documentation bug for GnuCash, which allows others to see what the problem is, and to offer insight or suggestions on fixes.
+
The tools and the process are outlined in this page. For background on these tools, see [[Build_Tools|Build Tools]].
  
To actually begin editing, you must first ''obtain a copy of the full set of the most recent documentation''. You can obtain a full set using 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/].
+
Any changes you make will be inserted into local copies of the source documentation files and subsequently transferred to the main documentation set. 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.
 
 
Any changes you make will be inserted into your local copies of the source documentation files and subsequently transferred to the main documentation set. 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.
 
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.
Line 25: Line 29:
 
It may be helpful to become familiar with the references given in the [[Documentation_Update_Instructions#References_to_Supporting_Technologies_Used|REFERENCES]] section below.
 
It may be helpful to become familiar with the references given in the [[Documentation_Update_Instructions#References_to_Supporting_Technologies_Used|REFERENCES]] section below.
  
==The Make Utility==
+
==Setting Up Your System==
Like the programs, the documentation is built using the '''make''' utility.
 
  
In the ''make'' build system there are three important directories:
+
To begin changing the documentation, you will need to set up your system with the proper software.
* 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.
+
===Required Software===
 +
You will need the following software:
 +
* To manage your changes of the source text, you will install the ''git'' version control system. See [[Git]] for more on this.
 +
* To edit the source files, you will need to have a ''text editor''. Any text editor will do, as long as it can save your files without extra markup. But some editors offer Syntaxhighlighting and perhaps other specific tools for Docbook or XML.
 +
* To use the build system (<tt>make</tt> commands etc.) see ''Requirements'' in the [https://github.com/Gnucash/gnucash-docs/blob/maint/README#L19 README] file.
 +
* To illustrate your text with [[#Screenshots and Images|Screenshots and Images]], you can use
 +
** for '''diagrams:''' any [https://en.wikipedia.org/wiki/Scalable_Vector_Graphics SVG] able drawing program like OfficeDraw (available from [https://www.libreoffice.org/ LibreOffice] or [https://www.openoffice.org/ OpenOffice]),
 +
** for '''screenshots:'''
 +
*** ''creation:'' the built in <code>PrintScreen</code> of your OS or desktop environment,
 +
*** ''manipulation:'' The script  <tt>/util/adjust-dpi.sh</tt> uses the following programs
 +
**** <tt>identify</tt>—and <tt>convert</tt> in other instructions—from [https://www.imagemagick.org ImageMagick], a nice toolset to manipulate images or query their parameters,
 +
**** <tt>awk</tt> from '''gawk''',
 +
**** <tt>bc</tt> from '''bc''', but the later two are in most cases already installed.
 +
*** ''maintenance:'' [http://optipng.sourceforge.net/ OptiPNG] should be run once on new png files, also in stylesheets.
 +
;To control the resulting output:
 +
:;html: any ''web browser''—This is the ''minimum requirement''.
 +
:;docbook: ''Gnome'''s <tt>Yelp</tt>—This is desired.
 +
::In theory also '''KHelpcenter''' is usable, but nobody provided the proper configuration.
 +
:;PDF: any ''PDF viewer''—This is recommended.
 +
:;epub, mobi: [https://calibre-ebook.com/ <tt>calibre</tt>] can display these mobile formats.
  
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.
+
===Initial Steps===
 +
To work on the documentation we'll need two base directories:
 +
* a directory to contain the documentation sources, we'll name ''src'' throughout this page, though you're free to name it as you like. Note you don't have to create this directory manually, it will be created while obtaining the documentation sources.
 +
* a directory to hold the documentation that will be generated from the sources. We'll call this directory ''build''.
  
The ''installation'' directory is the location where the generated objects should finally end up when using ''make install''.
+
To avoid potential issues while sending your future changes for inclusion to the GnuCash project it's strongly advised to keep the ''build'' directory '''outside''' of the ''src'' directory. This page will suggest and consistently use the following directory structure:
  
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:
+
<SyntaxHighlight lang="sh">
* Both the Help & Guide
+
<base>/
* Either the Help or Guide
+
    gnucash-docs/
* Just the Help or Guide for a specific language
+
        src
As building the documentation can take a while, it is best to only build what is needed for your changes.
+
        build
 +
</SyntaxHighlight>
  
Typical '''targets''' of the ''make target'' command used for the documentation are:
+
<base> can be any path in your file system you can write to. Throughout this page we will be using '''$HOME/code''', that is a directory named code in your home directory. So the above will become
  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:
+
<SyntaxHighlight lang="sh">
  make install              # See [[#Step 11 Test Documentation in Linux]].
+
$HOME/
 +
    code/
 +
        gnucash-docs/
 +
            src
 +
            build
 +
</SyntaxHighlight>
  
===Installing make===
+
;Note: There is a reason we inisist on keeping your ''build'' directory outside of your ''src'' directory. If you don't, all of the build artefacts will be seen by git in your source directory. In that case you have to be extra careful not to include these build artefacts in the patches or PRs you create later on. If you understand this and know for yourself how to avoid this (like by setting the proper exclude rules for git) you can ignore this advice. Otherwise, please stick to this rule.
  
* Linux: <code>make</code> is usually already installed as part of the default installation packages.
+
With that out of the way, you can now follow instructions in [[Initializing_Documentation_Build_Environment|Initializing Documentation Build Environment]] to create the directory structure above with the source files in place and ready to be edited.
* Mac OS X: <code>make</code> and <code>git</code> are provided by either Xcode or the Xcode '''command-line tools'''. To update the documentation, it is not necessary to install the full Xcode package which is currently a download of over 4 GBs. On MacOS 10.8 and later the system should offer to Install just the '''command line tools''' when you issue a command that they supply; <tt>make</tt> or <tt>git</tt> issued in Terminal should do it. If that doesn't work you'll need to download the appropriate command-line tools package from [https://developer.apple.com/download/more/ Apple\'s developer website] where you'll need to sign in with your Apple ID and agree to some terms and conditions if you haven't already set up a developer account.
 
* Windows: It is probably possible but complicated to update the documentation in Windows. [[Windows/Development]] may help. It may be easier to install Linux in a virtual machine like VirtualBox instead.
 
  
==The Documentation Change Process -- What and How it happens==
+
You likely will also follow these steps to install a few additional tools:
 +
* To check your changes, you will use the ''make'' utility to compile the documentation locally.
 +
:See [[The_Make_Utility|The Make Utility]] for more on using and installing make.
 +
* To test the linkages between GnuCash and help files in Linux, see [[Test_Documentation_in_Linux|Test Documentation in Linux]].
  
 +
==The Documentation Change Process==
 
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.
 
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.
 
'''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.
  
 +
===<span id="CreateBug"></span> Create a Place to Attach and Discuss Your Changes===
  
===Step 1 Create a Bugzilla Bug for the Documentation Change===
+
This can be
# Create a [http://wiki.gnucash.org/wiki/Bugzilla bugzilla] bug if one does not already exist
+
* an (existing or new) ''enhancement request'' "bug" in [[Bugzilla]] to discuss the theory like constrains and other relations;
#* At this [https://bugzilla.gnome.org/createaccount.cgi URL], register yourself to create an account.
+
* for collaborative work like collecting of relations a wiki page <tt>''foo''-draft</tt> can be the better choice.
#* After your account has been created, Login to the [https://bugzilla.gnome.org/enter_bug.cgi?product=GnuCash section of bugzilla reserved for GnuCash].
+
* finally a ''[[Setup_for_Pull_Requests|pull request]] (PR)'' on github.
#* Enter your userid and password and press 'login'.
+
 
#* After logging in you are at [https://bugzilla.gnome.org/enter_bug.cgi this page] and you can start the bug creation process by answering the questions on the page.
+
;Note the bug or PR number and title: You will be listed as wanting to be notified any time there is an update to the bug.  You can monitor it until it is confirmed and applied.
#** For Bug Version, most commonly use '''git-maint''', which is used to update the documentation on existing GnuCash features. If you are documenting a new feature (for example, a feature only in a future stable release), use '''git-master'''. See [[Git#Branches|Git - Branches]] for more on this.
+
:Ideally you would reuse type, number and title in you commit messages.
#** 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.
 
# Note the bug number. You will be listed as wanting to be notified any time there is an update to the bug.  You can monitor it until it is confirmed and installed.
 
 
 
===Step 2 Clone the Documentation===
 
Cloning the documentation copies the most current version of the documentation to your local computer, where you will be able to make your edits. GnuCash uses ''git'' to manage this.  
 
 
 
'''Note:''' In order to use these instructions, you must have [[https://git-scm.com/ git]] installed.
 
 
 
*If you are on a Linux computer, the system will instruct you to download and install the package.
 
*If you are on Windows, you will see something like:
 
:<tt>'git' is not recognized as an internal or external command, operable program or batch file.</tt>
 
 
 
If you are new to using git, you may find it useful to read [[Git_For_Newbies|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|Git for GnuCash]] 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.
 
 
 
First, change to your preferred local source code folder.
 
  cd /home/$USER/code
 
 
 
Next, use the ''git clone'' command 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
 
 
 
This will copy the documentation to your computer into the folder gnucash-docs.
 
  
===Step 3 Generate configure Script===
+
===<span id="UpdateLocal"></span>Update Your Local Copy===
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.
+
Since others could be making changes to the documentation at the same time you are, the GnuCash documentation process employs ''git'' to coordinate the disparate contributions. ''Git'' ensures that your changes and those of any others are incorporated efficiently into one final set of source files. See [[Git]] to learn about using ''git''. ''This section assumes that you have already obtained a clone of the GnuCash repository, as outlined in [[#Setting Up Your System|Setting Up Your System]].''
  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.
 
  
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:
+
Before you begin editing, you must make sure that your local copy is up to date and aligns with the GnuCash repository by following the instructions at [[An_Introduction_to_Git#Sync_your_local_master_or_maint_from_upstream_.28Pull_Requests.29|An Introduction to Git]].
  sudo apt-get install autoconf libtoolize automake xsltproc
 
  
As a rule of thumb, autogen.sh should be run
+
===<span id="IDLoc4Change"></span>Identify Location for Changes===
* the first time you want to initialize the build system and sometimes
+
GnuCash stores documentation in one master sequence, but reformats the information in different ways for different platforms. When you build the documentation, you create a copy in final format. To make changes, you need to edit the local repository files, not the build directory files. Once you have located the correct source files, you must identify the passages that need to be changed. Your changes should roughly follow the [https://developer.gnome.org/gdp-style-guide/ GNOME Documentation Style Guide] of the [https://wiki.gnome.org/DocumentationProject/ GNOME Documentation Project].
** you updated at least one of the in <tt>sudo apt</tt> from above mentioned packages or
 
** after changes are made in <tt>configure.ac</tt> or <tt>Makefile.am</tt> 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.
 
  
===Step 4 Make a Build Directory Structure and the Makefiles===
+
'''Read the documentation carefully to find exactly where your change belongs.'''  
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
 
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.
 
  
 
The English '''Help Manual''' source XML files are in
 
The English '''Help Manual''' source XML files are in
:/home/$USER/code/gnucash-docs/help/C
+
:$HOME/code/gnucash-docs/src/help/C
 
The English '''Tutorial and Concepts Guide''' source XML files are in
 
The English '''Tutorial and Concepts Guide''' source XML files are in
:/home/$USER/code/gnucash-docs/guide/C
+
:$HOME/code/gnucash-docs/src/guide/C
 
The non-english files are in the corresponding locations with '''C''' replaced by a 2 character language code.
 
The non-english files are in the corresponding locations with '''C''' replaced by a 2 character language code.
  
It will be useful to have either a printed copy or a PDF copy [3] of  
+
It may be useful to have either a printed copy or a PDF copy [3] of  
 
the documentation available for reference.  The PDF is often useful,  
 
the documentation available for reference.  The PDF is often useful,  
 
because it allows using FIND (ctrl-F) to search for key words.  This  
 
because it allows using FIND (ctrl-F) to search for key words.  This  
Line 155: Line 125:
 
interested in has already had a mention or treatment.
 
interested in has already had a mention or treatment.
  
===Step 6 Draft your Update in a Text File===
+
===<span id="DraftChanges"></span>Draft Your Changes===
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]].
+
If your changes are few and easily formulated, you should be able to make your changes directly in the source 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.  
+
If your changes are more extensive, you may find it helpful to develop your ideas in a separate temporary text file. If you use this approach, you will need to insert your changes into the XML file(s) affected. Doing this might be easier by using a [https://en.wikipedia.org/wiki/Comparison_of_XML_editors specific XML Editor]. Additional resources for XML are listed in the [[#References to Supporting Technologies Used|References]] section for this step.  
  
===Step 7 Place the Draft Changes in XML Files===
+
Note: Remember to 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.
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.
+
The source documents are saved in the XML flavour of [[Glossary#D|DocBook]] code, so all changes need to follow those formatting rules. ''DocBook'' enforces strict rules about tags and markup, so be sure to make your changes fit the XML tags in the manner of the existing documentation.  
  
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.''
+
;Note: It is ''not'' necessary to use comments to denote the start or end of your source modifications. The version control system is used to track changes.  
  
It is ''not'' necessary to use comments to denote the start or end of your source modifications. The version control system is used to track changes. One can use the git history to see what has changed. There are graphical tools like gitk or the [https://github.com github] website that help you visualize these changes.
+
====Conventions====
 +
* You can find a complete reference to DocBook in [{{URL:dbk-tdg}}/docbook.html The Definitive Guide]. Search for <q>II. Reference</q> for the ''complete alphabetical list''.
 +
* But for beginners the element lists ''grouped by their function'' [{{URL:dbk-tdg}}/ch02.html Chapter 2: Creating DocBook Documents] is better. Ignore the confusing first part of the page and search for <q>Logical Divisions</q>.
 +
* Elements  of the '''graphical user interface''' (GUI) should have the respective markup e.g.for a label: <code><guilabel>Accounts</guilabel></code>. A incomplete list of gui elements:
 +
::accel, guibutton, guiicon, guimenu, guimenuitem, guisubmenu, keycap, keycode, keycombo, keysym, menuchoice, mousebutton, shortcut.
 +
:See [https://tdg.docbook.org/tdg/{{DocbookVersion}}/docbook.html DocBook Guide] for more detail.
  
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.
+
;Entities: are the <q>global abbreviations</q> in DocBook and ''should be used wherever possible''. They are usually ''defined'' in the form <Syntaxhighlight lang="xml"><!ENTITY appname "GnuCash"></Syntaxhighlight> in a DTD and ''used'' in the source docs like <Syntaxhighlight lang="xml"><title>&appname; Documentation</title></Syntaxhighlight>
 +
:There are several levels of definitions:
 +
:;W3C: usually part of the package <tt>dokbook-dtd</tt> contain already entities for many special symbols like mathematical or typographical…
 +
:: See the [https://www.w3.org/2003/entities/2007/w3centities-f.ent unified alphabetical list at W3C] to '''avoid overwriting''' or
 +
:: select detailed lists from [https://www.w3.org/2003/entities/2007doc/Overview.html XML Entity Definitions for Characters (3rd Edition)].
 +
:; Gnucash-docs: Our main DTD <tt>gnc-docbookx.dtd</tt> got some modularization. We separated GUI elements in a language agnostic <tt>gui-struct.dtd</tt> and siblings for each language like <tt>gui-C.dtd</tt> or its translation <tt>gui-<language>.dtd</tt>.
  
Review the inserted and corrected text to verify that it is presented within the proper XML tags, using existing tags as a guide.
+
;File inclusion: ''Since GnuCash 3.3'' the documents use <tt>XInclude</tt> <SyntaxHighlight lang="xml">
 +
<xi:include href="Help_ch_Intro.xml" />
 +
</SyntaxHighlight> instead of <tt>system entities</tt> like <SyntaxHighlight lang="xml"> <!ENTITY SYSTEM ...></SyntaxHighlight> and most other <code><!ENTITY ...></code> elements moved in the new [{{URL:wp}}Document_type_definition Document Type Definition] (DTD) [https://github.com/Gnucash/gnucash-docs/blob/maint/docbook/gnc-docbookx.dtd gnucash-docs/docbook/gnc-docbookx.dtd] and its siblings in the same folder.
 +
:'''Now''' ''each file'' needs a header <SyntaxHighlight lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<!DOCTYPE book SYSTEM "gnc-docbookx.dtd">
 +
</SyntaxHighlight> to be syntactical correct and find the entities. Instead of <tt>book</tt> it can also be any other type like <tt>chapter</tt>, <tt>appendix</tt> …
  
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.
+
;ID attributes: Many elements can contain an inside of the document ''unique'' <tt>id="chapter-more-specific-context"</tt> attribute. This will serve as target for any links — internal or for [[#Telling the Program of a New Help Context]]. So each element, which is referenced from inside or outside (GnuCash's Help context) requires one. That includes also elements, for which ''lists'' a generated in some target formats: Tables, Figures, ...
 +
:Additional they can be used to name the pages of the html output: <tt>Getting_Started.html</tt> might look nicer than <tt>pt01.html</tt>.
 +
:;Conventions: Lowercase, hyphenated terms, where the first stands for the chapter.
 +
:;Command to grep current definitions: From the top source directory run <syntaxhighlight lang="sh">
 +
grep -inrF "id=" --include="*.xml" --include="*.po" manual/C/
 +
</syntaxhighlight> to get the list from the english manual. The pattern "*.po" is currently only required for Italian.
 +
:;Commands to grep current internal references: From the top source directory run <syntaxhighlight lang="sh">
 +
# the usual way
 +
grep -inrF "linkend=" --include="*.xml" --include="*.po" manual/C/
 +
# some are behind URLs like https://code.gnucash.org/docs/
 +
grep -inrF "url=" --include="*.xml" --include="*.po" manual/C/
 +
# Other dependencies: xinclude's href and imagedata fileref
 +
grep -inrF "ref=" --include="*.xml" --include="*.po" manual/C/   
 +
</syntaxhighlight>
  
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.
+
;Titles: They should be  unique, because the <book> has one <q>List of Tables</q> and a <q>List of Figures</q>, which are visible in HTML. One possibility to get consistent entries is the additional use of the element <q>titleabbrev</q>. For example, the representation of <syntaxhighlight lang="xml"><titleabbrev>Account Tree - File-Menu</titleabbrev></syntaxhighlight> in the <q>List of Tables</q> is more readable and looks better than <syntaxhighlight lang="xml"><title>Account Tree - File-Menu - Access to file, account operations and printing</title></syntaxhighlight> There are more in [[Docbook Conventions]].
  
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,
+
;Linking: [http://www.sagehill.net/docbookxsl/Db5Tools.html#Db5LinkExamples Examples]
then rerun autogen.sh and ../configure.sh. There is no need to update Makefile.in as this is generated by running autogen.sh.
+
:;Tip: If you do not plan to replace the URL by another text, use the short form <syntaxhighlight lang="xml" inline><link url="https://en.wikipedia.org/wiki/URL" /></syntaxhighlight> instead of <syntaxhighlight lang="xml"><link url="https://en.wikipedia.org/wiki/URL">https://en.wikipedia.org/wiki/URL</link></syntaxhighlight> The result is the same.
  
;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.
+
;URLs: Because they will be used in several translations, put them as entities in [https://github.com/Gnucash/gnucash-docs/blob/maint/docbook/gnc-docbookx.dtd#L61 docbook/gnc-docbookx.dtd] to allow an easier update, if they change. The previous example would become
 +
:# docbook/gnc-docbookx.dtd: <syntaxhighlight lang="xml">
 +
<!ENTITY url-wp-en "https://en.wikipedia.org/wiki/">  <!-- Append the desired topic -->
 +
</syntaxhighlight>
 +
:# and in your text: <syntaxhighlight lang="xml">
 +
More details in <link url="&url-wp-en;URL" />.
 +
</syntaxhighlight>
 +
:resulting in
 +
::More details in [https://en.wikipedia.org/wiki/URL https://en.wikipedia.org/wiki/URL]
 +
;Textual Conventions:
 +
:;Do not use vague formulations: Instead of "Previous versions [...]" use "Until version X.Y[.Z] [...]". But as the current docs are no archive, the text body should describe the ''current version of Gnucash''. On important changes add a footnote "Before version x.y it was …" to wake up experienced users to register the change.
  
You can find an introduction to [http://www.docbook.org DocBook] in [http://docbook.org/tdg51/en/html/ch02.html Creating DocBook Documents].
+
====<span id="DraftAddRemove"></span>Adding or Removing Files====
 +
If you are adding or deleting files from the documentation, for example adding a new chapter or appendix, you will need to announce it to several parts of the system to ensure that these new or deleted files get handled properly.
  
===Step 8 Validate XML Changes===
+
These are:
'''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 '''base XML file''' (i.e., ''gnucash-guide.xml'' or ''gnucash-help.xml''). This file includes <SyntaxHighlight lang="xml">
 +
<xi:include href="Book_type_Name.xml" />
 +
</SyntaxHighlight> declarations for each source file in the documentation. You must edit this XInclude list to reflect the changes you have made to the file list, where
 +
#*Book is either Help or empty, (TODO: should be dropped)
 +
#*type should be either ch[apter] or app[endix],
 +
#*Name describing its content.
 +
# Tell the build system about the change. You do this by inserting the name of your added file to or removing the name of your deleted file from the file list in '''CMakeLists.txt''' located in the same folder as the ''base XML file''.
 +
#;Note: There are CMakeLists.txt files in each of the language folders as well as in the base documentation folder. Make sure you edit the proper copy--that is, the copy in the specific language folder you have edited.
 +
# Tell [[Git]] to add/remove the file to/from the repository: <SyntaxHighlight lang="sh">
 +
git add ${MODULE}/${LOCALE}/${FILENAME} # ${MODULE}={guide|help}; ${LOCALE}={C|de|it...}; ${FILENAME}=file to add
 +
git rm ${MODULE}/${LOCALE}/${FILENAME} # to remove it - also from your filesystem! See 'git help rm' for other options.
 +
</SyntaxHighlight>
 +
;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 (<tt>$HOME/code/gnucash-docs/src/help/C</tt> or <tt>$HOME/code/gnucash-docs/src/guide/C</tt>) to determine what changes, if any, need to be made to modules outside your original assessment.
  
''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.
+
==== Telling the Program of a New Help Context ====
 +
In [https://github.com/Gnucash/gnucash/blob/maint/gnucash/gnome-utils/gnc-ui.h gnucash/gnome-utils/gnc-ui.h] are 2 important sections:
 +
# Help Files: <Syntaxhighlight lang="C">
 +
/** Help Files ******************************************************/
 +
:
 +
#    define HF_GUIDE        "gnucash-guide"
 +
#    define HF_HELP          "gnucash-help"
 +
:
 +
</Syntaxhighlight>
 +
# Links ''in'' the Help Files ('''id'''): <Syntaxhighlight lang="C">
 +
/** Links in the Help Files *****************************************/
 +
#define HL_USAGE            "usage"
 +
:
 +
</Syntaxhighlight>
  
In a Terminal, change directory to the place in the '''build''' directory structure where the changed modules are located:
+
Ask a developer to
 +
# add your chapter, section, table or whatever <code>id</code> to the list and
 +
# use it together with its <tt>HF_*</tt> as help context in <tt>gnc_gnome_help(file_name, anchor)</tt> or where else it is associated GUI elements.
 +
;Fixme: Ways to find the ids generally in the code sources?
  
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>:
+
===<span id="ValidateChanges"></span>Validate Your Changes===
 +
;xmllint: The program '''xmllint''' is used to test that your xml file has no '''syntax errors''' or '''incorrect references''' to internal sections. It is part of the package '''libxml'''.
 +
:;Tip:Some XML aware editors have a builtin ''Validate'' command to run xmllint direct on the ''currently opened file'' and jump to the first error.
  
To validate all the guide xml files for only the ''C'' (English) language:
+
;make *check: For your convenience the build system comes with built-in rules to run <tt>xmllint</tt>. It is run by executing '''make [something-]check''' in the top level build directory. Depending on the '''[something-]''' part in that command one or more documents will be checked.
  cd /home/$USER/code/gnucash-docs/'''build'''/guide/C
+
:For example, if you had downloaded the documentation files to a directory called <tt>$HOME/code/gnucash-docs</tt> and created a build directory called <tt>$HOME/code/gnucash-docs/build</tt>:
To validate all the guide xml files for all languages:
+
:#To validate one or more documents, first go to the top level ''build'' directory <SyntaxHighlight lang="sh">
  cd /home/$USER/code/gnucash-docs/'''build'''/guide
+
cd $HOME/code/gnucash-docs/build
To validate all the guide and help xml files:
+
</SyntaxHighlight>
  cd /home/$USER/code/gnucash-docs/'''build'''
+
:#From there to validate
 +
:#* all the ''guide'' xml files for only the ''C'' (''English'') language: <SyntaxHighlight lang="sh">
 +
make C-gnucash-guide-check
 +
</SyntaxHighlight>
 +
:#* all the guide xml files ''for all languages'': <SyntaxHighlight lang="sh">
 +
make gnucash-guide-check
 +
</SyntaxHighlight>
 +
:#* ''all the guide and manual'' xml files: <SyntaxHighlight lang="sh">
 +
make check
 +
</SyntaxHighlight>
 +
:So generally the check parameter to make is of the form ''<language>-<document>-check''. You can omit ''<language>-'' or ''<language>-<document>-'' to widen the scope of the check.
 +
:;Tip: If using ninja, you can list all the ''check'' targets by <SyntaxHighlight LANG="sh" inline>
 +
ninja -t targets | grep check
 +
</SyntaxHighlight>
  
Then:
+
;Note: xmllint works by loading the main ''gnucash-{guide|help}.xml'' file of the current document's directory together with all other xml files referenced in this main file and then checks all the files.
  make check
 
  
If there are any errors, fix them and repeat this step until no errors are found.
+
====xmllint output====
 +
* 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 there are any errors, fix them and repeat this step until no errors are found.
 +
* If you are unable to fix an XML error, ask either using [[IRC]] or, see [[Mailing_Lists]], on <tt>gnucash-devel</tt>.
  
If you are unable to fix an XML error, then go to [[Mailing_Lists]] and subscribe to the developers email list '''gnucash-devel@gnucash.org'''. If you are not a subscriber, then your email will wait for the list manager to find  the time to address emails received from
+
====make *pdf====
non-subscribers and you will not receive replies from developers unless they explicitly copy you. Send an email to gnucash-devel@gnucash.org asking for help. Provide as much information as possible, including the results of the <tt>xmllint</tt> command (I.e. the output from  ''make check'').
+
;Tip: After passing <code>make check</code> it is a good idea to also run <SyntaxHighlight lang="sh">
 +
make <language>-<document>-pdf
 +
</SyntaxHighlight>
 +
:The <tt>xsltproc</tt> command used there is stricter than <SyntaxHighlight lang="sh" inline>make check</SyntaxHighlight> with the current settings. It will
 +
:* '''warn''' if it finds '''unresolved ID reference'''s and
 +
:* '''abort''' if a table row has more columns than declared.
  
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).
+
====After Adding, Moving or Deleting Files====
 +
Verify a tarball
 +
# can be built <SyntaxHighlight lang="sh">
 +
cd ${BUILDDIR} # Adjust this
 +
make distcheck
 +
</SyntaxHighlight>
 +
# contains your new files.
 +
After success you can remove <tt>gnucash-docs-{{Version}}.tar.gz</tt> from your ${BUILDDIR} again.
  
===Step 9 Ensure Only the Changes you Expect Have Been Made===
+
===<span id="EnsureExpected"></span>Ensure Only Expected Changes Have Been Made===
This following command will show any changes to unstaged files
+
You should double check that there are no accidental changes to the documentation.
  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===
+
The following command when run in the ''src'' directory will show any changes to unstaged files
 +
<SyntaxHighlight lang="sh">
 +
git diff
 +
</SyntaxHighlight>
 +
Git status (also run in the ''src'' directory) will list all files with differences to the last commit, in categories staged, unstaged, and unknown to git but not matching an ignore pattern.
 +
<SyntaxHighlight lang="sh">
 +
git status
 +
</SyntaxHighlight>
  
After the XML has been tested for integrity using xmllint (make check) and the  
+
===<span id="Proofread"></span>Proofreading===
difference file has been determined to contain correct changes and only
+
After you have tested the integrity of the XML using xmllint (make check) and have verified that the  
those, then the Guide or Help must be recreated in HTML and the results
+
difference file shows the correct changes, it depends on your OS/installed software, how to proceed
examined in your browser to verify that the online version presents an
+
;Not very fast, but simple under Linux: run Gnucash after installing your version of the documentation:
appearance and reads as expected.
+
: Install and run your version <Syntaxhighlight lang="sh">
 +
cd ${BUILDDIR} # adjust this
 +
sudo make install
 +
gnucash
 +
#choose a component from the Help menu
 +
</Syntaxhighlight> This is also the preferred method to test the context sensitive help.
 +
;Fast under Linux:
 +
:;but more typing: ''KHelpcenter'' and Gnomes help viewer ''yelp'' can both display docbook documents: <Syntaxhighlight lang="sh">
 +
yelp $PREFIX/share/gnome/help/gnucash-help/$LANG/gnucash-help.xml # adjust:
 +
# 1. $PREFIX (/usr/local/) or just use your ${BUILDDIR},
 +
# 2. $LANG (/C/)
 +
# 3. document help or guide
  
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:
+
# or after we fixed the path for our DTD:
  cd [appropriate directory or sub-directory within the '''build''' directory structure]
+
khelpcenter $PREFIX/share/gnome/help/gnucash-help/$LANG/gnucash-help.xml
  make html
+
# If we create .desktop files this will become easier.
 +
</Syntaxhighlight>
 +
:;or less typing: If you
 +
::# used a standard path for the INSTALLDIR—e.g. did not change CMAKE_INSTALL_PREFIX in your build configuration—
 +
::#:If you changed it, you can insert it into <tt>XDG_DATA_DIRS</tt>. To get those path on each login, Linux users can insert the command e.g. into <tt>$HOME/.bashrc</tt>: <syntaxhighlight lang="sh">
 +
# Integrate my test directory
 +
export XDG_DATA_DIRS=${HOME}/test/share:${XDG_DATA_DIRS}
 +
</syntaxhighlight> if your CMAKE_INSTALL_PREFIX is <tt>${HOME}/test</tt>.
 +
::# are running your shell in the same language as the document,
 +
:: you can also use the shorter <syntaxhighlight lang="sh">
 +
yelp ghelp:gnucash-help
 +
</syntaxhighlight> or start gnucash and select it from the help menu.
 +
:;Note: There are plans to use in future versions
 +
::# <tt>help:</tt> instead of <tt>ghelp:</tt> which uses a different directory structure and
 +
::# <tt>manual</tt> instead of <tt>help</tt> as document name.
  
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.
+
====In HTML and Other Formats====
 +
The easiest way to check your changes is to view the HTML version in your browser. You should also review other formats as they have their own peculiarities:
 +
* If you are using non-latin writing, are the fonts right in pdf?
 +
* Are images displayed correctly?
 +
* Is the page layout OK in ebooks?
  
The built html files with be placed in an automatically created directory, which if using the example directories will be:
+
The Guide or Help must be recreated in HTML and the results
  /home/$USER/code/gnucash-docs/build/<guide|help>/C/gnucash-<guide|help>
+
examined in your browser to verify that the online version appears and reads as expected.
  
Review the results in your browser; if you need to make changes, do so, then check, rebuild and review again.
+
Build the Guide or Help file in HTML. Use any of the ''make'' commands below in a terminal, to generate (part) of the documentation in a chosen language and format: <Syntaxhighlight lang="sh">
 +
cd ${BUILDDIR} # adjust this
  
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.
+
# In any of the commands below, replace html with pdf, epub or mobi to build that other format
  
To view the results in a web browser, in a file manager (or for Windows: Windows Explorer/File Explorer) double click on either:
+
# to build both guide and manual in all languages in html:
 +
make html
 +
# or to build only the guide in all languages
 +
make gnucash-guide-html
 +
# or to build only the help manual in all languages
 +
make gnucash-help-html
  
  /home/$USER/code/gnucash-docs/build/help/C/gnucash-help/help.html
+
# In the following commands you can replace C with any other language code we have a guide or help manual for
or
+
# or to build only the guide in English
  /home/$USER/code/gnucash-docs/build/guide/C/gnucash-guide/index.html
+
make C-gnucash-guide-html
 +
# or to build only the help manual in English
 +
make C-gnucash-help-html
  
 +
</Syntaxhighlight>
  
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.
+
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.
 
 
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, &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.
 
 
 
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&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.
 
  
====11.1 Install Development GnuCash Locally====
+
The built html files with be placed in an automatically created directory, which if using the example directories will be: <Syntaxhighlight lang="sh">
''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/code/gnucash-docs/build/share/doc/<language>/gnucash-<guide|help>
 +
</Syntaxhighlight>
  
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:
+
Review the results in your browser. [https://calibre-ebook.com/about Calibre] is a good choice as viewer for ebook formats (epub, mobi, ...).
* 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  
+
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.
  /home/$USER/code/gnucash-install
 
  
====11.2 Install Updated Documentation Locally====
+
To view the results in a web browser, in a file manager (or for Windows: Windows Explorer/File Explorer) double click on either: <Syntaxhighlight lang="sh">
 +
$HOME/code/gnucash-docs/build/share/doc/C/gnucash-help/help.html
 +
# or
 +
$HOME/code/gnucash-docs/build/share/doc/C/gnucash-guide/index.html
 +
</Syntaxhighlight>
  
Let's say you wish to build your modified documentation in
+
===<span id="AddExtras"></span>Add Extra Files===
  /home/$USER/code/gnucash-docs-install
+
Git automatically tracks changes to files it knows are part of the repository. However, if you have added any files that should be included in your commit (xml or others, for example, illustrations), add (stage) them with the command:
 
 
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&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.
 
 
 
====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
 
   git add path/to/file
 +
 
 
Note:  Do '''NOT''' add file(s) from your ''build'' directory structure.
 
Note:  Do '''NOT''' add file(s) from your ''build'' directory structure.
  
Line 314: Line 381:
 
   git checkout path/to/ignored-file
 
   git checkout path/to/ignored-file
  
===Step 13 Commit your Changes===
+
===<span id="PubAuthor"></span>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 [https://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.
 +
 
 +
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
 +
 
 +
===<span id="CommitChanges"></span>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 <syntaxhighlight lang="sh">
 
  git commit -a
 
  git commit -a
:('''-a''' also causes git to notice and commit any deleted files)
+
</syntaxhighlight>
or you can commit a few files at a time with  
+
:('''-a''' also causes git to notice and commit any ''deleted files'')
git add path/to/file
+
or you can commit a few files at a time with <syntaxhighlight lang="sh">
git commit
+
git add path/to/file1 [path/to/file2 …]
If you need to make further changes, you can update your commit instead of creating a new one with
+
git commit
  git commit -a --amend
+
</syntaxhighlight> If you need to make further changes, you can update your commit instead of creating a new one with <syntaxhighlight lang="sh">
But <tt>--amend</tt> should only be used as long, as you did not publish your commit by pushing it to some public github repository.
+
git commit -a --amend
 +
</syntaxhighlight> But <tt>--amend</tt> should only be used as long, as you did not publish your commit by pushing it to some public github repository.  
 +
;Exception: ''Only on your own, still open pull requests'' you are allowed to use <syntaxhighlight lang="sh">
 +
git commit -a --amend
 +
git push -f
 +
</syntaxhighlight>
  
 
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.
Line 330: Line 408:
 
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.
+
The '''release announcement''' is generated from the 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.
 
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.
 
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 <syntaxhighlight lang="sh">
  git log -p path/to/file
+
git log -p path/to/file
 
+
</syntaxhighlight>
===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====
 
<tt>git status</tt> 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 <tt>git add path/to/filename</tt> to register the changes and when you've fixed them all and added them to the index, use <tt>git commit</tt> 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 <tt>0001-Better-explanation-of-trading-accounts.patch</tt>.
 
 
 
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 '''<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.
 
  
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
+
===<span id="PullorPatch"></span>Create a Pull Request or a Patch===
 
+
Once you have finalized your changes, you will notify the developer team of your changes, either by creating a —recommend— [[Git#Pull_Requests|pull request]], or —less desired— by [[Preparing_A_Documentation_Patch|creating and uploading a patch]].
===Step 17 Attach Patch to Bug===
+
===After Merge: Verification===
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.
+
To avoid surprises after the release, you should verify one day after the merge of your pull request the nightly build:
 +
;All: browse {{BuildURL}}/docs/
 +
;Flatpak users: See [[Flatpak]] for how to enable the nightlies and update them.
 +
:Then run <syntaxhighlight lang="sh">flatpak run --command=sh org.gnucash.GnuCash
 +
yelp
 +
</syntaxhighlight>
 +
:If you watch <syntaxhighlight lang="console">
 +
I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
 +
/app/share/gnome/help/gnucash-help/de/Help_ch_Transactions.xml:3171: parser error : Entity 'ndash' not defined
 +
                &ndash; Importieren als eine neue Buchung. Manueller Eingriff er
 +
                      ^
 +
$
 +
</syntaxhighlight> or similar, and can not fix it, inform the flatpak maintainers.
 +
;Windows users: See [[Windows]] for how to enable the nightlies and update them.
 +
:Start the Program and open the docs from the help menu.
  
 
==References to Supporting Technologies Used==
 
==References to Supporting Technologies Used==
  
===Step 1===
+
:[1] https://wiki.gnucash.org/wiki/Bugzilla
[1]  http://wiki.gnucash.org/wiki/Bugzilla
+
:[2] https://github.com
 +
:[3]  http://www.jedit.org/
 +
:[4] https://en.wikipedia.org/wiki/DocBook
 +
:[5] https://www.docbook.org/  DocBook: The Definitive Guide
 +
:: Some Distributions have it as a package named like ''docbook-tdg''.
 +
:[6] https://www.tldp.org/LDP/LDP-Author-Guide/html/tools-edit.html
 +
:[7] https://www.netlingo.com/tips/html-code-cheat-sheet.php
 +
:[8] https://wiki.gnucash.org/wiki/Git
  
===Step 2===
+
==Additional Information==
[2] https://github.com
+
===Screenshots And Other Images===
+
====Desktop Themes for Screenshots====
===Step 6===
+
:Try to maintain consistency with existing images by using specific themes for your desktop environment.
[3]  http://www.jedit.org/
+
:Most current images are still from the GnuCash-2 series, where we used the [https://www.gnome-look.org/content/show.php?content=19527 Clearlooks] engine, which has been the default theme of [https://help.gnome.org/misc/release-notes/2.0/ GNOME 2] since version 2.12.
+
:So for GnuCash3+ we should use Gnome3's default theme "Adwaita".
===Step 7===
+
:If you are not on Linux, try to find a similar theme for your desktop.
[4]  http://en.wikipedia.org/wiki/DocBook
+
If you customized your desktop or are using a different environment,
 +
: create ideally a Linux VM with a Vanilla Gnome Desktop
 +
: or at least create a separate user like <tt>Gnucash User</tt> or similar—ideally one per language/region.
 +
::In theory you could also adjust the settings per session but practical you will find after days one detail you had forgotten to set properly in a serie of images.
 +
start a '''Gnome''' session for that user;
 +
:if you are not translating, you should use the default '''LANG=C''' with one exception:
 +
::As the US date format is confusing to almost all other readers, start GnuCash and set in
 +
::<tt>Edit->Preferences->Numbers, Date and Time->Date Format:</tt> '''ISO'''
  
[5]  http://www.docbook.org/  DocBook: The Definitive Guide
+
====Image Formats====
: Some Distributions have it as a package named like ''docbook-tdg''.
+
;Screenshots: are ideally submitted in ''.png'' '''format'''.
 +
:;Tip:
 +
::;Before capturing: Shrink the window size to the minimum to get the best result. If text gets truncated, file a bug against the GUI.
 +
::;While capturing:
 +
:# Often you can '''avoid cropping''' by selecting <tt>Scope: ''Active Window''</tt>
 +
:# Hold down the <code>Alt</code> keys because GTK3 else hides the '''accelerator marking'''s <code>_</code>.
 +
;Graphics showing relations: are best in ''.svg''. That would allow translators to replace in their copy the labels with their translation.
 +
;Callouts: images with annotations – are ideally created in [{{URL:wp}}GIMP GIMP]'s .xfc format with the
 +
:;screenshot: on the ''lowest level'' and
 +
:;each label: on a ''separate level''. That will allow ''you or translators'' to edit, move or resize the labels.
 +
:'''Translators''' can replace the screenshot and translate the labels. Finally add it in
 +
:;xfc: for future maintenance, translation creation …  and
 +
:;png format: to use in the docs
 +
:to the repo and link the png in the text.
 +
;Icons: are used in all project components: Program, Bundles, Documentation and Website. Best practises still need to be written.
  
[6]  http://www.tldp.org/LDP/LDP-Author-Guide/html/tools-edit.html
+
====Indexing====
 
+
To add your image to the <tt>List of Figures</tt> at the start of the ''Help'' or ''Tutorial and Concepts Guide'', put your screenshot in a figure tag, for example:
[7]  http://www.netlingo.com/tips/html-code-cheat-sheet.php
+
<syntaxhighlight lang="xml">
 +
  <figure pgwide="1">
 +
    <title>This text will appear as header and in the List of Figures</title>
 +
    <screenshot>
 +
      <screeninfo>640x480x256</screeninfo>
 +
      <mediaobject>
 +
        <!-- insert the imageobjects here -->
 +
        <caption><para>Optionally you can here add a longer description than in the title.
 +
          If not required, remove the caption element.</para>
 +
        </caption>
 +
      </mediaobject>
 +
    </screenshot>
 +
  </figure>
 +
</syntaxhighlight>
 +
:;screeninfo: Information about how and at what resolution a screen shot was produced, when it was produced, and by whom. We found this in 2022 and need to discuss our preferred content. Perhaps it is a good place to store the size here instead of running <tt>identify</tt> on each time the info is needed.
 +
:;textobject:Older parts have mistakenly a <textobject> instead of a figure title or a <nowiki><caption></nowiki>. For now move the content into the adequate tag. Only if you want to support
 +
::*blind people using a screenreader and
 +
::*users of [{{URL:wp}}Text-based_web_browser Text-based web browser]s
 +
::add a precise description of the image as textobject.
  
[8]  http://wiki.gnucash.org/wiki/Git
+
; Displaying pictures side by side
 +
: If you want to display pictures next to each other, they can be positioned in a small table with a single table line and two column. This solution is suitable if the images to be displayed have comparable dimensions, preferably the same height.
 +
: Please note that the parameter "width" for the image size must be set to 100%. This value refers to the size of the table cell and fits the image completely into the cell.
  
==  Screenshots and Images ==
+
;Finally check your entry in the index context: Build the html flavour and open its Table of Content. That is currently
Screenshots and images 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 maintain consistency with existing images. The [https://www.gnome-look.org/content/show.php?content=19527 Clearlooks] engine has been the default theme of [https://www.gnome.org/start/2.0/ GNOME 2] since version 2.12.
+
::guide/C/gnucash-guide/index.html
 +
::help/C/gnucash-help/help.html
 +
: in your build directory, but willl change with [{{BugURL}}/show_bug.cgi?id=798166 GnuCash docs should follow XDG help-system-spec.].
 +
:Scroll down to <tt>List of Figures</tt>. Is it
 +
:*unique and
 +
:*descriptive?
  
Screenshots and images added to the GnuCash documentation must fit '''two purposes''': ''video display'' (e.g. online) and ''paper printing'' (pdf creation). Each has its own way of determining width; video display defines image widths limits in terms of pixels, while print output sets limits on image size based on a ratio of image size and the image's ''dots per inch (dpi)''. To successfully prepare an image for each of these uses, you must use two <imageobject> tags, as shown below:
+
====Display and Print Targets====
 +
;Gnucash 4.10 change: The original instructions talked about <q>510px</q> wide, but images of that width are too narrow on modern large screens. Because on a "Full HD" monitor the normal page wide in yelp seems to be >={{Docs img-w}} this is the new default stored in [{{URL:GH}}Gnucash/gnucash-docs/tree/maint/docbook/gnc-docbookx.dtd#L82 docbook/gnc-docbookx].
 +
:* Older documents require a review of their <tt><imageobject></tt>s: If the '''width''' is
 +
::;&le; {{Docs img-w}}: remove <tt>width=&img-w;</tt> and—if it references the same file—the fo object;
 +
::;else: verify that the fo object has no width in px.
 +
::To get a list see the Tip below.
 +
:;Still unresolved: Sometimes
 +
::* images are indented as part of a list element or
 +
::* we want to display 2 images side by side.
 +
:: How can we tell that <tt>adjust-dpi.sh</tt> …?
 +
Screenshots and images added to the GnuCash documentation must fit '''two purposes''': ''video display'' by Gnome's Yelp or other browsers like Firefox and ''paper printing'' (pdf creation). Each has its own way of determining width:
 +
:;video display: defines image width limits in terms of '''pixels''', while
 +
:;print output: sets limits on image size based on a ratio of image size and the image's ''dots per inch ('''dpi''')''.
 +
Because we do not want to shrink the image itself, but want to limit the width of
 +
:image presentations on screen to {{Docs img-w}},
 +
:and 14 cm on paper, we get 2 different cases for our entry:
 +
;width <= {{Docs img-w}}: and insert: <syntaxhighlight lang="xml">
 +
      <imageobject>
 +
        <imagedata fileref="figures/Report_Screen.png"
 +
                  srccredit="your name" />
 +
      </imageobject>
 +
</syntaxhighlight>
 +
:;imagedata attributes:
 +
::;format: like <tt>format="PNG"</tt>is only required, if the filename extension is unknown by the processor. Please remove obsolete instances!
 +
:::See also: [{{URL:dbk-xsl}}GraphicSelection.html docbookxsl GraphicSelection], [{{URL:dbk-xsl}}GraphicFormats.html docbookxsl GraphicFormats]
 +
::;width, depth: If the viewport area (''width''|''depth'') is specified, but no content area (''contentwidth''|''contentdepth''), docbook sets ''scalefit=1'' resulting in zooming the image to viewportsize.
 +
;width > {{Docs img-w}}: Use two <imageobject> tags, as shown below: <syntaxhighlight lang="xml">
 +
      <imageobject role="html">
 +
        <imagedata fileref="figures/Help_Pref_AccntPeriod.png"
 +
                  srccredit="your name" width="&img-w;" />
 +
      </imageobject>
 +
      <imageobject role="fo">
 +
        <imagedata fileref="figures/Help_Pref_AccntPeriod.png"
 +
                  srccredit="your name" />
 +
      </imageobject>
 +
</syntaxhighlight>
 +
:;imageobject attributes:
 +
::;role:"'''html'''" refers to ''display'' presentation on screens (the width is limited to {{Docs img-w}}), while
 +
::: "'''fo'''" processor (FOP) prepares it for ''printing'' of <tt>pdf</tt>
 +
:Now the image will fit on display and we can continue to adjust it for printing.
  
            <imageobject role="html">
+
==== Adjusting an Image's Dots Per Inch ====
              <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 presentation on screens (the width is limited to 510px), while the "fo" attribute refers to pdf printing.
 
 
 
:When you take a screenshot for inclusion in the GnuCash documentation, it should not be resized to 510 pixels width. Instead you should leave it as is, and set the width attribute to 510 pixels for the "html" role. Note that the width tag is not necessary if the image has a width smaller than 510px.
 
 
=== Adjusting an Image's Dots Per Inch ===
 
 
You must take another step to prepare a screenshot for print output: you must set the dots per inch (dpi) correctly. The dpi defines an image's dot density, and thus its overall quality; the higher the dpi, the better the printed image quality. The printing size, dpi and image pixel dimensions are in this relation:
 
You must take another step to prepare a screenshot for print output: you must set the dots per inch (dpi) correctly. The dpi defines an image's dot density, and thus its overall quality; the higher the dpi, the better the printed image quality. The printing size, dpi and image pixel dimensions are in this relation:
  
Line 437: Line 569:
 
:If the screenshot you are going to add to documentation is wider than 850 pixels, you should increase the dpi above 144 so that its printed size remains less than 15 cm.
 
:If the screenshot you are going to add to documentation is wider than 850 pixels, you should increase the dpi above 144 so that its printed size remains less than 15 cm.
  
:The dpi of an image be changed in one of two ways:
+
;Tip: To query the properties of the existing images you can use <tt>Imagemagick</tt>s <tt>identify</tt> command: <syntaxhighlight lang="sh">
:# Open the screenshot in an image editor (like [http://www.gimp.org The Gimp]) and select Image->Print Size. In the dialog that opens, set the X and Y resolution to the desired dpi (check that the unit value is set to the desired value - normally pixels/in). Press "Ok" and save the image.
+
# for many details of one file:
:# A faster approach uses Imagemagick, a library for image manipulation. From a terminal window, issue the following command:
+
identify -verbose $FILENAME
  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 terminal window:
+
# or important infos about all files in the current directory:
 +
echo "Size [px] and Resolution of all files in the current directory:";
 +
for i in *.png; do identify -format "%w x %h %x x %y %U %f\n" $i; done;
  
ls *.png > list
+
# or to create a list of the images width:
for i in `cat list`; do convert -units PixelsPerInch -density 144 "$i" "$i"; done
+
touch width.lst;
 +
for i in *.png; do identify -format "%w %f\n" $i >> width.lst; done;
 +
# Output sorted descending by width, useful on changes of &img-w;:
 +
clear; sort -nr width.lst;
 +
# or by name, useful on review of text:
 +
clear; sort -k2 width.lst
 +
</syntaxhighlight> The <code>%</code> parameters are explained in ImageMagick's doc package.
  
:The first line creates the file "list" with a list of all png files in the current directory
+
===== Individual =====
:The second and third lines applies a dpi of 144 to all images listed in the "list" file
+
:The dpi of an image be changed in one of two ways:
 +
:# Open the screenshot in an image editor (like [https://www.gimp.org The Gimp]) and select Image->Print Size. In the dialog that opens, set the X and Y resolution to the desired dpi (check that the unit value is set to the desired value - normally pixels/in). Press "Ok" and save the image.
 +
:# A faster approach uses Imagemagick, a library for image manipulation. From a terminal window, issue the following command:<syntaxhighlight lang="sh">
 +
convert -units PixelsPerInch -density DPI IN OUT
 +
</syntaxhighlight>
 +
: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).
  
:Imagemagick lets you also see sizes and pixels per inch from the command line:
+
===== All at once =====
  identify -format "%w x %h %x x %y" IMAGE_NAME.FORMAT
+
====== New Method ======
 +
:For your convenience the bash script '''adjust-dpi.sh''' has been included in the ''gnucash-docs'' repository that automatically calculates and assigns 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:
 +
:<syntaxhighlight lang="sh">
 +
cd guide/pt/figures            # In the repo, NOT the build directory structure
 +
../../../util/adjust-dpi.sh
 +
</syntaxhighlight>
 +
:If that fails i.e. because [[#Required Software|dependencies]] are missing on your computer, you can still use the old method.
  
:For your convenience the bash script '''adjust-dpi.sh''' has been included in the gnucash-docs repository that automatically calculates and assigns 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:
+
====== Old Method ======
 +
:To ''convert the dpi'' of a bunch of images do this from a terminal window:
 +
:<syntaxhighlight lang="sh">
 +
for i in *.png; do convert -units PixelsPerInch -density 144 "$i" "$i"; done
 +
</syntaxhighlight>
 +
:This applies a dpi of 144 to all images of the current directory.
  
  cd guide/pt/figures            # In the repo, NOT the build directory structure
+
==== Optimize the Compression ====
  ../../../util/adjust-dpi.sh
+
The tool OptiPNG tries to minimize the size of png files lossless:
 +
<syntaxhighlight lang="sh">
 +
cd guide/pt/figures            # In the repo, NOT the build directory structure
 +
optipng ${FILENAME}            # <- One file or all:
 +
for i in *.png; do optipng $i; done
 +
</syntaxhighlight>
 +
If it is too hard for you, ask the developers in your pull enhancement request to do it for you.
  
: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, then rerun ''../configure'' from the build directory. For example:
+
== Maintenance ==
  
  <figure pgwide="1">
+
In this section are collected all the standards used to work on documentation.
    <title>This is the text that will appear in the List of Figures</title>
 
    <screenshot>
 
    ...
 
    </screenshot>
 
  </figure>
 
  
== Maintenance ==
+
===Content Updates===
 +
Coders often forget to update the docs after changing the program behaviour or appearance. Sometimes users collect then updated rules here in this wiki. So, if you review a section of the docs, compare it
 +
# with the recent program,
 +
# also with related wiki pages for updates.
  
In this section are collected all the standards used to work on documentation.
+
After your changes were published you should ideally also replace the wiki content by a link to the doc section to avoid redundancy.
  
 
===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'''
+
;Style:
:<tt><!ENTITY vers-stable "2.6.6"></tt>
+
:Consider targets like [{{URL:Gnome-old-sg}}locale.html.en Writing Documentation for an International Audience].
:and appendixa.xml uses this variable like
+
* Short declarative sentences are the best style.
:<tt>The process works on &vers-stable; datafiles, and ought to</tt>
+
* Parentheses should be used as little as possible.
* All accounts named must be tagged with <emphasis>: e.g. <emphasis>Expenses:Tax</emphasis>
+
* Use proper '''terminology''' of
* Hyphens and dashes:
+
:; Gnucash: You can
: To represent a negative number or subtraction:
+
::* browse or download the ''glossary'' at [{{URL:wl}}/glossary/ Weblate] in several formats,
 +
::* view its source [{{URL:GH}}Gnucash/gnucash/blob/maint/po/glossary/gnc-glossary.txt gnc-glossary.txt at GitHub] as CSV file
 +
:: [[Language_Administration#Glossary]] describes its maintenance, adding new languages …
 +
:: ''Translators'' should also consult their current program translation <tt><LANGUAGE>.po</tt> in {{URL:GH}}Gnucash/gnucash/blob/maint/po/
 +
:; GUI elements: [{{URL:Gnome-HIG}} GNOME Human Interface Guidelines] and
 +
::[{{URL:Gnome-old}}wordlist.html Recommended Terminology (2.32)]
 +
* There are variable definitions, '''ENTITY''' in docbook terminology, in the [{{URL:GH}}Gnucash/gnucash-docs/blob/maint/docbook/gnc-docbookx.dtd GnuCash specific extension of the DocBook DTD], which must be used:
 +
:e.g. for future changes to revision numbers, <tt>docbook/gnc-docbookx.dtd</tt> defines variable '''vers-stable'''
 +
::<tt><!ENTITY vers-stable "{{Version}}"></tt>
 +
:and guide/appendixa.xml uses this variable like
 +
::<tt>The process works on &vers-stable; datafiles, and ought to ...</tt>
 +
* Use the same '''indentation''' as existing parts, i.e. indent each level of <tag>s by 2 spaces. Avoid the use of tabulators as their wide is not really defined and so the display of tabs varies depending on the editor, github, ...
 +
* Common '''markup'''s - refinement in progress:
 +
:;block:
 +
::;Components: chapter-like elements and many sections: should start with <syntaxhighlight lang="xml"><title>…</title>
 +
<abstract>Purpose and overview</abstract>
 +
</syntaxhighlight>
 +
::<task> should be used for ''tutorial lessons'' and the ''steps in assistants'';
 +
::<procedure> is better than <numberedlist>;
 +
::<glosslist> <ref>There is also a global glossary (currently in help)</ref> for
 +
::: ''definitions'' at the begin of a chapter/section and the
 +
::: ''descriptions of the gui elements of a dialog'' like <syntaxhighlight lang="xml"><glosslist>
 +
  <title>GUI Elements of Dialog Foo</title>
 +
  <glossentry>
 +
    <glossterm>LABEL</glossterm>
 +
      <glossdef>
 +
        <para>The GUI-ELEMENT-TYPE LABEL …
 +
        </para>
 +
      </glossdef>
 +
    </glossentry>
 +
    …
 +
  <glosslist>
 +
</syntaxhighlight> are better than <itemizedlist>;
 +
:;inline
 +
::One highlighting makup is usually enough. If an element is already part of <title>, <term>… then additional markups are usually not required.
 +
::<s>All '''accounts''' named must be tagged with <emphasis>: e.g. <emphasis>Expenses:Tax</emphasis></s>
 +
::Use <emphasis> only as emphasis.There are more adequate elements for other purposes like:
 +
::;GUI elements. <guibutton>, <guilabel>, <menuchoice> …
 +
::;In- and output: <userinput> (also for creating list elements) often combined with <replaceable> and <optional> instead of <some variable> and [optional part …] like we use them in the wiki.
 +
:::<computeroutput> (also for selection of a list element)
 +
:::<command> for console commands inline;#
 +
:::<programlisting>, <screen> for complexer forms or data files can have a language attribute, which produces in yelp syntaxhighlighting.
 +
* '''Hyphens and dashes''':
 +
: See https://www.thepunctuationguide.com/index.html for guidance on using English language ''punctuation'', including  <tt>&amp;ndash;</tt> and <tt>&amp;mdash;</tt>. You can also enter <code>AltGr</code>+<code>-</code> and <code>AltGr</code>+<code>Shift</code>+<code>-</code> directly on some keyboards.
 +
: 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.
 
:: 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:
 
:: Examples:
::: Number negative 1 (&minus;1): <tt>&amp;minus;1</tt>
+
::: Number <q>negative 1</q> (&minus;1): <tt>&amp;minus;1</tt>
::: Formula GROSS_SALE &minus; TOTALBUY: <tt>GROSS_SALE &amp;minus; TOTALBUY</tt>
+
::: Formula <q>GROSS_SALE &minus; TOTALBUY</q>: <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.
+
===Content Checklist===
 +
Some often missed parts:
 +
* In which '''context''' does it get used and '''why''' - hint: why did you develope it?
 +
* Under which circumstances should it '''not be used''', if any exist?
 +
* Do '''alternative''' methods exist?
 +
* The '''meaning of each GUI element''' should be explained in the related Help section.
 +
* Link '''related''' parts.
  
 
===Graphics conventions===
 
===Graphics conventions===
all screenshots of the GnuCash windows must be captured under a GNOME Desktop environment with the following settings:
+
All screenshots of the GnuCash windows should be captured under the GNOME ''desktop environment'' with the following settings:
 
 
 
* GNOME desktop environment
 
* GNOME desktop environment
* Clearlooks theme
+
* For ''GTK3'' '''Adwaita''' is the default theme. Under ''GTK2'' it was '''Clearlooks''' as you can see on older sceenshots.
* text besides icon
+
* ''GTK3'': text below icon, before it was 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.
 
+
*;Tip for Linux users: Create a ''separate user account'' with above settings. That requires installation of the program for ''all users''.
 +
;Notes:
 +
:* If the title of the window is not important, you can set <tt>without [window] decoration</tt> in your screenshot app. this will probably allow the use of other themes.
 +
:* As GnuCash normalizes the ''order of transaction splits'' (debits before credits), you should capture the screen '''before''' finishing the transaction, in case you enter credits first.<ref>{{BugURL}}show_bug.cgi?id=798143 - Different order of splits in instructions and screenshot</ref>
  
[[Category:Documentation]]
+
===Global Changes===
 +
Appying global changes on many files is often faster done with commandline tools than in your default editor.
 +
;Use Cases: Apply new entities on existing text and similar tasks.
 +
;Examples: Drop obsolete<q> format="PNG"</q>: <Syntaxhighlight lang="sh">
 +
for i in *.xml; do sed -i 's/ format="PNG"//' $i; done
 +
</Syntaxhighlight>
 +
:Escape <code>&</code> of entities in the replacement part as it has a special meaning in <tt>sed</tt>: <Syntaxhighlight lang="sh">
 +
for i in *.xml; do sed -i 's/510px/\&img-w;/' $i; done
 +
</Syntaxhighlight>
 +
;Important: Before and after using <tt>sed</tt>, run <tt>grep</tt> to verify that you didn't change unintended parts: <Syntaxhighlight lang="sh">
 +
clear; grep -in '510' *.xml
 +
</Syntaxhighlight> <tt>clear</tt> cleans the console output to have only the result of the last run.
 +
;Help: To see the manual of <tt>sed</tt>, <tt>grep</tt> … run <Syntaxhighlight lang="sh">
 +
info sed
 +
</Syntaxhighlight> KDE users can better open <tt>info:/grep</tt> in <tt>konqueror</tt> or use <tt>khelpcenter</tt>.
 +
: Windows users might need to install <tt>MinGW</tt>.
  
[[Category:Translation]]
+
===Updating Stylesheets===
 +
Sometimes maintainers update the XSL. If you do it, [[#Optimize the Compression]] of it's images.

Latest revision as of 10:59, 30 June 2022

These instructions describe the process to change the Tutorial & Concepts Guide and the Help manuals. Finally they should consist of:

A: Technical Refeference: Help, in future: Manual
B.1: didactical Tutorial
B.2: task oriented Guide

If you are interested in translating the documentation, you should also read Documentation Translation.

For coordination of changes see Documentation Schedule.

Preface and Introduction -- What to expect

The documentation update process uses the same software management tools that are used for updating the program itself. This ensures that changes are made consistently and reliably. This includes using a version control system (VCS) to coordinate contributions from disparate sources, as well as using DocBook, a semantic markup language for technical documentation based on eXtended Markup Language (XML) for the actual edits. It also requires contributors to check their contributions for compatibility by compiling the documentation before final submission.

These aspects require that documentation contributors learn and use several specialized tools to engage the process.

The tools and the process are outlined in this page. For background on these tools, see Build Tools.

Any changes you make will be inserted into local copies of the source documentation files and subsequently transferred to the main documentation set. 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. After your changes have been validated locally, you will submit your changes to the project either through a "patch," or by a git "pull request" (both of which will be explained later).

For quality control, any changes you submit will be reviewed by a developer before your changes become official. If everything is accepted without requiring further work, your changes will be applied to the main set of documentation by a developer and you will be notified of that action.

The above brief description outlines the general documentation update process.

It may be helpful to become familiar with the references given in the REFERENCES section below.

Setting Up Your System

To begin changing the documentation, you will need to set up your system with the proper software.

Required Software

You will need the following software:

  • To manage your changes of the source text, you will install the git version control system. See Git for more on this.
  • To edit the source files, you will need to have a text editor. Any text editor will do, as long as it can save your files without extra markup. But some editors offer Syntaxhighlighting and perhaps other specific tools for Docbook or XML.
  • To use the build system (make commands etc.) see Requirements in the README file.
  • To illustrate your text with Screenshots and Images, you can use
    • for diagrams: any SVG able drawing program like OfficeDraw (available from LibreOffice or OpenOffice),
    • for screenshots:
      • creation: the built in PrintScreen of your OS or desktop environment,
      • manipulation: The script /util/adjust-dpi.sh uses the following programs
        • identify—and convert in other instructions—from ImageMagick, a nice toolset to manipulate images or query their parameters,
        • awk from gawk,
        • bc from bc, but the later two are in most cases already installed.
      • maintenance: OptiPNG should be run once on new png files, also in stylesheets.
To control the resulting output
html
any web browser—This is the minimum requirement.
docbook
Gnome's Yelp—This is desired.
In theory also KHelpcenter is usable, but nobody provided the proper configuration.
PDF
any PDF viewer—This is recommended.
epub, mobi
calibre can display these mobile formats.

Initial Steps

To work on the documentation we'll need two base directories:

  • a directory to contain the documentation sources, we'll name src throughout this page, though you're free to name it as you like. Note you don't have to create this directory manually, it will be created while obtaining the documentation sources.
  • a directory to hold the documentation that will be generated from the sources. We'll call this directory build.

To avoid potential issues while sending your future changes for inclusion to the GnuCash project it's strongly advised to keep the build directory outside of the src directory. This page will suggest and consistently use the following directory structure:

<base>/
    gnucash-docs/
        src
        build

<base> can be any path in your file system you can write to. Throughout this page we will be using $HOME/code, that is a directory named code in your home directory. So the above will become

$HOME/
    code/
        gnucash-docs/
            src
            build
Note
There is a reason we inisist on keeping your build directory outside of your src directory. If you don't, all of the build artefacts will be seen by git in your source directory. In that case you have to be extra careful not to include these build artefacts in the patches or PRs you create later on. If you understand this and know for yourself how to avoid this (like by setting the proper exclude rules for git) you can ignore this advice. Otherwise, please stick to this rule.

With that out of the way, you can now follow instructions in Initializing Documentation Build Environment to create the directory structure above with the source files in place and ready to be edited.

You likely will also follow these steps to install a few additional tools:

  • To check your changes, you will use the make utility to compile the documentation locally.
See The Make Utility for more on using and installing make.

The Documentation Change Process

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.

Create a Place to Attach and Discuss Your Changes

This can be

  • an (existing or new) enhancement request "bug" in Bugzilla to discuss the theory like constrains and other relations;
  • for collaborative work like collecting of relations a wiki page foo-draft can be the better choice.
  • finally a pull request (PR) on github.
Note the bug or PR number and title
You will be listed as wanting to be notified any time there is an update to the bug. You can monitor it until it is confirmed and applied.
Ideally you would reuse type, number and title in you commit messages.

Update Your Local Copy

Since others could be making changes to the documentation at the same time you are, the GnuCash documentation process employs git to coordinate the disparate contributions. Git ensures that your changes and those of any others are incorporated efficiently into one final set of source files. See Git to learn about using git. This section assumes that you have already obtained a clone of the GnuCash repository, as outlined in Setting Up Your System.

Before you begin editing, you must make sure that your local copy is up to date and aligns with the GnuCash repository by following the instructions at An Introduction to Git.

Identify Location for Changes

GnuCash stores documentation in one master sequence, but reformats the information in different ways for different platforms. When you build the documentation, you create a copy in final format. To make changes, you need to edit the local repository files, not the build directory files. Once you have located the correct source files, you must identify the passages that need to be changed. Your changes should roughly follow the GNOME Documentation Style Guide of the GNOME Documentation Project.

Read the documentation carefully to find exactly where your change belongs.

The English Help Manual source XML files are in

$HOME/code/gnucash-docs/src/help/C

The English Tutorial and Concepts Guide source XML files are in

$HOME/code/gnucash-docs/src/guide/C

The non-english files are in the corresponding locations with C replaced by a 2 character language code.

It may 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.

Draft Your Changes

If your changes are few and easily formulated, you should be able to make your changes directly in the source XML files.

If your changes are more extensive, you may find it helpful to develop your ideas in a separate temporary text file. If you use this approach, you will need to insert your changes into the XML file(s) affected. Doing this might be easier by using a specific XML Editor. Additional resources for XML are listed in the References section for this step.

Note: Remember to 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.

The source documents are saved in the XML flavour of DocBook code, so all changes need to follow those formatting rules. DocBook enforces strict rules about tags and markup, so be sure to make your changes fit the XML tags in the manner of the existing documentation.

Note
It is not necessary to use comments to denote the start or end of your source modifications. The version control system is used to track changes.

Conventions

  • You can find a complete reference to DocBook in The Definitive Guide. Search for II. Reference for the complete alphabetical list.
  • But for beginners the element lists grouped by their function Chapter 2: Creating DocBook Documents is better. Ignore the confusing first part of the page and search for Logical Divisions.
  • Elements of the graphical user interface (GUI) should have the respective markup e.g.for a label: <guilabel>Accounts</guilabel>. A incomplete list of gui elements:
accel, guibutton, guiicon, guimenu, guimenuitem, guisubmenu, keycap, keycode, keycombo, keysym, menuchoice, mousebutton, shortcut.
See DocBook Guide for more detail.
Entities
are the global abbreviations in DocBook and should be used wherever possible. They are usually defined in the form
<!ENTITY appname "GnuCash">
in a DTD and used in the source docs like
<title>&appname; Documentation</title>
There are several levels of definitions:
W3C
usually part of the package dokbook-dtd contain already entities for many special symbols like mathematical or typographical…
See the unified alphabetical list at W3C to avoid overwriting or
select detailed lists from XML Entity Definitions for Characters (3rd Edition).
Gnucash-docs
Our main DTD gnc-docbookx.dtd got some modularization. We separated GUI elements in a language agnostic gui-struct.dtd and siblings for each language like gui-C.dtd or its translation gui-<language>.dtd.
File inclusion
Since GnuCash 3.3 the documents use XInclude
<xi:include href="Help_ch_Intro.xml" />
instead of system entities like
 <!ENTITY SYSTEM ...>
and most other <!ENTITY ...> elements moved in the new Document Type Definition (DTD) gnucash-docs/docbook/gnc-docbookx.dtd and its siblings in the same folder.
Now each file needs a header
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book SYSTEM "gnc-docbookx.dtd">
to be syntactical correct and find the entities. Instead of book it can also be any other type like chapter, appendix
ID attributes
Many elements can contain an inside of the document unique id="chapter-more-specific-context" attribute. This will serve as target for any links — internal or for #Telling the Program of a New Help Context. So each element, which is referenced from inside or outside (GnuCash's Help context) requires one. That includes also elements, for which lists a generated in some target formats: Tables, Figures, ...
Additional they can be used to name the pages of the html output: Getting_Started.html might look nicer than pt01.html.
Conventions
Lowercase, hyphenated terms, where the first stands for the chapter.
Command to grep current definitions
From the top source directory run
grep -inrF "id=" --include="*.xml" --include="*.po" manual/C/
to get the list from the english manual. The pattern "*.po" is currently only required for Italian.
Commands to grep current internal references
From the top source directory run
# the usual way
grep -inrF "linkend=" --include="*.xml" --include="*.po" manual/C/
# some are behind URLs like https://code.gnucash.org/docs/
grep -inrF "url=" --include="*.xml" --include="*.po" manual/C/ 
# Other dependencies: xinclude's href and imagedata fileref
grep -inrF "ref=" --include="*.xml" --include="*.po" manual/C/
Titles
They should be unique, because the <book> has one List of Tables and a List of Figures, which are visible in HTML. One possibility to get consistent entries is the additional use of the element titleabbrev. For example, the representation of
<titleabbrev>Account Tree - File-Menu</titleabbrev>
in the List of Tables is more readable and looks better than
<title>Account Tree - File-Menu - Access to file, account operations and printing</title>
There are more in Docbook Conventions.
Linking
Examples
Tip
If you do not plan to replace the URL by another text, use the short form <link url="https://en.wikipedia.org/wiki/URL" /> instead of
<link url="https://en.wikipedia.org/wiki/URL">https://en.wikipedia.org/wiki/URL</link>
The result is the same.
URLs
Because they will be used in several translations, put them as entities in docbook/gnc-docbookx.dtd to allow an easier update, if they change. The previous example would become
  1. docbook/gnc-docbookx.dtd:
    <!ENTITY url-wp-en "https://en.wikipedia.org/wiki/">  <!-- Append the desired topic -->
    
  2. and in your text:
    More details in <link url="&url-wp-en;URL" />.
    
resulting in
More details in https://en.wikipedia.org/wiki/URL
Textual Conventions
Do not use vague formulations
Instead of "Previous versions [...]" use "Until version X.Y[.Z] [...]". But as the current docs are no archive, the text body should describe the current version of Gnucash. On important changes add a footnote "Before version x.y it was …" to wake up experienced users to register the change.

Adding or Removing Files

If you are adding or deleting files from the documentation, for example adding a new chapter or appendix, you will need to announce it to several parts of the system to ensure that these new or deleted files get handled properly.

These are:

  1. The base XML file (i.e., gnucash-guide.xml or gnucash-help.xml). This file includes
    <xi:include href="Book_type_Name.xml" />
    
    declarations for each source file in the documentation. You must edit this XInclude list to reflect the changes you have made to the file list, where
    • Book is either Help or empty, (TODO: should be dropped)
    • type should be either ch[apter] or app[endix],
    • Name describing its content.
  2. Tell the build system about the change. You do this by inserting the name of your added file to or removing the name of your deleted file from the file list in CMakeLists.txt located in the same folder as the base XML file.
    Note
    There are CMakeLists.txt files in each of the language folders as well as in the base documentation folder. Make sure you edit the proper copy--that is, the copy in the specific language folder you have edited.
  3. Tell Git to add/remove the file to/from the repository:
    git add ${MODULE}/${LOCALE}/${FILENAME} # ${MODULE}={guide|help}; ${LOCALE}={C|de|it...}; ${FILENAME}=file to add
    git rm ${MODULE}/${LOCALE}/${FILENAME} # to remove it - also from your filesystem! See 'git help rm' for other options.
    
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 ($HOME/code/gnucash-docs/src/help/C or $HOME/code/gnucash-docs/src/guide/C) to determine what changes, if any, need to be made to modules outside your original assessment.

Telling the Program of a New Help Context

In gnucash/gnome-utils/gnc-ui.h are 2 important sections:

  1. Help Files:
    /** Help Files ******************************************************/
    :
    #    define HF_GUIDE         "gnucash-guide"
    #    define HF_HELP          "gnucash-help"
    :
    
  2. Links in the Help Files (id):
    /** Links in the Help Files *****************************************/
    #define HL_USAGE             "usage"
    :
    

Ask a developer to

  1. add your chapter, section, table or whatever id to the list and
  2. use it together with its HF_* as help context in gnc_gnome_help(file_name, anchor) or where else it is associated GUI elements.
Fixme
Ways to find the ids generally in the code sources?

Validate Your Changes

xmllint
The program xmllint is used to test that your xml file has no syntax errors or incorrect references to internal sections. It is part of the package libxml.
Tip
Some XML aware editors have a builtin Validate command to run xmllint direct on the currently opened file and jump to the first error.
make *check
For your convenience the build system comes with built-in rules to run xmllint. It is run by executing make [something-]check in the top level build directory. Depending on the [something-] part in that command one or more documents will be checked.
For example, if you had downloaded the documentation files to a directory called $HOME/code/gnucash-docs and created a build directory called $HOME/code/gnucash-docs/build:
  1. To validate one or more documents, first go to the top level build directory
    cd $HOME/code/gnucash-docs/build
    
  2. From there to validate
    • all the guide xml files for only the C (English) language:
      make C-gnucash-guide-check
      
    • all the guide xml files for all languages:
      make gnucash-guide-check
      
    • all the guide and manual xml files:
      make check
      
So generally the check parameter to make is of the form <language>-<document>-check. You can omit <language>- or <language>-<document>- to widen the scope of the check.
Tip
If using ninja, you can list all the check targets by ninja -t targets | grep check
Note
xmllint works by loading the main gnucash-{guide|help}.xml file of the current document's directory together with all other xml files referenced in this main file and then checks all the files.

xmllint output

  • 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 there are any errors, fix them and repeat this step until no errors are found.
  • If you are unable to fix an XML error, ask either using IRC or, see Mailing_Lists, on gnucash-devel.

make *pdf

Tip
After passing make check it is a good idea to also run
make <language>-<document>-pdf
The xsltproc command used there is stricter than make check with the current settings. It will
  • warn if it finds unresolved ID references and
  • abort if a table row has more columns than declared.

After Adding, Moving or Deleting Files

Verify a tarball

  1. can be built
    cd ${BUILDDIR} # Adjust this
    make distcheck
    
  2. contains your new files.

After success you can remove gnucash-docs-4.11.tar.gz from your ${BUILDDIR} again.

Ensure Only Expected Changes Have Been Made

You should double check that there are no accidental changes to the documentation.

The following command when run in the src directory will show any changes to unstaged files

git diff

Git status (also run in the src directory) 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

Proofreading

After you have tested the integrity of the XML using xmllint (make check) and have verified that the difference file shows the correct changes, it depends on your OS/installed software, how to proceed

Not very fast, but simple under Linux
run Gnucash after installing your version of the documentation:
Install and run your version
cd ${BUILDDIR} # adjust this
sudo make install
gnucash
#choose a component from the Help menu
This is also the preferred method to test the context sensitive help.
Fast under Linux
but more typing
KHelpcenter and Gnomes help viewer yelp can both display docbook documents:
yelp $PREFIX/share/gnome/help/gnucash-help/$LANG/gnucash-help.xml # adjust:
# 1. $PREFIX (/usr/local/) or just use your ${BUILDDIR},
# 2. $LANG (/C/)
# 3. document help or guide

# or after we fixed the path for our DTD:
khelpcenter $PREFIX/share/gnome/help/gnucash-help/$LANG/gnucash-help.xml
# If we create .desktop files this will become easier.
or less typing
If you
  1. used a standard path for the INSTALLDIR—e.g. did not change CMAKE_INSTALL_PREFIX in your build configuration—
    If you changed it, you can insert it into XDG_DATA_DIRS. To get those path on each login, Linux users can insert the command e.g. into $HOME/.bashrc:
    # Integrate my test directory
    export XDG_DATA_DIRS=${HOME}/test/share:${XDG_DATA_DIRS}
    
    if your CMAKE_INSTALL_PREFIX is ${HOME}/test.
  2. are running your shell in the same language as the document,
you can also use the shorter
yelp ghelp:gnucash-help
or start gnucash and select it from the help menu.
Note
There are plans to use in future versions
  1. help: instead of ghelp: which uses a different directory structure and
  2. manual instead of help as document name.

In HTML and Other Formats

The easiest way to check your changes is to view the HTML version in your browser. You should also review other formats as they have their own peculiarities:

  • If you are using non-latin writing, are the fonts right in pdf?
  • Are images displayed correctly?
  • Is the page layout OK in ebooks?

The Guide or Help must be recreated in HTML and the results examined in your browser to verify that the online version appears and reads as expected.

Build the Guide or Help file in HTML. Use any of the make commands below in a terminal, to generate (part) of the documentation in a chosen language and format:
cd ${BUILDDIR} # adjust this

# In any of the commands below, replace html with pdf, epub or mobi to build that other format

# to build both guide and manual in all languages in html:
make html
# or to build only the guide in all languages
make gnucash-guide-html
# or to build only the help manual in all languages
make gnucash-help-html

# In the following commands you can replace C with any other language code we have a guide or help manual for
# or to build only the guide in English
make C-gnucash-guide-html
# or to build only the help manual in English
make C-gnucash-help-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/code/gnucash-docs/build/share/doc/<language>/gnucash-<guide|help>

Review the results in your browser. Calibre is a good choice as viewer for ebook formats (epub, mobi, ...).

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/code/gnucash-docs/build/share/doc/C/gnucash-help/help.html
# or
$HOME/code/gnucash-docs/build/share/doc/C/gnucash-guide/index.html

Add Extra Files

Git automatically tracks changes to files it knows are part of the repository. However, if you have added any files that should be included in your commit (xml or others, for example, illustrations), add (stage) them with the command:

 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

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

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
(-a also causes git to notice and commit any deleted files)
or you can commit a few files at a time with
git add path/to/file1 [path/to/file2 …]
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
But --amend should only be used as long, as you did not publish your commit by pushing it to some public github repository.
Exception
Only on your own, still open pull requests you are allowed to use
git commit -a --amend
git push -f

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 is generated from the 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

Create a Pull Request or a Patch

Once you have finalized your changes, you will notify the developer team of your changes, either by creating a —recommend— pull request, or —less desired— by creating and uploading a patch.

After Merge: Verification

To avoid surprises after the release, you should verify one day after the merge of your pull request the nightly build:

All
browse https://code.gnucash.org/docs/
Flatpak users
See Flatpak for how to enable the nightlies and update them.
Then run
flatpak run --command=sh org.gnucash.GnuCash
yelp
If you watch
I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
/app/share/gnome/help/gnucash-help/de/Help_ch_Transactions.xml:3171: parser error : Entity 'ndash' not defined
                &ndash; Importieren als eine neue Buchung. Manueller Eingriff er
                       ^
$
or similar, and can not fix it, inform the flatpak maintainers.
Windows users
See Windows for how to enable the nightlies and update them.
Start the Program and open the docs from the help menu.

References to Supporting Technologies Used

[1] https://wiki.gnucash.org/wiki/Bugzilla
[2] https://github.com
[3] http://www.jedit.org/
[4] https://en.wikipedia.org/wiki/DocBook
[5] https://www.docbook.org/ DocBook: The Definitive Guide
Some Distributions have it as a package named like docbook-tdg.
[6] https://www.tldp.org/LDP/LDP-Author-Guide/html/tools-edit.html
[7] https://www.netlingo.com/tips/html-code-cheat-sheet.php
[8] https://wiki.gnucash.org/wiki/Git

Additional Information

Screenshots And Other Images

Desktop Themes for Screenshots

Try to maintain consistency with existing images by using specific themes for your desktop environment.
Most current images are still from the GnuCash-2 series, where we used the Clearlooks engine, which has been the default theme of GNOME 2 since version 2.12.
So for GnuCash3+ we should use Gnome3's default theme "Adwaita".
If you are not on Linux, try to find a similar theme for your desktop.

If you customized your desktop or are using a different environment,

create ideally a Linux VM with a Vanilla Gnome Desktop
or at least create a separate user like Gnucash User or similar—ideally one per language/region.
In theory you could also adjust the settings per session but practical you will find after days one detail you had forgotten to set properly in a serie of images.

start a Gnome session for that user;

if you are not translating, you should use the default LANG=C with one exception:
As the US date format is confusing to almost all other readers, start GnuCash and set in
Edit->Preferences->Numbers, Date and Time->Date Format: ISO

Image Formats

Screenshots
are ideally submitted in .png format.
Tip
Before capturing
Shrink the window size to the minimum to get the best result. If text gets truncated, file a bug against the GUI.
While capturing
  1. Often you can avoid cropping by selecting Scope: Active Window
  2. Hold down the Alt keys because GTK3 else hides the accelerator markings _.
Graphics showing relations
are best in .svg. That would allow translators to replace in their copy the labels with their translation.
Callouts
images with annotations – are ideally created in GIMP's .xfc format with the
screenshot
on the lowest level and
each label
on a separate level. That will allow you or translators to edit, move or resize the labels.
Translators can replace the screenshot and translate the labels. Finally add it in
xfc
for future maintenance, translation creation … and
png format
to use in the docs
to the repo and link the png in the text.
Icons
are used in all project components: Program, Bundles, Documentation and Website. Best practises still need to be written.

Indexing

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 text will appear as header and in the List of Figures</title>
    <screenshot>
      <screeninfo>640x480x256</screeninfo>
      <mediaobject>
        <!-- insert the imageobjects here -->
        <caption><para>Optionally you can here add a longer description than in the title.
          If not required, remove the caption element.</para>
        </caption>
      </mediaobject>
    </screenshot>
  </figure>
screeninfo
Information about how and at what resolution a screen shot was produced, when it was produced, and by whom. We found this in 2022 and need to discuss our preferred content. Perhaps it is a good place to store the size here instead of running identify on each time the info is needed.
textobject
Older parts have mistakenly a <textobject> instead of a figure title or a <caption>. For now move the content into the adequate tag. Only if you want to support
add a precise description of the image as textobject.
Displaying pictures side by side
If you want to display pictures next to each other, they can be positioned in a small table with a single table line and two column. This solution is suitable if the images to be displayed have comparable dimensions, preferably the same height.
Please note that the parameter "width" for the image size must be set to 100%. This value refers to the size of the table cell and fits the image completely into the cell.
Finally check your entry in the index context
Build the html flavour and open its Table of Content. That is currently
guide/C/gnucash-guide/index.html
help/C/gnucash-help/help.html
in your build directory, but willl change with GnuCash docs should follow XDG help-system-spec..
Scroll down to List of Figures. Is it
  • unique and
  • descriptive?

Display and Print Targets

Gnucash 4.10 change
The original instructions talked about 510px wide, but images of that width are too narrow on modern large screens. Because on a "Full HD" monitor the normal page wide in yelp seems to be >=800 px this is the new default stored in docbook/gnc-docbookx.
  • Older documents require a review of their <imageobject>s: If the width is
≤ 800 px
remove width=&img-w; and—if it references the same file—the fo object;
else
verify that the fo object has no width in px.
To get a list see the Tip below.
Still unresolved
Sometimes
  • images are indented as part of a list element or
  • we want to display 2 images side by side.
How can we tell that adjust-dpi.sh …?

Screenshots and images added to the GnuCash documentation must fit two purposes: video display by Gnome's Yelp or other browsers like Firefox and paper printing (pdf creation). Each has its own way of determining width:

video display
defines image width limits in terms of pixels, while
print output
sets limits on image size based on a ratio of image size and the image's dots per inch (dpi).

Because we do not want to shrink the image itself, but want to limit the width of

image presentations on screen to 800 px,
and 14 cm on paper, we get 2 different cases for our entry:
width <= 800 px
and insert:
      <imageobject>
        <imagedata fileref="figures/Report_Screen.png"
                   srccredit="your name" />
      </imageobject>
imagedata attributes
format
like format="PNG"is only required, if the filename extension is unknown by the processor. Please remove obsolete instances!
See also: docbookxsl GraphicSelection, docbookxsl GraphicFormats
width, depth
If the viewport area (width|depth) is specified, but no content area (contentwidth|contentdepth), docbook sets scalefit=1 resulting in zooming the image to viewportsize.
width > 800 px
Use two <imageobject> tags, as shown below:
      <imageobject role="html">
        <imagedata fileref="figures/Help_Pref_AccntPeriod.png"
                   srccredit="your name" width="&img-w;" />
      </imageobject>
      <imageobject role="fo">
        <imagedata fileref="figures/Help_Pref_AccntPeriod.png"
                   srccredit="your name" />
      </imageobject>
imageobject attributes
role
"html" refers to display presentation on screens (the width is limited to 800 px), while
"fo" processor (FOP) prepares it for printing of pdf
Now the image will fit on display and we can continue to adjust it for printing.

Adjusting an Image's Dots Per Inch

You must take another step to prepare a screenshot for print output: you must set the dots per inch (dpi) correctly. The dpi defines an image's dot density, and thus its overall quality; the higher the dpi, the better the printed image quality. 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 a maximum of about 15 cm, so you can resize the screenshot by changing its dpi (Note that the US Letter size paper is slightly wider than A4, so images scaled for A4 will also fit on US Letter size paper). Normally if you take a screenshot when the GnuCash window is almost at its minimum, the dpi will be set to 144, which for our example screenshot will result in a print size of:
800/144 x 560/144 inches = 14 x 10 cm 
This 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 its printed size remains less than 15 cm.
Tip
To query the properties of the existing images you can use Imagemagicks identify command:
# for many details of one file:
identify -verbose $FILENAME

# or important infos about all files in the current directory:
echo "Size [px] and Resolution of all files in the current directory:";
for i in *.png; do identify -format "%w x %h %x x %y %U %f\n" $i; done;

# or to create a list of the images width:
touch width.lst;
for i in *.png; do identify -format "%w %f\n"  $i >> width.lst; done;
# Output sorted descending by width, useful on changes of &img-w;:
clear; sort -nr width.lst;
# or by name, useful on review of text:
clear; sort -k2 width.lst
The % parameters are explained in ImageMagick's doc package.
Individual
The dpi of an image be changed in one of two ways:
  1. Open the screenshot in an image editor (like The Gimp) and select Image->Print Size. In the dialog that opens, set the X and Y resolution to the desired dpi (check that the unit value is set to the desired value - normally pixels/in). Press "Ok" and save the image.
  2. A faster approach uses Imagemagick, a library for image 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).
All at once
New Method
For your convenience the bash script adjust-dpi.sh has been included in the gnucash-docs repository that automatically calculates and assigns 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            # In the repo, NOT the build directory structure
../../../util/adjust-dpi.sh
If that fails i.e. because dependencies are missing on your computer, you can still use the old method.
Old Method
To convert the dpi of a bunch of images do this from a terminal window:
for i in *.png; do convert -units PixelsPerInch -density 144 "$i" "$i"; done
This applies a dpi of 144 to all images of the current directory.

Optimize the Compression

The tool OptiPNG tries to minimize the size of png files lossless:

cd guide/pt/figures            # In the repo, NOT the build directory structure
optipng ${FILENAME}            # <- One file or all:
for i in *.png; do optipng $i; done

If it is too hard for you, ask the developers in your pull enhancement request to do it for you.

Maintenance

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

Content Updates

Coders often forget to update the docs after changing the program behaviour or appearance. Sometimes users collect then updated rules here in this wiki. So, if you review a section of the docs, compare it

  1. with the recent program,
  2. also with related wiki pages for updates.

After your changes were published you should ideally also replace the wiki content by a link to the doc section to avoid redundancy.

Text conventions

Style
Consider targets like Writing Documentation for an International Audience.
  • Short declarative sentences are the best style.
  • Parentheses should be used as little as possible.
  • Use proper terminology of
Gnucash
You can
Language_Administration#Glossary describes its maintenance, adding new languages …
Translators should also consult their current program translation <LANGUAGE>.po in https://github.com/Gnucash/gnucash/blob/maint/po/
GUI elements
GNOME Human Interface Guidelines and
Recommended Terminology (2.32)
e.g. for future changes to revision numbers, docbook/gnc-docbookx.dtd defines variable vers-stable
<!ENTITY vers-stable "4.11">
and guide/appendixa.xml uses this variable like
The process works on &vers-stable; datafiles, and ought to ...
  • Use the same indentation as existing parts, i.e. indent each level of <tag>s by 2 spaces. Avoid the use of tabulators as their wide is not really defined and so the display of tabs varies depending on the editor, github, ...
  • Common markups - refinement in progress:
block
Components
chapter-like elements and many sections: should start with
<title></title>
<abstract>Purpose and overview</abstract>
<task> should be used for tutorial lessons and the steps in assistants;
<procedure> is better than <numberedlist>;
<glosslist> [1] for
definitions at the begin of a chapter/section and the
descriptions of the gui elements of a dialog like
<glosslist>
  <title>GUI Elements of Dialog Foo</title>
  <glossentry>
    <glossterm>LABEL</glossterm>
      <glossdef>
        <para>The GUI-ELEMENT-TYPE LABEL …
        </para>
      </glossdef>
    </glossentry><glosslist>
are better than <itemizedlist>;
inline
One highlighting makup is usually enough. If an element is already part of <title>, <term>… then additional markups are usually not required.
All accounts named must be tagged with <emphasis>: e.g. <emphasis>Expenses:Tax</emphasis>
Use <emphasis> only as emphasis.There are more adequate elements for other purposes like:
GUI elements. <guibutton>, <guilabel>, <menuchoice> …
In- and output
<userinput> (also for creating list elements) often combined with <replaceable> and <optional> instead of <some variable> and [optional part …] like we use them in the wiki.
<computeroutput> (also for selection of a list element)
<command> for console commands inline;#
<programlisting>, <screen> for complexer forms or data files can have a language attribute, which produces in yelp syntaxhighlighting.
  • Hyphens and dashes:
See https://www.thepunctuationguide.com/index.html for guidance on using English language punctuation, including &ndash; and &mdash;. You can also enter AltGr+- and AltGr+Shift+- directly on some keyboards.
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
  • 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.

Content Checklist

Some often missed parts:

  • In which context does it get used and why - hint: why did you develope it?
  • Under which circumstances should it not be used, if any exist?
  • Do alternative methods exist?
  • The meaning of each GUI element should be explained in the related Help section.
  • Link related parts.

Graphics conventions

All screenshots of the GnuCash windows should be captured under the GNOME desktop environment with the following settings:

  • GNOME desktop environment
  • For GTK3 Adwaita is the default theme. Under GTK2 it was Clearlooks as you can see on older sceenshots.
  • GTK3: text below icon, before it was besides icon;
  • font: Sans. 9 point for application and 11 point for window title.
    Tip for Linux users
    Create a separate user account with above settings. That requires installation of the program for all users.
Notes
  • If the title of the window is not important, you can set without [window] decoration in your screenshot app. this will probably allow the use of other themes.
  • As GnuCash normalizes the order of transaction splits (debits before credits), you should capture the screen before finishing the transaction, in case you enter credits first.[2]

Global Changes

Appying global changes on many files is often faster done with commandline tools than in your default editor.

Use Cases
Apply new entities on existing text and similar tasks.
Examples
Drop obsolete format="PNG":
for i in *.xml; do sed -i 's/ format="PNG"//' $i; done
Escape & of entities in the replacement part as it has a special meaning in sed:
for i in *.xml; do sed -i 's/510px/\&img-w;/' $i; done
Important
Before and after using sed, run grep to verify that you didn't change unintended parts:
clear; grep -in '510' *.xml
clear cleans the console output to have only the result of the last run.
Help
To see the manual of sed, grep … run
info sed
KDE users can better open info:/grep in konqueror or use khelpcenter.
Windows users might need to install MinGW.

Updating Stylesheets

Sometimes maintainers update the XSL. If you do it, #Optimize the Compression of it's images.
  1. There is also a global glossary (currently in help)
  2. https://bugs.gnucash.orgshow_bug.cgi?id=798143 - Different order of splits in instructions and screenshot