Test Documentation in Linux

For our purposes, “Linux” means any system that’s not Windows or macOS. GnuCash uses Yelp, the GNOME help browser, to display its help — both the User Manual and the Concepts Guide.

Although not tested, it's very likely that a cygwin environment on Windows or a fink/homebrew/macports environment on macOS can equally be configured to run these documentation tests. GnuCash as installed from the Windows Installer package or the macOS/Quarz dmg on the other hand can not.

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

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

To test the changes,

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

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

Install Development GnuCash Locally

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

Without any special configuration the default installation directory will be /usr/local/... on Linux based systems. This is usually not a good location during development (or documentation changing), because this would require

$ sudo make install
[sudo] Password for root:

on each install run. So for development purposes we need to tell the build system to use another final location. This is done by setting CMakes CMAKE_INSTALL_PREFIX variable as shown in #Install Updated Documentation Locally. The installation directory should meet the following requirements:

it should be a writable location for the user that runs make install
it should not be in the default paths

/usr —used by your packet manager— or

/usr/local —used for your stable build.

Build and install GnuCash locally as per Building.

Install Updated Documentation Locally

Let's say you wish to build your modified documentation in /home/$USER/code/gnucash-docs-install

These are the commands for that

cd /home/$USER/code/gnucash-docs
mkdir build
cd build
cmake -G"Unix Makefiles" -DCMAKE_INSTALL_PREFIX=/home/$USER/code/gnucash-docs-install /home/$USER/code/gnucash-docs # Add any other needed options...
make install

Tell Development GnuCash Where to Find Docs

Similar to the ${PATH} environment variable, which contains a list of directories to search for commands, ${XDG_DATA_DIRS} stores one for data.

At first verify, what is already set:

$ echo ${XDG_DATA_DIRS}
/usr/local/share:/usr/share

This is the default, but some packages might have added additional directories. Then execute

GCASH=/home/$USER/code/gnucash-install          # For convenience if you built gnucash yourself, otherwise:
GCASH=/usr                                      # For convenience if you use a default installed gnucash
GCASHDOCS=/home/$USER/code/gnucash-docs-install # For convenience
GLANG=<your-language>                           # To choose a language different from your user default, can be any of the supported languages: C, de, it, pt, ja,...
# To start gnucash with your own help files:
# From the following line add only the parts which are not already set:
LANG=$GLANG XDG_DATA_DIRS="$GCASHDOCS/share:$XDG_DATA_DIRS" $GCASH/bin/gnucash &

That last line, with XDG_DATA_DIRS, is the crux of it. That environment variable tells GnuCash, among other things, where to look for the documentation. In fact, it tells any tool which follows XDG standards (and Yelp itself) where to look for documentation.

To directly start yelp with a document and optionally a topic, try the following:

LANG=$GLANG XDG_DATA_DIRS="$GCASHDOCS/share:$XDG_DATA_DIRS" yelp help:gnucash-manual/intro-to-gnucash &
# 'help:' is a shortcut to tell yelp to locate the document in its DATA_DIRS
# '/' separates the topic from the filename

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

Conclusion

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

Testing

Which tests to run when

After each Edit
1. run make check to detect typos;
2. run make install && yelp help:$DOCUMENT to test in yelp;
3. run make html and test the document in your preferred browser.
Before committing/pushing your changes
1. run xmlformat over changed files (don't forget to add the changes to git);
2. make pdf as the FOP module used by pdf, epub and mobi is stricter than others.
  It aborts on undefined table columns.
  
  It warns about unresolved links.

Efficient Work Process

To work parallel with your computer start 2 bash sessions and set the required environment variables once in the test shell. After saving your changes:

# Session 1, your build shell, in your BUILDDIR:
# Clear is optional to see only the current run
clear; make check

# Install the docbook files for testing with yelp
make install
# Start the HTML build
make html

# while it is running switch to …
# Session 2, your test shell e.g. in ~:
# Test 1: docbook
yelp help:$DOCUMENT

# after testing with yelp:
# Session 1 after everything else is fine:
# Important if you changed images, tables or other layout sensitive parts
make pdf

# while running or not
# Test 2: html
# open or refresh the document in the BUILDDIR with your browser

# Finally if you added, renamed or removed files:
make distcheck
# Test 3: pdf
# check the pdf file in the BUILDDIR
# verify, distcheck did not fail

# Before switching to other branches:
# If your branch added or renamed files, you should finally clean up both directories:
# Install dir:
make uninstall
# Build dir:
make clean

Test Documentation in Linux

Contents