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

docbook/gnc-docbookx.dtd:

<!ENTITY url-wp-en "https://en.wikipedia.org/wiki/">  <!-- Append the desired topic -->

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

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

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

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.

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.

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:

Help Files:

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

Links in the Help Files (id):

/** Links in the Manual *********************************************/
#define DL_USAGE             "usage"
:

Ask a developer to

add your chapter, section, table or whatever id to the list and
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:

To validate one or more documents, first go to the top level build directory
```
cd $HOME/code/gnucash-docs/build
```
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

can be built

cd ${BUILDDIR} # Adjust this
make distcheck

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

or

# 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

and check that it is understandable.

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

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 Manual must be recreated in HTML and the results examined in your browser to verify that the online version appears and reads as expected.

Build the Guide or Manual document in HTML. Use any of the make commands below in a terminal, to generate (part) of the documentation in a chosen language and format:

cd ${BUILDDIR} # adjust this

# In any of the commands below, replace html with pdf, epub or mobi to build that other format
# In the following commands you can replace C (which stands for English) with any other language code we have a guide or manual for

# to build both guide and manual in all languages in html:
make html
# or to build both the guide and manual in English
make C-html
# or to build only the guide in English
make C-guide-html
# or to build only the manual in English
make C-manual-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 Manual.

The built html files with be placed in an automatically created directory, which if using the example directories will be:

$HOME/code/gnucash-docs/build/share/doc/<language>/gnucash-{guide|manual}

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.

To view the results in a web browser, in a file manager (or for Windows: Windows Explorer/File Explorer) double click on either:

$HOME/code/gnucash-docs/build/share/doc/C/gnucash-manual/index.html
# or
$HOME/code/gnucash-docs/build/share/doc/C/gnucash-guide/index.html

Publish your Authorship

Main file gnucash-{guide|manual}.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.
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 the respective 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.

Tell Git about New, Modified, Moved or Renamed and Removed 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 (Docbook or others, for example, illustrations), add (stage) them with the command:

 git add path/to/file

Reminder: Do not add files 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

Commit Your Changes

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

You can commit everything that's been changed with

 git commit -a

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

or you can commit a few files at a time with

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

If you need to make further changes, you can update your commit instead of creating a new one with

git commit -a --amend

But --amend should only be used as long, as you did not publish your commit by pushing it to some public github repository.

Exception

Only on your own, still open pull requests you are allowed to use either

