Difference between revisions of "Documentation Improvement"

Latest revision as of 11:57, 25 April 2024

These instructions describe the process to update or extend the Tutorial & Concepts Guide and the Manual. Finally they should consist of:

A: Technical Reference: Manual, former Help

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.

Note

The instructions below have been adapted for the documentation related to GnuCash 5.0 or more recent. This includes the stable branch in git at the time of this writing.^[1] If you are looking for instructions to improve older documentation releases, please refer to an older version of this page.

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 DocBook to provide structure. Later in the process, the DocBook 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 can be used.

PDF

any PDF viewer—This is recommended.

epub, mobi

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 Manual source Docbook files are in

$HOME/code/gnucash-docs/src/C/manual

The English Tutorial and Concepts Guide source Docbook files are in

$HOME/code/gnucash-docs/src/C/guide

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

Notes

Most of the GUI elements should now already be defined as entities —see below— in the gui-*.dtd files.

See DocBook Guide for other details like meaning and syntax.

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 docbook-dtd contain already entities for many special symbols like mathematical or typographical…

Select them from the detailed lists XML Entity Definitions for Characters (3rd Edition) and

use unified alphabetical list at W3C to avoid overwriting.

Note

Whe prefer docbook tags like <quote>text</quote> over hardcoding in entities “text”. The tag is easier to read and less localization work.

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="ch_Intro.docbook" />

instead of system entities like

 <!ENTITY SYSTEM ...>

and most other <!ENTITY ...> elements moved into 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 like

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book SYSTEM "gnc-docbookx.dtd">

to be syntactical correct and find the entities. Note that 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 are 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="*.docbook" --include="*.po" --exclude-dir=".git" C/manual/

to get the list from the english manual. The pattern "*.po" is currently only required for Italian. '--exclude-dir=".git"' is usually only recommended for the top source directory.

Commands to grep current internal references

From the top source directory run

# the usual way
grep -inrF "linkend=" --include="*.docbook" --include="*.po" C/manual/
# some are behind URLs like https://code.gnucash.org/docs/
grep -inrF "url=" --include="*.docbook" --include="*.po" C/manual/
# Other dependencies: xinclude's href and imagedata fileref
grep -inrF "ref=" --include="*.docbook" --include="*.po" C/manual/

Titles

Avoid leading articles as they look ugly in the display of links. Titles should be unique, because the <book> has exactly one List of Tables, a List of Figures …, which are visible in HTML, pdf …. 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 Docbook Files

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

1. The documents base file (i.e., guide/index.docbook or manual/index.docbook). This file includes

   <xi:include href="type_Name.docbook" />
   

   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
   • 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 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 ${LOCALE}/${MODULE}/${FILENAME} # ${LOCALE}={C|de|it...}; ${MODULE}={guide|manual}; ${FILENAME}=file to add
   git rm ${LOCALE}/${MODULE}/${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/C/manual or $HOME/code/gnucash-docs/src/C/guide) 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 file (i.e., index.docbook) or any of the other Docbook files that form the full document. Images typically are included in Docbook 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 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 one --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 ${LOCALE}/${MODULE}/figures/${FILENAME} # ${LOCALE}={C|de|it...}; ${MODULE}={guide|manual}; ${FILENAME}=image to add
   git rm ${LOCALE}/${MODULE}/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:

   /** Documentation references ****************************************/
   :
   #    define DF_GUIDE         "gnucash-guide"
   #    define DF_MANUAL        "gnucash-manual"
   :
   

2. Links in the Help Files (id):

   /** Links in the Manual *********************************************/
   #define DL_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 DF_* 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 Docbook 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 Docbook files for the C (English) language:

     make C-guide-check
     

   • all the guide and manual Docbook files for the C (English) language:

     make C-check
     

   • all the guide and manual Docbook files:

     make check
     

So generally the check parameter to make is of the form <language>-<document>-check. You can omit <document>- or <language>-<document>- to widen the scope of the check.

Tip

You can list all the check targets by make help | grep check

Note

xmllint works by loading the main index.docbook file of the current document's directory together with all other Docbook files referenced in this main file and then checks all the files.

xmllint output

• If your module(s) are free of syntax 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 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' C/manual/*.docbook

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

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 source files 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' is not required, if you configured CMake to install into your home directory:
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

Kde's KHelpcenter and Gnome's help viewer yelp can both display docbook documents:

LANG=$LANG XDG_DATA_DIRS=$PREFIX/share:$XDG_DATA_DIRS yelp help:gnucash-manual
# or
LANG=$LANG XDG_DATA_DIRS=$PREFIX/share:$XDG_DATA_DIRS khelpcenter help:gnucash-manual
# Note 1: Relace $PREFIX by that which you used in your CMake configuration.
# 2. If you store 'export XDG_DATA_DIRS=$PREFIX/share:$XDG_DATA_DIRS' in ~/.bash.rc, it will be set on each login and you can omit it here,
# 3: gnucash-manual for the manual can be replaced with gnucash-guide to view the <q>tutorial and concepts guide</q>.

These at first sight complicated commands combine temporarily setting two environment variables (LANG and XDG_DATA_DIRS) with the actual commands (yelp or khelpcenter). Both the LANG=... and XDG_DATA_DIRS=... may be omitted under certain conditions as explained below. If you do need them, you should replace $LANG and/or $PREFIX as explained further below.

LANG

If your shell runs in the same language as the document you want to show you can omit this part, and the commands will become

XDG_DATA_DIRS=$PREFIX/share:$XDG_DATA_DIRS yelp help:gnucash-manual
# or
XDG_DATA_DIRS=$PREFIX/share:$XDG_DATA_DIRS khelpcenter help:gnucash-manual

Otherwise, replace $LANG with the proper language code (C, de, pt, ...)

XDG_DATA_DIRS

contains a list of directories in which to look for (among others) documentation bundles. Depending on which set of built/installed documentation you want to test you may or may not have to set this environment variable. In general if the existing XDG_DATA_DIRS list of directories contains the $PREFIX/share directory that contains your set of documentation under test, you can omit the XDG_DATA_DIRS part of the command above and hence it would become:

LANG=$LANG yelp help:gnucash-manual
# or
LANG=$LANG khelpcenter help:gnucash-manual

For completeness if both XDG_DATA_DIRS and LANG are already correct, you can omit both:

yelp help:gnucash-manual
# or
khelpcenter help:gnucash-manual

To clarify what the $PREFIX/share can be:

• If you want to test the documentation as generated in your build directory, $PREFIX should be the path to your build directory (referred to as ${BUILDDIR} in these instructions)
• If you want to test the documentation after installation (that is after having run sudo make install), something should be whatever you set as CMAKE_INSTALL_PREFIX when you first ran cmake.
• If you didn't set CMAKE_INSTALL_PREFIX, sudo make install will install the documentation in a default location (/usr/local/share). In this case you can omit the XDG_DATA_DIRS part from the commands
• If you don't want to specify the XDG_DATA_DIRS part each time you run the command, you can also add your preferred documentation path (as explained above either in your build directory or in a non-default install location) permanently to the XDG_DATA_DIRS environment variable. You can do so by adding this to your $HOME/.bashrc file:

  # Integrate my documentation test directory
  export XDG_DATA_DIRS=$PREFIX/share:${XDG_DATA_DIRS}
  # Be sure to replace $PREFIX according to the guidelines earlier in this section