Difference between revisions of "Test Documentation in Linux"

From GnuCash
Jump to: navigation, search
(Install Updated Documentation Locally: Drop autotools)
(Test Documentation in Linux: drop GNOME 2 standard)
 
(7 intermediate revisions by 3 users not shown)
Line 2: Line 2:
 
==Test Documentation in Linux==
 
==Test Documentation in Linux==
  
For our purposes, &ldquo;Linux&rdquo; means any system that&rsquo;s not Windows or {{mac}}. GnuCash uses <tt>Yelp</tt>, 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.  
+
For our purposes, &ldquo;Linux&rdquo; means any system that&rsquo;s not Windows or {{mac}}. GnuCash uses <tt>Yelp</tt>, 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 '''{{mac}}''' can equally be configured to run these documentation tests. GnuCash as installed from the Windows Installer package or the {{mac}}/Quarz dmg on the other hand can not.
 
Although not tested, it's very likely that a ''cygwin'' environment on '''Windows''' or a ''fink/homebrew/macports'' environment on '''{{mac}}''' can equally be configured to run these documentation tests. GnuCash as installed from the Windows Installer package or the {{mac}}/Quarz dmg on the other hand can not.
Line 19: Line 19:
 
''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.''
 
''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:
+
Without any special configuration the default installation directory will be <tt>/usr/local/</tt>... on Linux based systems. This is usually not a good location during development (or documentation changing), because this would require <syntaxhighlight lang="console>
 +
$ sudo make install
 +
[sudo] Password for root:
 +
</syntaxhighlight> 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 [[CMake]]s <tt>CMAKE_INSTALL_PREFIX</tt> 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 be a writable location for the user that runs ''make install''
* it should not be in the default paths /usr or /usr/local
+
* it should not be in the default paths  
 +
:<tt>/usr</tt> —used by your packet manager— or
 +
:<tt>/usr/local</tt> —used for your stable build.
  
Build and install GnuCash locally as per [[Building]]. Let's say you've installed GnuCash in
+
Build and install GnuCash locally as per [[Building]].
  /home/$USER/code/gnucash-install
 
  
 
===Install Updated Documentation Locally===
 
===Install Updated Documentation Locally===
Line 40: Line 44:
  
 
===Tell Development GnuCash Where to Find Docs===
 
===Tell Development GnuCash Where to Find Docs===
At first verify, what is already set: <SyntaxHighlight lang="sh" inline>
+
Similar to the <tt>${PATH}</tt> environment variable, which contains a list of directories to search for commands, ${XDG_DATA_DIRS} stores one for data.
echo ${XDG_DATA_DIRS}
+
At first verify, what is already set: <SyntaxHighlight lang="console">
</SyntaxHighlight>
+
$ echo ${XDG_DATA_DIRS}
 +
/usr/local/share:/usr/share
 +
</SyntaxHighlight> This is the default, but some packages might have added additional directories.
 
Then execute <SyntaxHighlight lang="sh">
 
Then execute <SyntaxHighlight lang="sh">
 
GCASH=/home/$USER/code/gnucash-install          # For convenience if you built gnucash yourself, otherwise:
 
GCASH=/home/$USER/code/gnucash-install          # For convenience if you built gnucash yourself, otherwise:
Line 50: Line 56:
 
# To start gnucash with your own help files:
 
# To start gnucash with your own help files:
 
# From the following line add only the parts which are not already set:
 
# 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 &
+
LANG=$GLANG XDG_DATA_DIRS="$GCASHDOCS/share:$XDG_DATA_DIRS" $GCASH/bin/gnucash &
 
</SyntaxHighlight>
 
</SyntaxHighlight>
  
Line 57: Line 63:
 
To directly start yelp with a ''document'' and optionally a ''topic'', try the following:
 
To directly start yelp with a ''document'' and optionally a ''topic'', try the following:
 
<SyntaxHighlight lang="sh">
 
<SyntaxHighlight lang="sh">
LANG=$GLANG XDG_DATA_DIRS="$GCASHDOCS/share:$XDG_DATA_DIRS" yelp ghelp:gnucash-help#Using-Help &
+
LANG=$GLANG XDG_DATA_DIRS="$GCASHDOCS/share:$XDG_DATA_DIRS" yelp help:gnucash-manual/intro-to-gnucash &
# 'ghelp:' or 'gnome-help:' is a shortcut to tell yelp to locate the document in its DATA_DIRS
+
# 'help:' is a shortcut to tell yelp to locate the document in its DATA_DIRS
# '#' separates the topic from the filename
+
# '/' separates the topic from the filename
 
</SyntaxHighlight>
 
</SyntaxHighlight>
  
Line 71: Line 77:
 
* After each Edit
 
* After each Edit
 
*# run <SyntaxHighlight lang="sh" inline>make check</SyntaxHighlight> to detect typos;
 
*# run <SyntaxHighlight lang="sh" inline>make check</SyntaxHighlight> to detect typos;
*# run <SyntaxHighlight lang="sh" inline>make install && yelp ghelp:$DOCUMENT</SyntaxHighlight> to test in yelp;
+
*# run <SyntaxHighlight lang="sh" inline>make install && yelp help:$DOCUMENT</SyntaxHighlight> to test in yelp;
 
*# run <SyntaxHighlight lang="sh" inline>make html</SyntaxHighlight> and test the document in your preferred browser.
 
*# run <SyntaxHighlight lang="sh" inline>make html</SyntaxHighlight> and test the document in your preferred browser.
 
* Before committing/pushing your changes
 
* Before committing/pushing your changes
Line 92: Line 98:
 
# Session 2, your test shell e.g. in ~:
 
# Session 2, your test shell e.g. in ~:
 
# Test 1: docbook
 
# Test 1: docbook
yelp ghelp:$DOCUMENT
+
yelp help:$DOCUMENT
  
 
# after testing with yelp:
 
# after testing with yelp:

Latest revision as of 14:51, 14 April 2023

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,

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