Improvement:
```
git commit -a --amend
git push -f
```
Rebase your branch:
```
git rebase …
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.

If required, you can check committed changes to a particular file with

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/help/de/gnucash-manual/Help_ch_Transactions.docbook:3171: parser error : Entity 'ndash' not defined
                &ndash; 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, but documenting in US English, 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

Don't forget to reset them both before you continue to translate.

Image Formats

Screenshots

are ideally submitted in PNG format.

Related data files

Iif you are working on the docs, special on the guide, read data/README and store your data files in an appropriate subdirectory.

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.; Consider also to shrink columns of tables inside to the minimum without loosing content.; That way you can reduce downscaling of bigger GUI elements resulting in unreadable small text.
While capturing

Often you can avoid cropping by selecting Scope: Active Window
Hold down the Alt keys because GTK3 else hides the accelerator markings _.

Graphics showing relations

are best as 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^[2]: 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 Manual 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>640x480</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

share/doc/C/gnucash-guide/index.html

share/doc/C/gnucash-manual/index.html

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:

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.
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 pt/guide/figures            # In the source directory (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 pt/guide/figures            # In the source directory (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

with the recent program,
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/stable/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.docbook 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> or
<highlights>…</highlights>

. In some cases you should also consider to use <task>.

<task>

<tasksummary>…
<taskprerequisites>…
<procedure>…
<taskrelated>…

offers a good structure e.g. for tutorial lessons and the steps in assistants;

<procedure>

is better than <orderedlist>:

<procedure><title>An Example Procedure</title>
<step>
  <para>
    A Step
  </para>
</step>
<step>
  <para>
    Another Step with substeps:
  </para>
  <substeps>
    <step>
      <para>
        Substeps can be nested indefinitely deep.
      </para>
    </step>
  </substeps>
</step>
<step>
  <para>
    A Final Step
  </para>
</step>
</procedure>

;

<glosslist> ^[3]

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 texts 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 at least in yelp syntaxhighlighting. The in docbook known language highlighters are listed in xsl/1.79.2/highlighting^[4]. We specify also languages, which are currently not supported by docbook like csv as info for ourself.

Hyphens and dashes:

See https://www.thepunctuationguide.com/index.html for guidance on using English language punctuation, including – and —. 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, −). 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): −1

Formula GROSS_SALE − TOTALBUY: GROSS_SALE − 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 Manual 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. To save toner avoid dark themes!
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.^[5]

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

In one directory only all docbook files

Drop obsolete format="PNG":

for i in *.docbook; 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 *.docbook; do sed -i 's/510px/\&img-w;/' $i; done

Note

In sed's substitute command \ (backslash) is the escape character to quote characters with a special meaning like . (Catch all), & or in closing tags /.

In all languages, components and all used file types

for l in C de it ja pt ru zh; do
  for c in guide manual; do
    for x in docbook po; do
      for d in $l/$c/*.$x; do sed -i 's/ format="PNG"//' $d; done;
    done;
  done;
done;

Important

Before and after using sed, run grep to verify that you didn't change unintended parts:

clear; grep -in '510' *.docbook

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

Sometimes maintainers update the XSL. If you do it, #Optimize the Compression of it's images.

↑ Before version 5.0 stable was named maint and future master. Discussionand Announcement

↑

Caution

make check will send a false warning like

$ make de-manual-check
Note: following images exist but are not referenced in document gnucash-manual(manual):
    - /home/frank/git/gnucash-docs/de/manual/figures/main-window-small.png

because it does not scan xfc files for references.

↑ There is also a global glossary (currently in Guide, but should be moved to Manual)
↑ Docbook-xsl Chapter 27. Program listings: Syntax highlighting
↑ https://bugs.gnucash.orgshow_bug.cgi?id=798143 - Different order of splits in instructions and screenshot

[Git_branches_renamed-1] Before version 5.0 stable was named maint and future master. Discussionand Announcement

[2] 
Caution

make check will send a false warning like
$ make de-manual-check Note: following images exist but are not referenced in document gnucash-manual(manual): - /home/frank/git/gnucash-docs/de/manual/figures/main-window-small.png

because it does not scan xfc files for references.

[3] There is also a global glossary (currently in Guide, but should be moved to Manual)

[4] Docbook-xsl Chapter 27. Program listings: Syntax highlighting

[5] ttps://bugs.gnucash.orgshow_bug.cgi?id=798143 - Different order of splits in instructions and screenshot

[1]

[2]

[3]

[4]

[5]

@@ Line 1: / Line 1: @@
-'''''[Due to the the width of browser pages, all readers are invited to adjust page width to reading comfort by installing this free tool: "http:// lab dot arc90 dot com/experiments/readability/"]'''''
+[[Category:Documentation Development]]
+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.
-''These instructions describe the process to change both the GnuCash "Guide"
+;Small Changes: You can try [[Simple Pull Request]] for small changes like fixing typos. It requires only a web browser.
-and the GnuCash "Help" manuals as well as any other parts of GnuCash documentation.''
+If you are interested in translating the documentation, you should also read [[Documentation Translation]].
-==Preface and Introduction -- What to expect==
+For coordination of changes see [[Documentation Schedule]].
-The recommendation of experienced programmers who work with code and related documentation is to ''obtain a copy of the full set of the most recent documentation''. Nightly builds can be seen at [http://svn.gnucash.org/docs/ http://svn.gnucash.org/docs/]. Besides having the modules you think you will need to change, you will easily be able to update other files, if you discover additional places requiring a modification.
+;Note: The instructions below have been adapted for the documentation related to GnuCash 5.0 or more recent. This includes the <tt>stable</tt> branch in git at the time of this writing.{{Git branchs rename.ref}} If you are looking for instructions to improve older documentation releases, please refer to [https://wiki.gnucash.org/wiki/index.php?title=Documentation_Improvement&oldid=21341 an older version of this page].
-In addition, other persons could be making changes to parts of the documentation at the same time you are.  You will need to make sure any changes (others have made following your acquiring a set of the documentation) are included in what you will install.
+==Preface and Introduction — What to expect==
-After obtaining your full set of the documentation, you will be ''inserting your modifications'' into the proper places in the set of documents.  Modules in the set are formatted using XML.  Later in processing, the XML modules are converted to HTML versions for online easy viewing.  As a documentation support person, your task is to shepherd your enhancements through all stages from start to finish.
+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 [{{URL:wp}}Version_control version control] system (VCS)'' to coordinate contributions from disparate sources, as well as using [{{URL:wp}}DocBook 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.
-At each stage ''changes must be validated'' to assure that intended changes occur, and other unexpected changes found are understood and either accepted or rejected after proper analysis.
+'''These aspects require that documentation contributors learn and use several specialized tools to engage the process.'''
-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.
+The tools and the process are outlined in this page. For background on these tools, see [[Build_Tools|Build Tools]].
-For the sake of quality control there is a ''review process'' that you must use in order to make your change "official".  The above brief description when executed results in a file of changes.  These changes must be explained as to their purpose.  Accompanying the explanation in words is everything that makes up the substance of the change.  The term for this is "patch".  Whether you introduce a major restructuring or a small tweak, every thing is a "patch".
+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.
-Creation of the explanation and the content of the change you are making are combined in a ''bugzilla'' event, otherwise called a "bug".  In this usage bug means a statement of what is changing and why along with the content that will be the change when approved and applied to all the places needed.  It does not necessarily mean a problem is being corrected, enhancements are handled as bugs too.
+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.
-After creating your patch and presenting it in a bugzilla bug, usually a developer watching the [https://bugzilla.gnome.org/page.cgi?id=patchreport.html&product=GnuCash&patch-status=none bugzilla patchreport] will review it. If you see no reaction in the next days, you can inform them also on their list and ask for the review and approval. Your email should list a brief statement of what your bug is about. You also provide the Bugzilla bug ID number so it can be found and reviewed easily.
-If everything is accepted without requiring further work, your patch will be applied to the main set of documentation by a developer and you will be notified of that action.
+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).
-As your first act in getting started, become very familiar with the references given in the [[Documentation_Update_Instructions#References_to_Supporting_Technologies_Used|REFERENCES]] section following the [[Documentation_Update_Instructions#NOTES_for_each_of_the_above_steps|NOTES]] section below.
-==The Documentation Change Process -- What and How it happens==
+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.
-To write GnuCash documentation the following steps must be completed in the order given. [See the NOTES for each step, which are listed after all the steps! Also, when executing any command listed, do not use around the commands quotations of any sort.]
+The above brief description outlines the general documentation update process.
-'''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.
+It may be helpful to become familiar with the references given in the [[Documentation_Update_Instructions#References_to_Supporting_Technologies_Used|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 [{{URL:GH}}Gnucash/gnucash-docs/blob/stable/README#L19 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 <tt>make</tt> 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 [[:Category:IDE|IDE]]s offer Syntaxhighlighting and perhaps other specific tools for Docbook or at least XML.
+:;Illustrations: To illustrate your text with [[#Screenshots and Images|Screenshots and Images]], you can use  for
+::;Diagrams: any [{{URL:wp}}Scalable_Vector_Graphics SVG] able drawing program like '''OfficeDraw''' (available from [https://www.libreoffice.org/ LibreOffice] or [https://www.openoffice.org/ OpenOffice]),
+::;Screenshots:
+:::;Creation: the built-in <code>PrintScreen</code> of your OS or desktop environment,
+:::;Manipulation: Our script  <tt>util/adjust-dpi.sh</tt> uses the following programs
+::::;<tt>identify</tt>—and in other instructions <tt>convert</tt>: from [https://www.imagemagick.org ImageMagick], a nice toolset to manipulate images or query their parameters,
+::::;<tt>awk</tt>: from '''gawk''',
+::::;<tt>bc</tt>: from '''bc''',
+:::: but the later two are in most cases already installed.
+:::;Maintenance: [http://optipng.sourceforge.net/ 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 <tt>Yelp</tt>—This is desired.
+::Alternatively ''Kde'''s help browser <tt>KHelpcenter</tt> can be used.
+:;PDF: any ''PDF viewer''—This is recommended.
+:;epub, mobi: [https://calibre-ebook.com/ <tt>calibre</tt>] can display these mobile formats.
-# Use this command exactly as written to download to your own computer a full set of documentation files.
+===Initial Steps===
-#:<pre>git clone https://github.com/Gnucash/gnucash-docs gnucash-docs</pre>
+You can start by following instructions in [[Initializing_Documentation_Build_Environment|Initializing Documentation Build Environment]] to create a recommended base directory structure with the source files in place and ready to be edited.
-# Find the place in the documentation that you want to change; identify the file(s) that need to be changed to accomplish your documentation objective. Your changes should roughly follow the [http://library.gnome.org/devel/gdp-style-guide/stable/ GNOME Documentation Style Guide] of the [https://live.gnome.org/DocumentationProject/ GNOME Documentation Project].
-# Draft your text changes for each module that will be affected by your update.  For substantive changes to the documentation it frequently is helpful to open a text editor and develop your ideas there.  See [4] in the References section for a link to the jEdit text editor, which installs in both Linux and Windows operating systems.  If your changes are minor, you may skip this step and enter your changes directly into the XML modules.
-# Insert your changes into the XML file(s) affected.  Make your changes fit the XML tags in the manner of the existing documentation.  Adjust your XML tag structure so that the finished structure appears properly and as you intended in the HTML version of the documentation. Doing this might be easier by using a [http://www.dmoz.org/Computers/Data_Formats/Markup_Languages/XML/Tools/Editors/ specific XML Editor]. [http://sourceforge.net/projects/sernafree.mirror/ Serna-Free] is a more-or-less free DocBook editor which is much easier to use than a plain XML editor, but it introduces a lot of extraneous changes which must be removed before preparing a commit or patch ''You may have to return to this step should step 6 reveal a less than desirable arrangement of the data.''
-# Test that your xml file has no syntax errors by running ''xmllint'' on the '''main file''' ''gnucash-{guide|help}.xml''.  Use this command in a terminal:
-#:<pre>xmllint --valid --noout gnucash-guide.xml</pre>
-#:Repeatedly perform this step until no xml errors are found. Then move on to the next step.  If you become unable to identify an XML error, then send an email to the developers' list and ask for their help in understanding the error and making a change to remove it.  [The program ''xmllint'' is part of the package '''libxml'''.]
-# Build the Guide or Help file in HTML. Use this command exactly as written in a terminal (NOTE: there must be a space following the directory name 'output_html/' in the command below):
-#:<pre>xsltproc -o output_html/ ../../xsl/general-customization.xsl gnucash-guide.xml</pre>
-#:When updating the Help manual, change the above command's file name to be gnucash-help.xml.
-#:Review the results in your browser; if you need to make changes, do so, then rebuild and review again.
-# If you have added any files (e.g. illustrations) that should be included in your patch, add them to git as well:
-#:<pre>git add path/to/file </pre>
-# You can examine your changes with
-#:<pre>git diff</pre>
-#:This lists all modules changed and the exact places in the modules where the change(s) occur.
-# Commit your changes into your local repository with
-#:<pre>git commit -a</pre>
-#: This will open a text editor for you to enter a commit message. Please write a one-line (<80 character) summary line and if appropriate skip a line then add a moe detailed description. Please make sure that you break lines at < 80 characters.
-#: Update your local repository with any changes that might have been committed while you were working:
-#:<pre>git pull --rebase</pre>
-#: Repeat step 6 to ensure that the update didn't mess up your change. If you need to make further changes, you can use
-#:<pre>git commit -a --amend</pre>
-#:to update your commit instead of creating a new one.
-# Create a patch from your commit:
-#:<pre>git format-patch HEAD^</pre>
-#:This will produce a patch file named '0001-<your-summary>', substituting the first line from your commit message for <your-summary>, with spaces replaced by hyphens.
-# Create the documentation change as a bugzilla bug:
-#* At this [https://bugzilla.gnome.org/createaccount.cgi URL], register yourself to create an account.
-#* After your account has been created, Login to the [https://bugzilla.gnome.org/enter_bug.cgi?product=GnuCash section of bugzilla reserved for GnuCash].
-#* Enter your userid and password and press 'login'.
-#* After logging in you are at [https://bugzilla.gnome.org/enter_bug.cgi this page] and you can start the bug creation process by answering the questions on the page.
-#** In the comment box, explain the nature of the bug fix.
-#** Attach your patch to the bug.
-#* When you press commit, bugzilla creates the bug and a unique id for it.
-# Note the bug number.  You will be listed as wanting to be notified any time there is an update to the bug.  Monitor it until it is confirmed and installed to the trunk.
-==NOTES for each of the above steps==
+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|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|Test Documentation in Linux]].
-===Step 1 - Git Clone===
+==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.
-The terminal command will cause the documentation to be copied to your computer under the name you specify in the command.  Executing the command assumes that git has previously been installed successfully on your computer.  If the system finds that git is not installed, it ignores your request and replies with the correct command to download and install the package.
+'''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.
-:If you need to install git with a Linux package manager, make note of the module(s) that it tells you should be deleted.  Also, note the command it provides to delete such module(s).  Next install git with the install command given.  Note any instructions given during the install process and carry them out.  Finally, use the instruction first noted that tells you what module(s) to remove and carry out the remove instruction.
+===<span id="CreateBug"></span> Create a Place to Attach and Discuss Your Changes===
-In the git command "gnucash-docs" is the directory name where the checkout process places the full set of documentation modules.  You can use that name or some other.  Remember that the bash shell is case sensitive when typing commands and providing names.
+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 <tt>''foo''-draft</tt> can be the better choice.
+* finally a ''[[Setup_for_Pull_Requests|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.
-Avoid merge conflicts and merge commits by always using
+===<span id="UpdateLocal"></span>Update Your Local Copy===
-  git pull --rebase
+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|Setting Up Your System]].''
-to update your local repository.
-===Step 2 - find update location===
+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#Sync_your_local_master_or_maint_from_upstream_.28Pull_Requests.29|An Introduction to Git]].
-This means you have to read the documentation to find exactly where
+===<span id="IDLoc4Change"></span>Identify Location for Changes===
-the error is or the best place to insert the additional information
+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 [https://developer.gnome.org/documentation/guidelines/devel-docs.html GNOME Documentation Style Guide] of the [https://wiki.gnome.org/DocumentationProject/ GNOME Documentation Project].
-that improves the understanding of how the feature works or what its
-purpose is in the software.
-Experienced developers instruct that you should focus first on the
+'''Read the documentation carefully to find exactly where your change belongs.'''
-modules in either of these two directories (found in the step 1
-downloaded files): gnucash-docs/help/C or gnucash-docs/guide/C.
-Trying to open each file in each of those directories will show
+The English '''Manual''' source Docbook files are in
-whether there are any errors in the modules you downloaded.  If you
+:$HOME/code/gnucash-docs/src/C/manual
-find errors, ask a more experienced person whether these should first
+The English '''Tutorial and Concepts Guide''' source Docbook files are in
-be corrected before proceeding with your updates.  You can do that
+:$HOME/code/gnucash-docs/src/C/guide
-by email to gnucash-devel@gnucash.org.  If you choose this method, be
+The non-english files are in the corresponding locations with '''C''' replaced by a 2 character language code.
-sure to be a subscriber to that list in order to receive a prompt
-answer.  If you are not a subscriber, then your email will wait for
-the list manager to find  the time to address emails received from
-non-subscribers.
-It will be useful to have either a printed copy or a PDF copy [3] of
+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
@@ Line 112: / Line 107: @@
 interested in has already had a mention or treatment.
-===Step 3 - draft your update in a text file===
+===<span id="DraftChanges"></span>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 few and easily formulated, then you should be
+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 [https://en.wikipedia.org/wiki/Comparison_of_XML_editors specific XML Editor]. Additional resources for XML are listed in the [[#References to Supporting Technologies Used|References]] section for this step.
-able to skip this step and proceed to [[#Step 4 - place the draft changes in XML files]].
-If your update is adding something new or reworking existing text
+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.
-rather extensively, it will be very helpful to translate your ideas
-into words by using a text file not part of the existing
-documentation as a scratch pad to hone your expression of your ideas.
-When your ideas are clear and expressed as you think appropriate,
+The source documents are saved in the XML flavour of [[Glossary#D|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.
-then proceed to [[#Step 4 - place the draft changes in XML files]].
-===Step 4 - place the draft changes in XML files===
+;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.
-Because the source documents are saved in XML - or to be more precise [[Glossary#D|DocBook]] - code, all changes need to be added to the source modules in that manner.   Small changes can be made directly into the XML file itself.  Larger and extensive changes may first be prepared in a text editor and later inserted into the module(s) in their proper places.  Resources for XML are listed in the [[#Step 4|References]] section for this step.
+====Conventions====
+* You can find a complete reference to DocBook in [{{URL:dbk-tdg}}/docbook.html The Definitive Guide]. Search for <q>II. Reference</q> for the ''complete alphabetical list''.
+* But for beginners the element lists ''grouped by their function'' [{{URL:dbk-tdg}}/ch02.html Chapter 2: Creating DocBook Documents] is better. Ignore the confusing first part of the page and search for <q>Logical Divisions</q>.
+* Elements  of the '''graphical user interface''' (GUI) should have the respective markup e.g.for a label: <syntaxhighlight lang="xml" inline><guilabel>Accounts</guilabel></syntaxhighlight>. 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 <tt>gui-''*''.dtd</tt> files.
+::See [https://tdg.docbook.org/tdg/{{DocbookVersion}}/docbook.html DocBook Guide] for other details like meaning and syntax.
-Review the inserted and corrected text to verify that it is presented within the proper XML tags, using existing tags as a guide.  To read about XML and its tags, entities, and attributes, see the References section for links to resources.
+;Entities: are the <q>global abbreviations</q> in DocBook and ''should be used wherever possible''. They are usually ''defined'' in the form <Syntaxhighlight lang="xml"><!ENTITY appname "GnuCash"></Syntaxhighlight> in a DTD and ''used'' in the source docs like <Syntaxhighlight lang="xml"><title>&appname; Documentation</title></Syntaxhighlight>
+:There are several levels of definitions:
+:;W3C: usually part of the package <tt>docbook-dtd</tt> contain already entities for many special symbols like mathematical or typographical…
+:: '''Select''' them from the detailed lists [https://www.w3.org/2003/entities/2007doc/Overview.html XML Entity Definitions for Characters (3rd Edition)] and
+:: use [https://www.w3.org/2003/entities/2007/w3centities-f.ent unified alphabetical list at W3C] to '''avoid overwriting'''.
+::;Note: Whe prefer docbook tags like <Syntaxhighlight lang="xml" inline><quote>text</quote></Syntaxhighlight> over hardcoding in entities <Syntaxhighlight lang="xml" inline>&ldquo;text&rdquo;</Syntaxhighlight>. The tag is easier to read and less localization work.
+:; Gnucash-docs: Our main DTD <tt>gnc-docbookx.dtd</tt> got some modularization. We separated GUI elements in a language agnostic <tt>gui-struct.dtd</tt> and siblings for each language like <tt>gui-C.dtd</tt> or its translation <tt>gui-<language>.dtd</tt>.
-If text exceeds the vertical text border guides, you should not be alarmed that text outside the vertical border guides would be lost. These border guides show up when the XML module is opened, but are length of line indicators and not warnings that text should be moved within the guides.
+;File inclusion: ''Since GnuCash 3.3'' the documents use <tt>XInclude</tt> <SyntaxHighlight lang="xml">
+<xi:include href="ch_Intro.docbook" />
+</SyntaxHighlight> instead of <tt>system entities</tt> like <SyntaxHighlight lang="xml"> <!ENTITY SYSTEM ...></SyntaxHighlight> and most other <code><!ENTITY ...></code> elements moved into the new [{{URL:wp}}Document_type_definition Document Type Definition] (DTD) [https://github.com/Gnucash/gnucash-docs/blob/stable/docbook/gnc-docbookx.dtd gnucash-docs/docbook/gnc-docbookx.dtd] and its siblings in the same folder.
+:'''Now''' ''each file'' needs a header like <SyntaxHighlight lang="xml">
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book SYSTEM "gnc-docbookx.dtd">
+</SyntaxHighlight> to be syntactical correct and find the entities. Note that instead of <tt>book</tt> it can also be any other type like <tt>chapter</tt>, <tt>appendix</tt> …
-Apply the modules structural concepts to your own text after you have cut and pasted it into the XML file.  This is done by using the various '''XML tags''' in the existing text: ''chapter'', ''segment'', ''sect1'', ''sect2'', ''orderedlist'', ''list item'', ''para'' (to name just a few) and the corresponding closing tags. You should also use the '''Definitions''' ''<!ENTITY ...>'' from the main file where ever possible. See the references below these step notes for information about XML and docbook.
+;ID attributes: Many elements can contain an inside of the document ''unique'' <tt>id="'''chapter'''-more-specific-context"</tt> 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: <tt>Getting_Started.html</tt> might look nicer than <tt>pt01.html</tt>.
+:;Conventions: Lowercase, hyphenated terms, where the first stands for the chapter.
+:;Command to grep current definitions: From the top source directory run <syntaxhighlight lang="sh">
+grep -inrF "id=" --include="*.docbook" --include="*.po" --exclude-dir=".git" C/manual/
+</syntaxhighlight> 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 <syntaxhighlight lang="sh">
+# 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/
+</syntaxhighlight>
-;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 (gnucash-docs/help/C or gnucash-docs/guide/C) to determine what changes,if any, need to be made to modules outside your original assessment in step 2.
+;Titles: Avoid leading articles as they look ugly in the display of links. Titles should be ''unique'', because the <book> has ''exactly one'' <q>List of Tables</q>, a <q>List of Figures</q> …, which are visible in HTML, pdf …. One possibility to get consistent entries is the additional use of the element <q>titleabbrev</q>. For example, the representation of <syntaxhighlight lang="xml"><titleabbrev>Account Tree - File-Menu</titleabbrev></syntaxhighlight> in the <q>List of Tables</q> is more readable and looks better than <syntaxhighlight lang="xml"><title>Account Tree - File-Menu - Access to file, account operations and printing</title></syntaxhighlight> There are more in [[Docbook Conventions]].
+:;Note: Most markups are ignored inside title elements, but you can still <syntaxhighlight lang="xml"><quote>multiword terms</quote></syntaxhighlight>
-You can find an introduction to DocBook in [http://docbook.org/tdg51/en/html/ch02.html Creating DocBook Documents].
+;Linking: [http://www.sagehill.net/docbookxsl/Db5Tools.html#Db5LinkExamples Examples]
+:;Tip: If you do not plan to replace the URL by another text, use the short form <syntaxhighlight lang="xml"><link url="https://en.wikipedia.org/wiki/URL"/></syntaxhighlight> instead of <syntaxhighlight lang="xml"><link url="https://en.wikipedia.org/wiki/URL">https://en.wikipedia.org/wiki/URL</link></syntaxhighlight> The result is the same.
-====Publish your Authorship====
+;URLs: Because they will be used in several translations, put them as entities in [https://github.com/Gnucash/gnucash-docs/blob/stable/docbook/gnc-docbookx.dtd#L61 docbook/gnc-docbookx.dtd] to allow an easier update, if they change. The previous example would become
+:# docbook/gnc-docbookx.dtd: <syntaxhighlight lang="xml">
+<!ENTITY url-wp-en "https://en.wikipedia.org/wiki/">  <!-- Append the desired topic -->
+</syntaxhighlight>
+:# and in your text: <syntaxhighlight lang="xml">
+More details in <link url="&url-wp-en;URL"/>.
+</syntaxhighlight>
+:resulting in
+::More details in [https://en.wikipedia.org/wiki/URL 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.
-The first page, which can also be shown as ''About'' of the document is in the file '''<tt>gnucash-</tt>{<tt>guide</tt>|<tt>help</tt>}<tt>-C.omf</tt>'''. OMF means [http://en.wikipedia.org/wiki/Open_Media_Framework Open Media Framework]. Add a maintainer section with your data and check the other items like the date, which also needs an update.
+====<span id="DraftAddRemove"></span>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.
-Add your name and email address to the file AUTHORS. Create a separate patch for this change and ask to apply this patch also on gnucash/DOCUMENTERS - both in trunk and stable. The AUTHORS file can usually be shown in the packet manager while gnucash/DOCUMENTERS is shown in GnuCashs About->Credits->Documenters
+What to do exactly depends on the file type you are adding or deleting.
-===Step 5 - validate xml changes===
-Execute the <tt>xmllint</tt> command in a terminal after changing directory to the place where the changed modules are located.  For example, if the module you are hanging is in the <tt>guide/C</tt> directory, and you had downloaded the documentation files to a directory called <tt>GC-docs</tt>, then you would <tt>cd</tt> to the directory <tt>C-docs/guide/C.</tt>  It is when you are inside that high-level directory that you execute the command.
+===== Additional Docbook Files =====
-The file <tt>gnucash-guide.xml</tt> is found in the <tt>C</tt> subdirectory of <tt>GC-docs/guide/C</tt>.  Similarly, the file <tt>gnucash-help.xml</tt> would be in <tt>GC-docs/help/C</tt>.
-If your module(s) are free of XML errors, then the command returns a blank screen (if running in a terminal) or a blank file (if redirecting output to a file.
+New chapters or an appendix are typically added as Docbook files. It requires three changes
-XML errors must be removed before completing the remaining steps.  If you are not able to determine the source of the error, then help could be available via the developers list (gnucash-devel@gnucash.org). If asking for help, provide as much information as possible, including the results of the <tt>xmllint</tt> command.
+# The documents '''base file''' (i.e., ''guide/index.docbook'' or ''manual/index.docbook''). This file includes <SyntaxHighlight lang="xml">
+<xi:include href="type_Name.docbook" />
+</SyntaxHighlight> 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.
+# 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.
+# Tell [[Git]] to add/remove the file to/from the repository: <SyntaxHighlight lang="sh">
+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.
+</SyntaxHighlight>
+;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 (<tt>$HOME/code/gnucash-docs/src/C/manual</tt> or <tt>$HOME/code/gnucash-docs/src/C/guide</tt>) to determine what changes, if any, need to be made to modules outside your original assessment.
-===Step 6 - Proofread in HTML===
+===== Additional images =====
-Build a documentation set in HTML and examine the results in your browser. 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.
-===Step 7 - git diff===
+Images can appear anywhere in the documentation as appropriate. They also require three modifications
-This 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
+# 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 <SyntaxHighlight lang="xml">
-  git status -uno
+<figure id="fig-fil-imp-match" pgwide="1">
-The <tt>-uno</tt> 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
+  <title>The Generic Transaction Import Matcher Window</title>
-   git add path/to/new-file
+   <screenshot id="ImportMatcherScreenShot">
-and revert files that you didn't mean to change with
+    <mediaobject>
-  git checkout path/to/ignored-file
+      <imageobject role="html">
+        <imagedata fileref="figures/Import_Transaction_matcher_1.png"
+          srccredit="David Cousens" width="&img-w;"/>
+      </imageobject>
-===Step 8 - Commit your Changes===
+      <imageobject role="fo">
-Once you're satisfied with your changes, it's time to commit them. You can commit everything that's been changed with
+        <imagedata fileref="figures/Import_Transaction_matcher_1.png"
- git commit -a
+          srccredit="David Cousens"/>
-or you can commit a few files at a time with
+      </imageobject>
- git add path/to/file
- git commit
-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.
+      <caption>
+        The import transaction matcher window after opening a file to import
+      </caption>
+    </mediaobject>
+  </screenshot>
+</figure>
+</SyntaxHighlight>Add or remove a similar block for your the image you wish to add or remove—details in [[#Screenshots And Other Images]].
+# 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.
+# Tell [[Git]] to add/remove the file to/from the repository: <SyntaxHighlight lang="sh">
+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.
+</SyntaxHighlight>
-A patch should always be made against the most recent revision of the gnucash-docs project in subversion, so the next step is to get the latest version and re-apply your changes to it:
+==== Telling the Program of a New Help Context ====
-  git pull --rebase
+In [https://github.com/Gnucash/gnucash/blob/stable/gnucash/gnome-utils/gnc-ui.h gnucash/gnome-utils/gnc-ui.h] are 2 important sections:
-Most of the time this will work with no changes needed, but if someone else has committed a change in the same files that you did you'll get conflicts.
+# Help Files: <Syntaxhighlight lang="C">
-====Conflict Resolution====
+/** Documentation references ****************************************/
-<tt>git status</tt> will tell you which files have conflicts, and when you open one of them it will be marked with lines like
+:
- <<<<<<HEAD
+#    define DF_GUIDE         "gnucash-guide"
- ...
+#    define DF_MANUAL        "gnucash-manual"
- ======
+:
- ...
+</Syntaxhighlight>
- >>>>>>Your change summary
+# Links ''in'' the Help Files ('''id'''): <Syntaxhighlight lang="C">
-You'll have to edit each file with conflicts to remove those lines and get the section in between to read the way you want.
+/** Links in the Manual *********************************************/
-After you've fixed up a file, use <tt>git add path/to/filename</tt> to register the changes and when you've fixed them all and added them to the index, use <tt>git commit</tt> to re-commit them. This time in the editor you'll see a line
+#define DL_USAGE             "usage"
- Conflicts:
+:
-followed by a list of the files with conflicts. Be sure to remove those lines from the file, since you've resolved the conflicts.
+</Syntaxhighlight>
-There are other tools that can simplify cleaning up conflicted files, but they're beyond the scope of this tutorial.
+Ask a developer to
+# add your chapter, section, table or whatever <code>id</code> to the list and
+# use it together with its <tt>DF_*</tt> as help context in <tt>gnc_gnome_help(file_name, anchor)</tt> or where else it is associated GUI elements.
+;Fixme: Ways to find the ids generally in the code sources?
-After resolving your conflicts and recommitting, it's wise to re-do steps 5 - 7 to make sure that everything wound up the way you want it.
+===<span id="ValidateChanges"></span>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.
-===Step 9 - test documentation in Linux===
+;make check: For your convenience the build system comes with built-in rules to run <tt>xmllint</tt>. 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 <tt>$HOME/code/gnucash-docs</tt> and created a build directory called <tt>$HOME/code/gnucash-docs/build</tt>:
+:#To validate one or more documents, first go to the top level ''build'' directory <SyntaxHighlight lang="sh">
+cd $HOME/code/gnucash-docs/build
+</SyntaxHighlight>
+:#From there to validate
+:#* all the ''guide'' Docbook files for the ''C'' (''English'') language: <SyntaxHighlight lang="sh">
+make C-guide-check
+</SyntaxHighlight>
+:#* all the ''guide and manual'' Docbook files ''for the ''C'' (''English'') language: <SyntaxHighlight lang="sh">
+make C-check
+</SyntaxHighlight>
+:#* ''all the guide and manual'' Docbook files: <SyntaxHighlight lang="sh">
+make check
+</SyntaxHighlight>
+: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 <SyntaxHighlight LANG="sh" inline>
+make help | grep check
+</SyntaxHighlight>
-For our purposes, &ldquo;Linux&rdquo; means any system that&rsquo;s not Windows or Mac OS X. GnuCash uses Yelp, the GNOME documentation browser, to display its help--both the User Manual and the Concepts Guide. This documentation gets installed in the standard GNOME help directory hierarchy. If you want to test the changes you just made to the documentation without interfering with the already-installed versions, you need to (1) install a development version of GnuCash locally, (2) install the changed documentation locally, and (3) tell (1) where to find (2).
+;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.
-Note that you can't test changes to the docs in this way with the 2.4
+=====xmllint output=====
-series of releases. GnuCash only started using the system described
+* 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).
-[[#7.3 Tell development GnuCash where to find docs|below]] ''after'' the
+* If there are any errors, fix them and repeat this step until no errors are found.
-.4 series. So if you want to test interaction between GnuCash and the
+* If you are unable to fix an error, ask either using [[IRC]] or, see [[Mailing_Lists]], on <tt>gnucash-devel</tt>.
-help system, you really do need to do it with a development version of
-GnuCash.
-If you don&rsquo;t want to test interaction with GnuCash, see [[#7.3 Tell development GnuCash where to find docs|below]] for a way to do that.
+====Appearance Check: make pdf====
+;Tip: After passing <code>make check</code> it is a good idea to also run <SyntaxHighlight lang="sh">
+make <language>-<document>-pdf
+</SyntaxHighlight>
+:The <tt>xsltproc</tt> command used there is stricter than <SyntaxHighlight lang="sh" inline>make check</SyntaxHighlight> with the current settings. It will
+:* '''warn''' if it finds '''unresolved ID reference'''s and
+:* '''abort''' if a table row has more columns than declared.
-====9.1 Install development GnuCash locally====
+====Completeness Check: After Adding, Moving or Deleting Files====
+Verify a tarball
+# can be built <SyntaxHighlight lang="sh">
+cd ${BUILDDIR} # Adjust this
+make distcheck
+</SyntaxHighlight>
+# contains your new files.
+After success you can remove <tt>gnucash-docs-{{Version}}.tar.gz</tt> from your ${BUILDDIR} again.
-Build and install GnuCash locally as per [[Building]]. Let&rsquo;s say you&rsquo;ve installed in /home/$USER/code/gnucash-install.
+====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
+<syntaxhighlight lang="sh">grep -inrF '<xref' C/manual/*.docbook</syntaxhighlight> or
+<syntaxhighlight lang="sh">
+# 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
+</syntaxhighlight> and check that it is understandable.
-====9.2 Install updated documentation locally====
+===<span id="EnsureExpected"></span>Ensure Only Expected Changes Have Been Made===
+You should double check that there are no accidental changes to the documentation.
-<pre>
+The following command when run in the ''src'' directory will show any changes to unstaged files:
-$ pwd
+<SyntaxHighlight lang="sh">
-/home/$USER/code/gnucash-docs
+git diff
-$ ./autogen.sh # First time only, when building from repository copy
+</SyntaxHighlight>
-$ ./configure --prefix=/home/$USER/code/gnucash-docs-install # And your other preferred options....
+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.
-$ make install
+<SyntaxHighlight lang="sh">
-</pre>
+git status
+</SyntaxHighlight>
-====9.3 Tell development GnuCash where to find docs====
+===<span id="Proofread"></span>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 <Syntaxhighlight lang="sh">
+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
+</Syntaxhighlight> 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: <Syntaxhighlight lang="sh">
+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>.
+</Syntaxhighlight>
+: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<Syntaxhighlight lang="sh">
+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
+</Syntaxhighlight>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:<Syntaxhighlight lang="sh">
+LANG=$LANG yelp help:gnucash-manual
+# or
+LANG=$LANG khelpcenter help:gnucash-manual</Syntaxhighlight>For completeness if both XDG_DATA_DIRS and LANG are already correct, you can omit both:<Syntaxhighlight lang="sh">
+yelp help:gnucash-manual
+# or
+khelpcenter help:gnucash-manual</Syntaxhighlight>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 <tt>$HOME/.bashrc</tt> file:<syntaxhighlight lang="sh">
+# 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
+</syntaxhighlight>
-<pre>
+====In HTML and Other Formats====
-$ GCASH=/home/$USER/code/gnucash-install # For convenience&rsquo; sake
+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:
-$ GCASHDOCS=/home/$USER/code/gnucash-docs-install # For convenience&rsquo; sake
+* If you are using non-latin writing, are the fonts right in pdf?
-$ XDG_DATA_DIRS="$GCASHDOCS/share:$XDG_DATA_DIRS" $GCASH/bin/gnucash &
+* Are images displayed correctly?
-</pre>
+* Is the page layout OK in ebooks?
-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 uses Yelp (and Yelp itself) where to look for documentation. For example, try the following:
+The Guide or Manual must be recreated in HTML and the results
+examined in your browser to verify that the online version appears and reads as expected.
-<pre>
+Build the Guide or Manual document in HTML. Use any of the ''make'' commands below in a terminal, to generate (part) of the documentation in a chosen language and format: <Syntaxhighlight lang="sh">
-$ XDG_DATA_DIRS="$GCASHDOCS/share:$XDG_DATA_DIRS" yelp ghelp:gnucash-help &
+cd ${BUILDDIR} # adjust this
-</pre>
-That should open up your development-version GnuCash docs without first starting GnuCash itself. Handy if you don&rsquo;t need to test GnuCash along with the docs--i.e., if you&rsquo;re just updating sections that are already ''in'' the docs.
+# In any of the commands below, replace html with pdf, epub or mobi to build that other format
+# In the following commands you can replace C (which stands for English) with any other language code we have a guide or manual for
-====9.4 Conclusion====
+# to build both guide and manual in all languages in html:
+make html
+# or to build both the guide and manual in English
+make C-html
+# or to build only the guide in English
+make C-guide-html
+# or to build only the manual in English
+make C-manual-html
+</Syntaxhighlight>
-Now you can update both your local GnuCash and GnuCash docs freely and test their interaction.
+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 Manual.
-===Step 8 - build the HTML version of the documentation===
+The built html files with be placed in an automatically created directory, which if using the example directories will be: <Syntaxhighlight lang="sh">
+$HOME/code/gnucash-docs/build/share/doc/<language>/gnucash-{guide|manual}
+</Syntaxhighlight>
-This step means that after XML has been tested for integrity and the
+Review the results in your browser. [https://calibre-ebook.com/about Calibre] is a good choice as viewer for ebook formats (epub, mobi, ...).
-difference file has been determined to contain correct changes and only
-those, then the Guide must be recreated in HTML and the results
-examined to verify that the online version of the Guide presents an
-appearance and reads as expected.  The command to make this conversion
-is
-:<pre>xsltproc -o output_html/ ../../xsl/general-customization.xsl gnucash-guide.xml</pre>
+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.
-:;NOTE: there is a space following 'output_html/ and preceeding '../'
+To view the results in a web browser, in a file manager (or for Windows: Windows Explorer/File Explorer) double click on either: <Syntaxhighlight lang="sh">
+$HOME/code/gnucash-docs/build/share/doc/C/gnucash-manual/index.html
+# or
+$HOME/code/gnucash-docs/build/share/doc/C/gnucash-guide/index.html
+</Syntaxhighlight>
-:"output_html" is a directory that will automatically be created and filled with the files the command creates.  The directory name can be anything that makes sense to the person executing the command (output_html or something you choose).
+===<span id="PubAuthor"></span>Publish your Authorship===
-:Note the '/' following the file name 'output_html'.  When that character is in place, the directory (output_html) is created and  HTML modules placed in it.  When not present, the output_html modules are placed in the current directory.  Be sure to retain that '/' in its proper place!.
-:The command segment (“../../xsl/general-customization.xsl”) is a relative path to the XSL stylesheet used to turn the raw input XML into the output HTML that comprises the online version of the Guide. This command segment must be used exactly as written here.
+#Main file '''<tt>gnucash-</tt>{<tt>guide</tt>|<tt>manual</tt>}<tt>.xml</tt>'''
+## <tt><bookinfo></tt> section
+##: contains the metadata, which can also be shown as ''About'' from the documents start page. Verrify the first (=recent) <copyright> entry.
+## <tt><preface id="authors"></tt> section
+### contains a alphabetical <tt><author></tt> list,
+### translations also a <tt><othercredit role="translator"></tt> list.
+# 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 the respective 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.
-:If your changes involved no images, screenshots, icons, figures of any kind, then you are done at this point.  However, if your work does involve figures of any kind, they will not be viewable in the HTML files created up to this point.  In that case you should run this quick fix (3 command lines in sequence) in a terminal:
+===<span id="AddExtras"></span>Tell Git about New, Modified, Moved or Renamed and Removed 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 (Docbook or others, for example, illustrations), add (stage) them with the command:
+  git add path/to/file
+;Reminder:  Do '''not''' add files from your ''build'' directory structure.
-:<pre>cd output_html</pre>
+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
-:<pre>ln -s ../figures</pre>
+  git status -uno
-:<pre>ln -s ../../../stylesheet</pre>
+The <tt>-uno</tt> 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
-:After making this fix, any page containing any figure when reloaded should show the missing figure(s).
+===<span id="CommitChanges"></span>Commit Your Changes===
+Once you're satisfied with your changes, it's time to commit them.
+You can commit everything that's been changed with <syntaxhighlight lang="sh">
+ git commit -a
+</syntaxhighlight>
+:('''-a''' also causes git to notice and commit any ''deleted files'')
+or you can commit a few files at a time with <syntaxhighlight lang="sh">
+git add path/to/file1 [path/to/file2 …]
+git commit
+</syntaxhighlight> If you need to make further changes, you can update your commit instead of creating a new one with <syntaxhighlight lang="sh">
+git commit -a --amend
+</syntaxhighlight> But <tt>--amend</tt> should only be used as long, as you did not publish your commit by pushing it to some public github repository.
+;Exception: ''Only on your own, still open pull requests'' you are allowed to use either
+:# Improvement: <syntaxhighlight lang="sh">
+git commit -a --amend
+git push -f
+</syntaxhighlight>
+:# Rebase your branch: <syntaxhighlight lang="sh">
+git rebase …
+git push -f
+</syntaxhighlight>
-:Once your inspection shows that the online Guide is now acceptable in all respects, you should make certain that the output_html directory and its contents are not included in any respect in your patch.  To do that, before building the patch, remove the directory by this terminal command:
+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.
-:<pre>rm -rf output_html</pre>
+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.
-===Step 9 - Create the documentation change as a bugzilla bug===
+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.
-See [[#Step 9|reference]].
+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.
-==References to Supporting Technologies Used==
+If required, you can check ''committed'' changes to a particular file with <syntaxhighlight lang="sh">
+git log -p path/to/file
+</syntaxhighlight>
-===Step 1===
+===<span id="PullorPatch"></span>Create a Pull Request or a Patch===
-[1] http://svnbook.red-bean.com/en/1.5/svn.tour.html
+Once you have finalized your changes, you will notify the developer team of your changes, either by creating a —recommend— [[Git#Pull_Requests|pull request]], or —less desired— by [[Preparing_A_Documentation_Patch|creating and uploading a patch]].
+===After Merge: Verification===
-[2] http://wiki.gnucash.org/wiki/Subversion
+To avoid surprises after the release, you should verify one day after the merge of your pull request the nightly build:
+;All: browse {{BuildURL}}/docs/
+;Flatpak users: See [[Flatpak]] for how to enable the nightlies and update them.
+:Then run <syntaxhighlight lang="sh">flatpak run --command=sh org.gnucash.GnuCash
+yelp
+</syntaxhighlight>
+:If you watch <syntaxhighlight lang="console">
+I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
+/app/share/help/de/gnucash-manual/Help_ch_Transactions.docbook:3171: parser error : Entity 'ndash' not defined
+                &ndash; Importieren als eine neue Buchung. Manueller Eingriff er
+                       ^
+$
+</syntaxhighlight> 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.
-===Step 2===
+==References to Supporting Technologies Used==
-[3]  http://svn.gnucash.org/docs/guide/
-===Step 3===
+:[1] https://wiki.gnucash.org/wiki/Bugzilla
-[4]  http://www.jedit.org/
+:[2] https://github.com
+:[3]  http://www.jedit.org/
-===Step 4===
+:[4] https://en.wikipedia.org/wiki/DocBook
-[5]  http://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''.
+:* [http://www.sagehill.net/docbookxsl/index.html 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
+:* [https://www.w3schools.com/xml/default.asp Tutorials at w3schools.com about XML], XSLT, DTD, …
-[6]  http://www.docbook.org/  DocBook: The Definitive Guide
+==Additional Information==
-: Some Distributions have it as a package named like ''docbook-tdg''.
+===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 [https://www.gnome-look.org/content/show.php?content=19527 Clearlooks] engine, which has been the default theme of [https://help.gnome.org/misc/release-notes/2.0/ 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 <tt>Gnucash User</tt> 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'', but documenting in US English, 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
+::<tt>Edit->Preferences->Numbers, Date and Time->Date Format:</tt> '''ISO'''
+:*Don't forget to ''reset them both'' before you continue to translate.
-[7]  http://www.tldp.org/LDP/LDP-Author-Guide/html/tools-edit.html
+====Image Formats====
+;Screenshots: are ideally submitted in [{{URL:wp}}PNG PNG] '''format'''.
+:;Related data files: Iif you are working on the docs, special on the guide, read [{{URL:git}}gnucash-docs/blob/stable/data/README data/README] and store your data files in an appropriate subdirectory.
+:;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.
+:::Consider also to shrink ''columns of tables inside'' to the minimum without loosing content.
+:::That way you can reduce downscaling of bigger GUI elements resulting in unreadable small text.
+::;While capturing:
+:# Often you can '''avoid cropping''' by selecting <tt>Scope: ''Active Window''</tt>
+:# Hold down the <code>Alt</code> keys because GTK3 else hides the '''accelerator marking'''s <code>_</code>.
+;Graphics showing relations: are best as [{{URL:wp}}SVG SVG]. That would allow translators to replace in their copy the labels with their translation.
+;Callouts: images with annotations – are ideally created in [{{URL:wp}}GIMP GIMP]'s .xfc format with the
+:;screenshot<ref>
+;Caution: <tt>make check</tt> will send a false warning like <syntaxhighlight lang="console">
+$ make de-manual-check
+Note: following images exist but are not referenced in document gnucash-manual(manual):
+    - /home/frank/git/gnucash-docs/de/manual/figures/main-window-small.png</syntaxhighlight>
+:because it does not scan xfc files for references.</ref>: 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.
-[8]  http://www.netlingo.com/tips/html-code-cheat-sheet.php
+====Indexing====
+To add your image to the <tt>List of Figures</tt> at the start of the ''Manual'' or ''Tutorial and Concepts Guide'', put your screenshot in a figure tag, for example:
+<syntaxhighlight lang="xml">
+  <figure pgwide="1">
+    <title>This text will appear as header and in the List of Figures</title>
+    <screenshot>
+      <screeninfo>640x480</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>
+</syntaxhighlight>
+:;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 <tt>identify</tt> on each time the info is needed.
+:;textobject:Older parts have mistakenly a <textobject> instead of a figure title or a <nowiki><caption></nowiki>. For now move the content into the adequate tag. Only if you want to support
+::*blind people using a screenreader and
+::*users of [{{URL:wp}}Text-based_web_browser Text-based web browser]s
+::add a precise description of the image as textobject.
-[9]  http://svn.gnucash.org/trac/timeline
+; 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.
-[10]  http://wiki.gnucash.org/wiki/Git
+;Finally check your entry in the index context: Build the html flavour and open its Table of Content. That is currently
+::share/doc/C/gnucash-guide/index.html
+::share/doc/C/gnucash-manual/index.html
+:Scroll down to <tt>List of Figures</tt>. Is it
+:*unique and
+:*descriptive?
-===Step 6===
+====Display and Print Targets====
-[11]  http://svnbook.red-bean.com/en/1.5/svn.tour.cycle.html#svn.tour.cycle.resolve
+;Gnucash 4.10 change: The original instructions talked about <q>510px</q> 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 >={{Docs img-w}} this is the new default stored in [{{URL:GH}}Gnucash/gnucash-docs/tree/stable/docbook/gnc-docbookx.dtd#L82 docbook/gnc-docbookx].
+:* Older documents require a review of their <tt><imageobject></tt>s: If the '''width''' is
+::;&le; {{Docs img-w}}: remove <tt>width=&img-w;</tt> 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 <tt>adjust-dpi.sh</tt> …?
+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 {{Docs img-w}},
+:and 14 cm on paper, we get 2 different cases for our entry:
+;width <= {{Docs img-w}}: and insert: <syntaxhighlight lang="xml">
+      <imageobject>
+        <imagedata fileref="figures/Report_Screen.png"
+                   srccredit="your name" />
+      </imageobject>
+</syntaxhighlight>
+:;imagedata attributes:
+::;format: like <tt>format="PNG"</tt>is only required, if the filename extension is unknown by the processor. Please remove obsolete instances!
+:::See also: [{{URL:dbk-xsl}}GraphicSelection.html docbookxsl GraphicSelection], [{{URL:dbk-xsl}}GraphicFormats.html 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 > {{Docs img-w}}: Use two <imageobject> tags, as shown below: <syntaxhighlight lang="xml">
+      <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>
+</syntaxhighlight>
+:;imageobject attributes:
+::;role:"'''html'''" refers to ''display'' presentation on screens (the width is limited to {{Docs img-w}}), while
+::: "'''fo'''" processor (FOP) prepares it for ''printing'' of <tt>pdf</tt>
+:Now the image will fit on display and we can continue to adjust it for printing.
-===Step 9===
+==== Adjusting an Image's Dots Per Inch ====
-[12]  http://wiki.gnucash.org/wiki/Bugzilla
+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:
-===Steps 10 and 11 - Prepare and submit your patch===
+ size = pixels / dpi
-Once everything it tested out and you're confident that your changes are correct, you're ready to make a patch. This part is easy:
- git format-patch master
-Will create a set of patch files, one for each of your new commits. By default they'll be named with a 4-digit serial number followed by your summary line with the spaces replaced with hyphens. For example, if one of your commits had a summary "Better explanation of trading accounts",
-the corresponding patch name would be <tt>0001-Better-explanation-of-trading-accounts.patch</tt>.
-Attach your patches to a [[http://bugzilla.gnome.org GnuCash bug report]] and you're done!
+: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:
-== Images and screenshots ==
+/144 x 560/144 inches = 14 x 10 cm
-Screenshots for GnuCash documentation must be submitted in .png format or in .svg where applicable. It is better if you can use a theme similar to "clearlooks" for linux in order to keep consistency with existing images.
-The screenshots and images added to the GnuCash documentation must fit for two purposes: video printing (e.g. GNOME yelp) and paper printing (pdf creation). While the former has limits on image width in pixel (generally 510px) this limitation should be avoided for the latter.
-* Both requirements are met by '''using a doubled <imageobject> tag''' as shown next:
-            <imageobject role="html">
+:This will stay inside the available areas.
-              <imagedata fileref="figures/Help_Pref_AccntPeriod.png" format="PNG"
-                         srccredit="Cristian Marchi" width="510px"></imagedata>
-            </imageobject>
-            <imageobject role="fo">
-              <imagedata fileref="figures/Help_Pref_AccntPeriod.png" format="PNG"
-                         srccredit="Cristian Marchi"></imagedata>
-            </imageobject>
-:The "html" attribute refers to display visualization of the screenshots (the width is limited to 510px) while the "fo" attribute refers to pdf printing.
+: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.
-:So when you take a screenshot for inclusion in the GnuCash documentation, it should not be resized to 510 pixel width. Instead you should leave it as is, add the "html" attribute and fix the width to 510px as shown above (note that the width tag is not necessary if the image has a width smaller than 510px).
+;Tip: To query the properties of the existing images you can use <tt>Imagemagick</tt>s <tt>identify</tt> command: <syntaxhighlight lang="sh">
+# for many details of one file:
-* You need to accomplish another step in order to prepare the captured screenshot ''for printing'': '''change the dpi''' (dot per inch) of the image. The dpi is a printing resolution and is just a tag in the image (the higher the dpi is, the better the image will be printed on paper). The printing size, dpi and image pixel dimensions are in this relation:
+identify -verbose $FILENAME
- size = pixels / dpi
+# 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;
-: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)
+# or to create a list of the images width:
-:The available space in the A4 format pdf output is at max 15 cm so you can resize the screenshot by changing it's dpi. Normally (if you take a screenshot when the GnuCash window is almost at it's minimum) this value is set to 144 (see the GnuCash help figures). When the dpi is 144 our example screenshot will be printed as 800/144 x 560/144 inches = 14 x 10 cm and will stay inside the available areas.
+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
+</syntaxhighlight> The <code>%</code> parameters are explained in ImageMagick's doc package.
-:If the screenshot you are going to add to documentation is wider than 850 pixels, you should increase the dpi above 144 so that it's printed size remains less than 15 cm.
+===== Individual =====
+:The dpi of an image be changed in one of two ways:
-:So how can the dpi of an image be changed?
+:# Open the screenshot in an image editor (like [https://www.gimp.org 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.
-:Two ways:
+:# A faster approach uses Imagemagick, a library for image manipulation. From a terminal window, issue the following command:<syntaxhighlight lang="sh">
-:* Open the screenshot in [http://www.gimp.org The Gimp] and select Image->Print Size. In the dialog that will open set the X and Y resolution to the desired dpi (check that the unit in the right is set to the desired value - normally pixels/in). Press "Ok" and save the image.
+convert -units PixelsPerInch -density DPI IN OUT
+</syntaxhighlight>
-:* A faster approach uses Imagemagick a library for images 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).
-:To convert the dpi of a bunch of images do this from a linux terminal:
+===== 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:
+:<syntaxhighlight lang="sh">
+cd pt/guide/figures            # In the source directory (repo), NOT the build directory structure
+../../../util/adjust-dpi.sh
+</syntaxhighlight>
+:If that fails i.e. because [[#Required Software|dependencies]] are missing on your computer, you can still use the old method.
- ls *.png > list
+====== Old Method ======
- for i in `cat list`; do convert -units PixelsPerInch -density 144 "$i" "$i"; done
+:To ''convert the dpi'' of a bunch of images do this from a terminal window:
+:<syntaxhighlight lang="sh">
+for i in *.png; do convert -units PixelsPerInch -density 144 "$i" "$i"; done
+</syntaxhighlight>
+:This applies a dpi of 144 to all images of the current directory.
-:The first line creates the file "list" with a list of all png files in the current directory
+==== Optimize the Compression ====
-:The second and third lines applies a dpi of 130 to all images listed in the "list" file
+The tool OptiPNG tries to minimize the size of png files lossless:
+<syntaxhighlight lang="sh">
+cd pt/guide/figures            # In the source directory (repo), NOT the build directory structure
+optipng ${FILENAME}            # <- One file or all:
+for i in *.png; do optipng $i; done
+</syntaxhighlight>
+If it is too hard for you, ask the developers in your pull enhancement request to do it for you.
-:Imagemagick let's you also see sizes and Pixels per inch from the command line:
+== Maintenance ==
-  identify -format "%w x %h %x x %y" IMAGE_NAME.FORMAT
-:The following bash script can be used to automatically ''calculate and assign the right value of dpi to a list of png files''. To use it create a new file and copy the following text into it. Save it with a descriptive name (e.g. adjust-dpi), close and make the file executable (<tt>chmod +x adjust-dpi</tt> on linux). Move this file in the "figures" folder and run it from the command line (i.e. type <tt>./adjust-dpi</tt>).
+In this section are collected all the standards used to work on documentation.
- # make a list file of all the png figures
+===Content Updates===
- ls *.png > list
+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
+# with the recent program,
- for figure in `cat list`;
+# also with related wiki pages for updates.
- do
- # read width in pixel for the figure
- width=$(identify -format "%w" "$figure")
- # if the width is less than 90x14cm/2,54
- if [ "$width" -lt 496 ]; then
-   dpi=90
-   # convert dpi from pixelsperinch to pixelspercentimeter
-   dpi_cm=$(echo "scale=2; $dpi/2.54" | bc)
-   # read the existing dpi from figure as XX PixelsPerCentimeter
-   existing_dpi=$(identify -format "%x" "$figure")
-   # set the future dpi of figure as XX PixelsPerCentimeter
-   future_dpi="$dpi_cm PixelsPerCentimeter"
-   # apply new dpi only if it's changed from the existing
-   if [ "$existing_dpi" != "$future_dpi" ]; then
-     convert -units PixelsPerInch -density "$dpi" "$figure" "$figure"
-     echo "File $figure converted to $dpi dpi"
-   fi
- # if the width is more than 144x14cm/2,54
- else
-   if [ "$width" -gt 793 ]; then
-     # set the new dpi in function of the image size
-     dpi=$(echo "scale=0; $width*2.54/14" | bc)
-     # convert dpi from pixelsperinch to pixelspercentimeter
-     dpi_cm=$(echo "scale=2; $dpi/2.54" | bc)
-     # read the existing dpi from figure as XX PixelsPerCentimeter
-     existing_dpi=$(identify -format "%x" "$figure")
-     # set the future dpi of figure as XX PixelsPerCentimeter
-     future_dpi="$dpi_cm PixelsPerCentimeter"
-     # apply new dpi only if it's changed from the existing
-     if [ "$existing_dpi" != "$future_dpi" ]; then
-       convert -units PixelsPerInch -density "$dpi" "$figure" "$figure"
-       echo "File $figure converted to $dpi dpi"
-     fi
- # for figures with width between 496px and 793px use a dpi of 144
-   else
-     dpi=144
-     # convert dpi from pixelsperinch to pixelspercentimeter
-     dpi_cm=$(echo "scale=2; $dpi/2.54" | bc)
-     # read the existing dpi from figure as XX PixelsPerCentimeter
-     existing_dpi=$(identify -format "%x" "$figure")
-     # set the future dpi of figure as XX PixelsPerCentimeter
-     future_dpi="$dpi_cm PixelsPerCentimeter"
-     # apply new dpi only if it's changed from the existing
-     if [ "$existing_dpi" != "$future_dpi" ]; then
-       convert -units PixelsPerInch -density 144 "$figure" "$figure"
-       echo "File $figure converted to 144 dpi"
-     fi
-   fi
- fi
- done
- echo "Done!"
-== Maintenance ==
+After your changes were published you should ideally also replace the wiki content by a link to the doc section to avoid redundancy.
-In this section are collected all the standards used to work on documentation.
 ===Text conventions===
-* There are variable definitions in the main file, wich must be used e.g. for the in future changing revision numbers.
+;Style:
-* All accounts name must be tagged with <emphasis>: e.g. <emphasis>Expenses:Tax</emphasis>
+:Consider targets like [{{URL:Gnome-old-sg}}locale.html.en 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 [{{URL:wl}}/glossary/ Weblate] in several formats,
+::* view its source [{{URL:GH}}Gnucash/gnucash/blob/stable/po/glossary/gnc-glossary.txt 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 <tt><LANGUAGE>.po</tt> in {{URL:GH}}Gnucash/gnucash/blob/stable/po/
+:; GUI elements: [{{URL:Gnome-HIG}} GNOME Human Interface Guidelines] and
+::[{{URL:Gnome-old}}wordlist.html Recommended Terminology (2.32)]
+* There are variable definitions, '''ENTITY''' in docbook terminology, in the [{{URL:GH}}Gnucash/gnucash-docs/blob/stable/docbook/gnc-docbookx.dtd GnuCash specific extension of the DocBook DTD], which must be used:
+:e.g. for future changes to revision numbers, <tt>docbook/gnc-docbookx.dtd</tt> defines variable '''vers-stable'''
+::<tt><!ENTITY vers-stable "{{Version}}"></tt>
+:and guide/appendixa.docbook uses this variable like
+::<tt>The process works on &vers-stable; datafiles, and ought to ...</tt>
+* 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 '''markup'''s - refinement in progress:
+:;block:
+::;Components: ''chapter-like'' elements and many sections: should start with <syntaxhighlight lang="xml"><title>…</title>
+<abstract>Purpose and overview</abstract> or
+<highlights>…</highlights>
+</syntaxhighlight>. In some cases you should also consider to use <task>.
+::;<task>: <syntaxhighlight lang="xml"><tasksummary>…
+<taskprerequisites>…
+<procedure>…
+<taskrelated>…
+</syntaxhighlight> offers a good structure e.g. for ''tutorial lessons'' and the ''steps in assistants'';
+::;<procedure>: is better than <orderedlist>: <syntaxhighlight lang="xml">
+<procedure><title>An Example Procedure</title>
+<step>
+  <para>
+    A Step
+  </para>
+</step>
+<step>
+  <para>
+    Another Step with substeps:
+  </para>
+  <substeps>
+    <step>
+      <para>
+        Substeps can be nested indefinitely deep.
+      </para>
+    </step>
+  </substeps>
+</step>
+<step>
+  <para>
+    A Final Step
+  </para>
+</step>
+</procedure>
+</syntaxhighlight>;
+::;<glosslist> <ref>There is also a global glossary (currently in Guide, but should be moved to Manual)</ref>: for
+::: ''definitions'' at the begin of a chapter/section and the
+::: ''descriptions of the gui elements of a dialog'' like <syntaxhighlight lang="xml"><glosslist>
+  <title>GUI Elements of Dialog Foo</title>
+  <glossentry>
+    <glossterm>LABEL</glossterm>
+      <glossdef>
+        <para>The GUI-ELEMENT-TYPE LABEL …
+        </para>
+      </glossdef>
+    </glossentry>
+    …
+  <glosslist>
+</syntaxhighlight> 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 texts 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.
+::<s>All '''accounts''' named must be tagged with <emphasis>: e.g. <emphasis>Expenses:Tax</emphasis></s>
+::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 at least in yelp syntaxhighlighting. The in docbook known language highlighters are listed in [{{URL:GH}}Gnucash/gnucash-docs/blob/stable/xsl/1.79.2/highlighting/xslthl-config.xml#L30-L54 xsl/1.79.2/highlighting]<ref>[http://www.sagehill.net/docbookxsl/SyntaxHighlighting.html Docbook-xsl Chapter 27. Program listings: Syntax highlighting]</ref>. We specify also  languages, which are currently not supported by docbook like <q>csv</q> as info for ourself.
+* '''Hyphens and dashes''':
+: See https://www.thepunctuationguide.com/index.html for guidance on using English language ''punctuation'', including  <tt>&amp;ndash;</tt> and <tt>&amp;mdash;</tt>. You can also enter <code>AltGr</code>+<code>-</code> and <code>AltGr</code>+<code>Shift</code>+<code>-</code> directly on some keyboards.
+: To represent a ''negative number'' or subtraction:
+:: The typographically correct symbol to use is &minus; (U+2212, <tt>&amp;minus;</tt>). 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 <q>negative 1</q> (&minus;1): <tt>&amp;minus;1</tt>
+::: Formula <q>GROSS_SALE &minus; TOTALBUY</q>: <tt>GROSS_SALE &amp;minus; TOTALBUY</tt>
+* 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.
-* 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 Manual section.
+* Link '''related''' parts.
 ===Graphics conventions===
-all screenshots of the GnuCash windows must be captured under a GNOME Desktop environment with the following settings:
+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. To save toner avoid dark themes!
+* ''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 <tt>without [window] decoration</tt> 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.<ref>{{BugURL}}show_bug.cgi?id=798143 - Different order of splits in instructions and screenshot</ref>
+===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:
+:;In one directory only all docbook files: Drop obsolete<q> format="PNG"</q>: <Syntaxhighlight lang="sh">
+for i in *.docbook; do sed -i 's/ format="PNG"//' $i; done
+</Syntaxhighlight>
+::Escape <code>&</code> of entities in the replacement part as it has a special meaning in <tt>sed</tt>: <Syntaxhighlight lang="sh">
+for i in *.docbook; do sed -i 's/510px/\&img-w;/' $i; done
+</Syntaxhighlight>
+:;Note: In sed's '''s'''ubstitute command <code>\</code> (backslash) is the escape character to quote characters with a special meaning like <code>.</code> (Catch all), <code>&</code> or in closing tags <code>/</code>.
+:;In all languages, components and all used file types: <Syntaxhighlight lang="sh">
+for l in C de it ja pt ru zh; do
+  for c in guide manual; do
+    for x in docbook po; do
+      for d in $l/$c/*.$x; do sed -i 's/ format="PNG"//' $d; done;
+    done;
+  done;
+done;
+</Syntaxhighlight>
+;Important: Before and after using <tt>sed</tt>, run <tt>grep</tt> to verify that you didn't change unintended parts: <Syntaxhighlight lang="sh">
+clear; grep -in '510' *.docbook
+</Syntaxhighlight> <tt>clear</tt> cleans the console output to have only the result of the last run.
+;Help: To see the manual of <tt>sed</tt>, <tt>grep</tt> … run <Syntaxhighlight lang="sh">
+info sed
+</Syntaxhighlight> KDE users can better open <tt>info:/grep</tt> in <tt>konqueror</tt> or use <tt>khelpcenter</tt>.
+: Windows users might need to install <tt>MinGW</tt>.
-* GNOME desktop environment
+===Updating Stylesheets===
-* Clearlooks theme
+Sometimes maintainers update the XSL. If you do it, [[#Optimize the Compression]] of it's images.
-* text besides icon
+----
-* font: Sans. 9 point for application and 11 point for window title

Difference between revisions of "Documentation Improvement"

Latest revision as of 11:57, 25 April 2024

Contents

Preface and Introduction — What to expect

Setting Up Your System

Required Software

Initial Steps

The Documentation Change Process

Create a Place to Attach and Discuss Your Changes

Update Your Local Copy

Identify Location for Changes

Draft Your Changes

Conventions

Adding or Removing Files

Additional Docbook Files

Additional images

Telling the Program of a New Help Context

Validate Your Changes

Formal Checks

xmllint output

Appearance Check: make pdf

Completeness Check: After Adding, Moving or Deleting Files

Content Checks

Context

Ensure Only Expected Changes Have Been Made

Proofreading

In HTML and Other Formats

Publish your Authorship

Tell Git about New, Modified, Moved or Renamed and Removed Files

Commit Your Changes

Create a Pull Request or a Patch

After Merge: Verification

References to Supporting Technologies Used

Additional Information

Screenshots And Other Images

Desktop Themes for Screenshots

Image Formats

Indexing

Display and Print Targets

Adjusting an Image's Dots Per Inch

Individual

All at once

New Method

Old Method

Optimize the Compression

Maintenance

Content Updates

Text conventions

Content Checklist

Graphics conventions

Global Changes

Updating Stylesheets

Navigation menu

Search