Difference between revisions of "Documentation Improvement"

Revision as of 10:58, 20 October 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

with each chapter in a separate file.

Small Changes

You can try Simple Pull Request for small changes like fixing typos. It requires only a web browser.

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

The recent details are in Requirements in the README file. But here it is probably better explained: You will need the following software:

Version Control System

To manage your changes of the source text, you will install Git.

Build System

To check and install your version with make commands CMake is used.

You can now edit text or add/update images. That will require:

Editing Text

To edit the source files, you will need to have a plain text editor. Any text editor will do, as long as it can save your files without extra markup. But some editors or IDEs offer Syntaxhighlighting and perhaps other specific tools for Docbook or at least XML.

Illustrations

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

Screenshots

Creation

the built-in PrintScreen of your OS or desktop environment,

Manipulation

Our script util/adjust-dpi.sh uses the following programs

identify—and in other instructions convert

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.

Finally to control the resulting output:

html

any web browser—This is the minimum requirement.

docbook

Gnome's help browser Yelp—This is desired.

Alternatively Kde's help browser KHelpcenter<tt> can be used.

PDF

any PDF viewer—This is recommended.

epub, mobi

<tt>calibre can display these mobile formats.

Initial Steps

You can start by following instructions in Initializing Documentation Build Environment to create a recommended base directory structure 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.

• To test the linkages between GnuCash and help files in Linux, see 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.

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.

Note

Most markups are ignored inside title elements, but you can still

<quote>multiword terms</quote>

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 you will need to announce it to several parts of the system to ensure that these new or deleted files get handled properly.

What to do exactly depends on the file type you are adding or deleting.

Additional xml files

New chapters or an appendix are typically added as xml files. It requires three changes

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 entities 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|manual}; ${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.

Additional images

Images can appear anywhere in the documentation as appropriate. They also require three modifications

1. The base XML file (i.e., gnucash-guide.xml or gnucash-help.xml) or any of the other xml files that form the full document. Images typically are included in xml nodes similar to

   <figure id="fig-fil-imp-match" pgwide="1">
     <title>The Generic Transaction Import Matcher Window</title>
     <screenshot id="ImportMatcherScreenShot">
       <mediaobject>
         <imageobject role="html">
           <imagedata fileref="figures/Import_Transaction_matcher_1.png"
             srccredit="David Cousens" width="&img-w;"/>
         </imageobject>
   
         <imageobject role="fo">
           <imagedata fileref="figures/Import_Transaction_matcher_1.png"
             srccredit="David Cousens"/>
         </imageobject>
   
         <caption>
           The import transaction matcher window after opening a file to import
         </caption>
       </mediaobject>
     </screenshot>
   </figure>
   

   Add or remove a similar block for your the image you wish to add or remove—details in #Screenshots And Other Images.
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 figures 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}/figures/${FILENAME} # ${MODULE}={guide|manual}; ${LOCALE}={C|de|it...}; ${FILENAME}=image to add
   git rm ${MODULE}/${LOCALE}/figures/${FILENAME} # to remove it - also from your filesystem! See 'git help rm' for other options.
   

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

Formal Checks

This checks are mandatory.

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.

Appearance Check: 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.

Completeness Check: 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-5.9.tar.gz from your ${BUILDDIR} again.

Content Checks

Context

Because we make more and more use of XRefs, we have to provide the jumping reader with enough context. Either get the list of xrefs

grep -inrF '<xref' manual/C/*.xml

# Get the list of id's in your working area, e.g.
grep -inrF 'id=' manual/de/ch_Tools_Assistants.xml
# For each id get the links, e.g.
grep -inrF 'linkend="finance-quote-scheduler"' manual/de/*.xml

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.

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.

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

$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

1. Main file gnucash-{guide|help}.xml
   1. <bookinfo> section

      contains the metadata, which can also be shown as About from the documents start page. Verrify the first (=recent) <copyright> entry.

   2. <preface id="authors"> section
      1. contains a alphabetical <author> list,
      2. translations also a <othercredit role="translator"> list.
2. Insert your name into 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

Todo

At some point the maintainer should simplify this.

Commit Your Changes

Once you're satisfied with your changes, it's time to commit them.

 git commit -a

(-a also causes git to notice and commit any deleted files)

git add path/to/file1 [path/to/file2 …]
git commit

git commit -a --amend

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.

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

• DocBook XSL: The Complete Guide of its processing

[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

• Tutorials at w3schools.com about XML, XSLT, DTD, …

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

• blind people using a screenreader and
• users of Text-based web browsers

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

• browse or download the glossary at Weblate in several formats,
• view its source 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 <LANGUAGE>.po in https://github.com/Gnucash/gnucash/blob/maint/po/

GUI elements

GNOME Human Interface Guidelines and

Recommended Terminology (2.32)

• There are variable definitions, ENTITY in docbook terminology, in the GnuCash specific extension of the DocBook DTD, which must be used:

e.g. for future changes to revision numbers, docbook/gnc-docbookx.dtd defines variable vers-stable

<!ENTITY vers-stable "5.9">

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>

in the manual

are better than <itemizedlist>;

<example>

They get listed in the table of content. They get marked like blockquote or procedure with a sidebar. They can not contain tables or figures. So they are more for short textx like a paragraph.

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> is intended for formal descriptions <cmdsynopsis>.

<programlisting>, <screen>

for complexer forms or data files can have a language attribute, which produces in yelp syntaxhighlighting. The in docbook known language highlighters are listed in xsl/1.79.2/highlighting^[2] .

• 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.^[3]

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