Difference between revisions of "Test Documentation in Linux"

Revision as of 15:22, 20 October 2022

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. This documentation gets still installed into the old GNOME 2 standard help directory hierarchy.

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,

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

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

Install Development GnuCash Locally

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

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

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

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

 /home/$USER/code/gnucash-install

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

At first verify, what is already set: echo ${XDG_DATA_DIRS}

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:/usr/local/share:/usr/share" $GCASH/bin/gnucash &

That last line, with XDG_DATA_DIRS, is the crux of it. That environment variable tells GnuCash, among other things, where to look for the documentation. In fact, it tells any tool which 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 ghelp:gnucash-help#Using-Help &
# 'ghelp:' or 'gnome-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 ghelp:$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

# 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 ghelp:$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