Difference between revisions of "Documentation Improvement"

From GnuCash
Jump to: navigation, search
m (Changing DPI heading)
(Draft Your Changes: simplify xml/Dicbook)
(39 intermediate revisions by 4 users not shown)
Line 7: Line 7:
 
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 ''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.  
 
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 ''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.
+
'''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.
+
The tools and the process are outlined in this page. For background on these tools, see [[Build_Tools|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.
 
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.
Line 25: Line 25:
 
==Setting Up Your System==
 
==Setting Up Your System==
  
To begin changing the documentation, you will need to set up your system with the proper software. You will need the following software:
+
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 the change sequence, you will install the ''git'' version control system. See [[Git]] for more on this.
 
* To manage the change sequence, 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.
 
* 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.
* To stage your changes, you will need an appropriate directory structure. See [[Initializing_Documentation_Build_Environment]] for more.
+
* To illustrate your text with [[#Screenshots and Images|Screenshots and Images]], you can use  
* 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.
+
** 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]),
* To test the linkages between GnuCash and help files in Linux, see [[Test_Documentation_in_Linux]].
+
** for '''screenshots:'''
 +
*** ''creation:'' the built in PrintScreen of your OS or desktop environment,
 +
*** ''manipulation:'' [https://www.imagemagick.org ImageMagick] is suggested because it is used by <tt>/util/adjust-dpi.sh</tt>.
  
With the proper tools in place, there are a number of additional steps to take to prepare your system. You will need to obtain a local copy of the files from the GnuCash repository, which is called '''cloning'''. The cloned copy is what you will work on.
+
===Initial Steps===
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]]. 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/].  
+
* You will need to obtain a local copy of the files from the GnuCash repository, which is called '''cloning'''. The cloned copy is what you will work on. See [[git]] for more information.
 +
* To stage your changes, you will need an appropriate directory structure.  
 +
:See [[Initializing_Documentation_Build_Environment|Initializing Documentation Build Environment]] for more.
 +
* 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==
 
==The Documentation Change Process==
Line 41: Line 51:
  
 
===<span id="CreateBug"></span> Create a Bugzilla Documentation Bug===
 
===<span id="CreateBug"></span> Create a Bugzilla Documentation Bug===
Create a [http://wiki.gnucash.org/wiki/Bugzilla bugzilla] bug if one does not already exist. See [[Bugzilla]] for more.  
+
Create a [[Bugzilla]] bug if one does not already exist.
 
    
 
    
 
;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.
 
;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.
  
 
===<span id="UpdateLocal"></span>Update Your Local Copy===
 
===<span id="UpdateLocal"></span>Update Your Local Copy===
Cloning the documentation copies the most current version of the documentation to your local computer, where you will be able to make your edits. Since others could be making changes to the documentation at the same time you are, the GnuCash documentation process employs the ''git'' VCS 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''.
+
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]].''
  
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.
+
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]].
  
First, change to your preferred local source code folder.
+
===Ensure The Build Directory Is Up To Date===
  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.
+
As the source files get changed on your machine and on the remote repositories, the files <tt>configure.ac</tt> and <tt>Makefile.am</tt> can change. If either of these files changes, you should run autogen.sh and configure again to make sure that changes are incorporated. This might occur because you changed it yourself or because someone else committed a change in git.  
  git clone https://github.com/Gnucash/gnucash-docs gnucash-docs
 
  
This will copy the documentation to your computer into the folder gnucash-docs.
+
If you are not sure whether or not these files have changed, the safest course is to run these commands every time you pull.
 +
 
 +
Remember that these commands are issued from the ''build directory''; '''if you do not yet have your build directory set up, consult [[Initializing_Documentation_Build_Environment|Initializing Documentation Build Environment]].'''
  
 
===<span id="IDLoc4Change"></span>Identify Location for Changes===
 
===<span id="IDLoc4Change"></span>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 [http://library.gnome.org/devel/gdp-style-guide/stable/ GNOME Documentation Style Guide] of the [https://live.gnome.org/DocumentationProject/ GNOME Documentation Project].
+
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].
  
 
'''Read the documentation carefully to find exactly where your change belongs.'''  
 
'''Read the documentation carefully to find exactly where your change belongs.'''  
Line 79: Line 89:
 
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 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 [http://www.dmoz.org/Computers/Data_Formats/Markup_Languages/XML/Tools/Editors/ specific XML Editor]. Additional resources for XML are listed in the [[#References to Supporting Technologies Used|References]] section for this step.  
+
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.  
  
 
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.
 
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 XML - or to be more precise [[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.  
+
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.
 +
 
 +
;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.
 +
 
 +
====<span id="DraftConvention"></span>Conventions====
 +
Examples of commonly-used tags include: ''chapter'', ''sect1'' ... ''sect5'', ''simplelist'', ''orderedlist'', ''list item'', ''para'' and their corresponding closing tags.
  
Examples of commonly-used tags include: ''chapter'', ''segment'', ''sect1'', ''sect2'', ''orderedlist'', ''list item'', ''para'' and their corresponding closing tags. You should also use the '''Definitions''' ''<!ENTITY ...>'' from the main file where ever possible.
+
You can find a complete reference to DocBook in [https://tdg.docbook.org/tdg/{{DocbookVersion}}/docbook.html The Definitive Guide]. [https://tdg.docbook.org/tdg/{{DocbookVersion}}/ch02.html Chapter 2: Creating DocBook Documents] may be of particular assistance.
 +
;Since GnuCash 3.3: The documents use XInclude <SyntaxHighlight lang="xml">
 +
<xi:include href="Help_ch_Intro.xml" />
 +
</SyntaxHighlight> instead of file inclusion by <SyntaxHighlight lang="xml"> <!ENTITY SYSTEM ...></SyntaxHighlight> and most other <code><!ENTITY ...></code> elements moved in the new [https://en.wikipedia.org/wiki/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]. Each file needs now 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.
  
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.  
+
In particular, note that:
 +
* Wherever possible you should use the '''Definitions''' <code><!ENTITY ''name'' ...></code> from our <tt>gnc-docbookx.dtd</tt> and the base file <tt>gnucash-guide.xml</tt> or <tt>gnucash-help.xml</tt> as <code>&''name'';</code>.
 +
* 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.
  
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,
+
====<span id="DraftAddRemove"></span>Adding or Removing Files====
then rerun autogen.sh and ../configure.sh. There is no need to update Makefile.in as this is generated by running autogen.sh.
+
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.
  
;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.
+
This are:
 +
# 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 [[Autotools]] from the change: The '''Makefile.am''' located in the same folder as the ''base XML file''. Again, you must edit the file list in this file to reflect the changes you have made to the file list. Makefile.am must include ''all'' files listed in the <code> <xi:include ...></code> section of the base XML file in its <code>entities</code> list. <!-- Is the previous statement correct? Who asks this?~Fell-->
 +
#;Note: There are Makefile.am 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.
 +
#;Important: Because you have changed Makefile.am, you will need to rerun <code>../configure</code>, as described in [[Initializing_Documentation_Build_Environment|Initializing Documentation Build Environment]].
 +
# 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
 +
</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>gnucash-docs/help/C</tt> or <tt>gnucash-docs/guide/C</tt>) to determine what changes, if any, need to be made to modules outside your original assessment.
  
You can find an introduction to [http://www.docbook.org DocBook] in [http://docbook.org/tdg51/en/html/ch02.html Creating DocBook Documents].
+
==== Telling the Program of a New Help Context ====
 +
Ask a developer to add your chapter, section, table or whatever <code>id</code> to the list <Syntaxhighlight lang="C">
 +
/** Links in the Help Files *****************************************/
 +
#define HL_USAGE            "usage"
 +
:
 +
</Syntaxhighlight> of [https://github.com/Gnucash/gnucash/blob/maint/gnucash/gnome-utils/gnc-ui.h gnucash/gnome-utils/gnc-ui.h]
 +
and use it as help context of its associated GUI elements.
  
 
===<span id="ValidateChanges"></span>Validate Your Changes===
 
===<span id="ValidateChanges"></span>Validate Your Changes===
Line 106: Line 151:
  
 
To validate all the guide xml files for only the ''C'' (English) language:
 
To validate all the guide xml files for only the ''C'' (English) language:
  cd /home/$USER/code/gnucash-docs/'''build'''/guide/C
+
<SyntaxHighlight lang="sh">
 +
cd /home/$USER/code/gnucash-docs/build/guide/C
 +
</SyntaxHighlight>
 
To validate all the guide xml files for all languages:
 
To validate all the guide xml files for all languages:
  cd /home/$USER/code/gnucash-docs/'''build'''/guide
+
<SyntaxHighlight lang="sh">
 +
cd /home/$USER/code/gnucash-docs/build/guide
 +
</SyntaxHighlight>
 
To validate all the guide and help xml files:
 
To validate all the guide and help xml files:
  cd /home/$USER/code/gnucash-docs/'''build'''
+
<SyntaxHighlight lang="sh">
 +
cd /home/$USER/code/gnucash-docs/build
 +
</SyntaxHighlight>
  
 
Then:
 
Then:
  make check
+
<SyntaxHighlight lang="sh">
 +
make check
 +
</SyntaxHighlight>
  
 
If there are any errors, fix them and repeat this step until no errors are found.
 
If there are any errors, fix them and repeat this step until no errors are found.
Line 126: Line 179:
  
 
The following command will show any changes to unstaged files
 
The following command will show any changes to unstaged files
  git diff
+
<SyntaxHighlight lang="sh">
 +
git diff
 +
</SyntaxHighlight>
 
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 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
+
<SyntaxHighlight lang="sh">
 +
git status
 +
</SyntaxHighlight>
  
 
===<span id="Proofread"></span>Proofread in HTML===
 
===<span id="Proofread"></span>Proofread in HTML===
Line 178: Line 235:
 
===<span id="PubAuthor"></span>Publish your Authorship===
 
===<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 [http://en.wikipedia.org/wiki/Open_Media_Framework Open Media Framework]. Add a maintainer section with your data and check the other items like the date, which also needs an update.
+
The first page, which can also be shown as ''About'' of the document is in the file '''<tt>gnucash-</tt>{<tt>guide</tt>|<tt>help</tt>}<tt>-C.omf</tt>'''. OMF means [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
 
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
Line 207: Line 264:
  
 
===<span id="PullorPatch"></span>Create a Pull Request or a Patch===
 
===<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 [[Git#Pull_Requests|pull request], or by [[Preparing_A_Documentation_Patch|creating and uploading a patch]].
+
Once you have finalized your changes, you will notify the developer team of your changes, either by creating a [[Git#Pull_Requests|pull request]], or by [[Preparing_A_Documentation_Patch|creating and uploading a patch]].
  
 
==References to Supporting Technologies Used==
 
==References to Supporting Technologies Used==
  
[1] http://wiki.gnucash.org/wiki/Bugzilla
+
:[1] https://wiki.gnucash.org/wiki/Bugzilla
[2] https://github.com
+
:[2] https://github.com
[3]  http://www.jedit.org/
+
:[3]  http://www.jedit.org/
[4] http://en.wikipedia.org/wiki/DocBook
+
:[4] https://en.wikipedia.org/wiki/DocBook
[5] http://www.docbook.org/  DocBook: The Definitive Guide
+
:[5] https://www.docbook.org/  DocBook: The Definitive Guide
: Some Distributions have it as a package named like ''docbook-tdg''.
+
:: Some Distributions have it as a package named like ''docbook-tdg''.
[6] http://www.tldp.org/LDP/LDP-Author-Guide/html/tools-edit.html
+
:[6] https://www.tldp.org/LDP/LDP-Author-Guide/html/tools-edit.html
[7] http://www.netlingo.com/tips/html-code-cheat-sheet.php
+
:[7] https://www.netlingo.com/tips/html-code-cheat-sheet.php
[8] http://wiki.gnucash.org/wiki/Git
+
:[8] https://wiki.gnucash.org/wiki/Git
  
 
==Additional Information==
 
==Additional Information==
 
===Screenshots and Images===
 
===Screenshots and Images===
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.
+
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://help.gnome.org/misc/release-notes/2.0/ GNOME 2] since version 2.12.  
 +
The utility adjust-dpi.sh uses the following programs
 +
* identify from [https://www.imagemagick.org ImageMagick], a nice toolset to manipulate images or query their parameters,
 +
* awk from gawk
 +
* bc from bc.
 +
 
 +
====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:
 +
<syntaxhighlight lang="xml">
 +
  <figure pgwide="1">
 +
    <title>This is the text that will appear in the List of Figures</title>
 +
    <screenshot>
 +
      <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>
 +
 
 +
====Display and Print Targets====
 +
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 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 limit the width of
 +
:image presentations on screen to 510px
 +
:and 14 cm on paper, we get 2 different cases for our entry:
 +
;width <= 510px: and insert
 +
<syntaxhighlight lang="xml">
 +
      <imageobject>
 +
        <imagedata fileref="figures/Report_Screen.png" format="PNG"
 +
                  srccredit="your name"></imagedata>
 +
      </imageobject>
 +
</syntaxhighlight>
 +
 
 +
;width > 510px: Use two <imageobject> tags, as shown below:
 +
<syntaxhighlight lang="xml">
 +
      <imageobject role="html">
 +
        <imagedata fileref="figures/Help_Pref_AccntPeriod.png" format="PNG"
 +
                  srccredit="your name" width="510px"></imagedata>
 +
      </imageobject>
 +
      <imageobject role="fo">
 +
        <imagedata fileref="figures/Help_Pref_AccntPeriod.png" format="PNG"
 +
                  srccredit="your name"></imagedata>
 +
      </imageobject>
 +
</syntaxhighlight>
  
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:
+
:The "'''html'''" attribute refers to ''display'' presentation on screens (the width is limited to 510px), while the "'''fo'''" attribute refers to pdf ''printing''.
  
            <imageobject role="html">
+
;Note: 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.
              <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.
+
Now the image will fit on display and we can continue to adjust it for 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 ====
 
==== 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 253: Line 348:
 
: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.
  
 +
===== Individual =====
 
:The dpi of an image be changed in one of two ways:
 
:The dpi of an image be changed in one of two ways:
:# 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.
+
:# 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:
+
:# 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  
+
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).
 
: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:
+
===== All at once =====
 
+
====== Old Method ======
ls *.png > list
+
# To ''convert the dpi'' of a bunch of images do this from a terminal window:
for i in `cat list`; do convert -units PixelsPerInch -density 144 "$i" "$i"; done
+
#:<syntaxhighlight lang="sh">
 
+
ls *.png > list
:The first line creates the file "list" with a list of all png files in the current directory
+
for i in `cat list`; do convert -units PixelsPerInch -density 144 "$i" "$i"; done
:The second and third lines applies a dpi of 144 to all images listed in the "list" file
+
</syntaxhighlight>
 
+
#:The first line creates the file "list" with a list of all png files in the current directory
:Imagemagick lets you also see sizes and pixels per inch from the command line:
+
#:The second and third lines applies a dpi of 144 to all images listed in the "list" file
  identify -format "%w x %h %x x %y" IMAGE_NAME.FORMAT
+
# Imagemagick lets you also ''see sizes and pixels per inch'' from the command line:
 +
#:<syntaxhighlight lang="sh">
 +
identify -format "%w x %h %x x %y" IMAGE_NAME.FORMAT
 +
</syntaxhighlight>
  
 +
====== 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:
 
: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
+
cd guide/pt/figures            # In the repo, NOT the build directory structure
  ../../../util/adjust-dpi.sh
+
../../../util/adjust-dpi.sh
 
+
</syntaxhighlight>
: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:
 
 
 
  <figure pgwide="1">
 
    <title>This is the text that will appear in the List of Figures</title>
 
    <screenshot>
 
    ...
 
    </screenshot>
 
  </figure>
 
  
 
== Maintenance ==
 
== Maintenance ==
Line 300: Line 393:
 
::: Number negative 1 (&minus;1): <tt>&amp;minus;1</tt>
 
::: Number negative 1 (&minus;1): <tt>&amp;minus;1</tt>
 
::: Formula GROSS_SALE &minus; TOTALBUY: <tt>GROSS_SALE &amp;minus; TOTALBUY</tt>
 
::: Formula GROSS_SALE &minus; TOTALBUY: <tt>GROSS_SALE &amp;minus; TOTALBUY</tt>
:: See http://www.thepunctuationguide.com/index.html for guidance on using English language punctuation,  including  <tt>&amp;ndash;</tt> and <tt>&amp;mdash;</tt>.
+
:: See https://www.thepunctuationguide.com/index.html for guidance on using English language punctuation,  including  <tt>&amp;ndash;</tt> and <tt>&amp;mdash;</tt>.
  
 
* In the current state of this page there are many more. Have a look at the recently reworked chapters. If you have some free time, add them here.
 
* In the current state of this page there are many more. Have a look at the recently reworked chapters. If you have some free time, add them here.
Line 308: Line 401:
  
 
* GNOME desktop environment
 
* GNOME desktop environment
* Clearlooks theme
+
* Under ''GTK2'' we used the '''Clearlooks''' theme. For ''GTK3'' '''Adwaita''' is the default theme.
 
* text besides icon
 
* text besides icon
 
* font: Sans. 9 point for application and 11 point for window title
 
* font: Sans. 9 point for application and 11 point for window title
Line 314: Line 407:
  
 
[[Category:Documentation]]
 
[[Category:Documentation]]
 +
 +
[[Category:Development]]
  
 
[[Category:Translation]]
 
[[Category:Translation]]

Revision as of 21:04, 23 March 2019

These instructions describe the process to change the Tutorial & Concepts Guide and the Help manuals.

If you are interested in translating the documentation, you should read Translating the GnuCash Guide and Help, too.

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 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 the change sequence, 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.
  • 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: ImageMagick is suggested because it is used by /util/adjust-dpi.sh.

Initial Steps

  • You will need to obtain a local copy of the files from the GnuCash repository, which is called cloning. The cloned copy is what you will work on. See git for more information.
  • To stage your changes, you will need an appropriate directory structure.
See Initializing Documentation Build Environment for more.
  • 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 Bugzilla Documentation Bug

Create a Bugzilla bug if one does not already exist.

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.

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.

Ensure The Build Directory Is Up To Date

As the source files get changed on your machine and on the remote repositories, the files configure.ac and Makefile.am can change. If either of these files changes, you should run autogen.sh and configure again to make sure that changes are incorporated. This might occur because you changed it yourself or because someone else committed a change in git.

If you are not sure whether or not these files have changed, the safest course is to run these commands every time you pull.

Remember that these commands are issued from the build directory; if you do not yet have your build directory set up, consult Initializing Documentation Build Environment.

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/$USER/code/gnucash-docs/help/C

The English Tutorial and Concepts Guide source XML files are in

/home/$USER/code/gnucash-docs/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

Examples of commonly-used tags include: chapter, sect1 ... sect5, simplelist, orderedlist, list item, para and their corresponding closing tags.

You can find a complete reference to DocBook in The Definitive Guide. Chapter 2: Creating DocBook Documents may be of particular assistance.

Since GnuCash 3.3
The documents use XInclude
<xi:include href="Help_ch_Intro.xml" />
instead of file inclusion by
 <!ENTITY SYSTEM ...>
and most other <!ENTITY ...> elements moved in the new Document Type Definition (DTD) gnucash-docs/docbook/gnc-docbookx.dtd. Each file needs now a header
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book SYSTEM "gnc-docbookx.dtd">
to be syntactical correct and find the entities.

In particular, note that:

  • Wherever possible you should use the Definitions <!ENTITY name ...> from our gnc-docbookx.dtd and the base file gnucash-guide.xml or gnucash-help.xml as &name;.
  • 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.

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.

This 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 Autotools from the change: The Makefile.am located in the same folder as the base XML file. Again, you must edit the file list in this file to reflect the changes you have made to the file list. Makefile.am must include all files listed in the <xi:include ...> section of the base XML file in its entities list.
    Note
    There are Makefile.am 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.
    Important
    Because you have changed Makefile.am, you will need to rerun ../configure, as described in Initializing Documentation Build Environment.
  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
    
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.

Telling the Program of a New Help Context

Ask a developer to add your chapter, section, table or whatever id to the list
/** Links in the Help Files *****************************************/
#define HL_USAGE             "usage"
:
of gnucash/gnome-utils/gnc-ui.h

and use it as help context of its associated GUI elements.

Validate Your Changes

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

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

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

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

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

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

To validate all the guide xml files for all languages:

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

To validate all the guide and help xml files:

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

Then:

make check

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

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 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 xmllint command (I.e. the output from make check).

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).

Ensure Only Expected Changes Have Been Made

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

The following command will show any changes to unstaged files

git diff

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

git status

Proofread in HTML

After you have tested the integrity of the XML using xmllint (make check) and have verified that the difference file shows the correct changes, then 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 this command exactly as written in a terminal, from the appropriate directory within the build directory structure:

 cd [appropriate directory or sub-directory within the build directory structure]
 make html

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

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

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

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

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

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

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

or

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


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

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

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

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

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/file
git commit

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

 git commit -a --amend

But --amend should only be used as long, as you did not publish your commit by pushing it to some public github repository.

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

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

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

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

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

 git log -p path/to/file

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 pull request, or by creating and uploading a patch.

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 Images

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 Clearlooks engine has been the default theme of GNOME 2 since version 2.12. The utility adjust-dpi.sh uses the following programs

  • identify from ImageMagick, a nice toolset to manipulate images or query their parameters,
  • awk from gawk
  • bc from bc.

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 is the text that will appear in the List of Figures</title>
    <screenshot>
      <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>

Display and Print Targets

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 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 limit the width of

image presentations on screen to 510px
and 14 cm on paper, we get 2 different cases for our entry:
width <= 510px
and insert
      <imageobject>
        <imagedata fileref="figures/Report_Screen.png" format="PNG"
                   srccredit="your name"></imagedata>
      </imageobject>
width > 510px
Use two <imageobject> tags, as shown below:
      <imageobject role="html">
        <imagedata fileref="figures/Help_Pref_AccntPeriod.png" format="PNG"
                   srccredit="your name" width="510px"></imagedata>
      </imageobject>
      <imageobject role="fo">
        <imagedata fileref="figures/Help_Pref_AccntPeriod.png" format="PNG"
                   srccredit="your name"></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.
Note
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.

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.
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
Old Method
  1. To convert the dpi of a bunch of images do this from a terminal window:
    ls *.png > list
    for i in `cat list`; do convert -units PixelsPerInch -density 144 "$i" "$i"; done
    
    The first line creates the file "list" with a list of all png files in the current directory
    The second and third lines applies a dpi of 144 to all images listed in the "list" file
  2. Imagemagick lets you also see sizes and pixels per inch from the command line:
    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:
cd guide/pt/figures            # In the repo, NOT the build directory structure
../../../util/adjust-dpi.sh

Maintenance

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

Text conventions

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

Graphics conventions

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

  • GNOME desktop environment
  • Under GTK2 we used the Clearlooks theme. For GTK3 Adwaita is the default theme.
  • text besides icon
  • font: Sans. 9 point for application and 11 point for window title