Documentation Improvement - GnuCash
Documentation Improvement
From GnuCash
Jump to:
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
Contents
Preface and Introduction — What to expect
Setting Up Your System
2.1
Required Software
2.2
Initial Steps
The Documentation Change Process
3.1
Create a Place to Attach and Discuss Your Changes
3.2
Update Your Local Copy
3.3
Identify Location for Changes
3.4
Draft Your Changes
3.4.1
Conventions
3.4.2
Adding or Removing Files
3.4.2.1
Additional Docbook Files
3.4.2.2
Additional images
3.4.3
Telling the Program of a New Help Context
3.5
Validate Your Changes
3.5.1
Formal Checks
3.5.1.1
xmllint output
3.5.2
Appearance Check: make pdf
3.5.3
Completeness Check: After Adding, Moving or Deleting Files
3.5.4
Content Checks
3.5.4.1
Context
3.6
Ensure Only Expected Changes Have Been Made
3.7
Proofreading
3.7.1
In HTML and Other Formats
3.8
Publish your Authorship
3.9
Tell Git about New, Modified, Moved or Renamed and Removed Files
3.10
Commit Your Changes
3.11
Create a Pull Request or a Patch
3.12
After Merge: Verification
References to Supporting Technologies Used
Additional Information
5.1
Screenshots And Other Images
5.1.1
Desktop Themes for Screenshots
5.1.2
Image Formats
5.1.3
Indexing
5.1.4
Display and Print Targets
5.1.5
Adjusting an Image's Dots Per Inch
5.1.5.1
Individual
5.1.5.2
All at once
5.1.5.2.1
New Method
5.1.5.2.2
Old Method
5.1.6
Optimize the Compression
Maintenance
6.1
Content Updates
6.2
Text conventions
6.3
Content Checklist
6.4
Graphics conventions
6.5
Global Changes
6.6
Updating Stylesheets
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
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:
Accounts
. 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
in a DTD and
used
in the source docs like
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
text
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-
File inclusion
Since GnuCash 3.3
the documents use
XInclude
"ch_Intro.docbook"
/>
instead of
system entities
like
and most other
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
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
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
Account Tree - File-Menu
in the
List of Tables
is more readable and looks better than
There are more in
Docbook Conventions
Note
Most markups are ignored inside title elements, but you can still
multiword terms
Linking
Examples
Tip
If you do not plan to replace the URL by another text, use the short form
"https://en.wikipedia.org/wiki/URL"
/>
instead of
"https://en.wikipedia.org/wiki/URL"
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:
and in your text:
More details in
"&url-wp-en;URL"
/>
resulting in
More details in
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
"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
"fig-fil-imp-match"
pgwide=
"1"
"ImportMatcherScreenShot"
"html"
"figures/Import_Transaction_matcher_1.png"
srccredit=
"David Cousens"
width=
"&img-w;"
/>
"fo"
"figures/Import_Transaction_matcher_1.png"
srccredit=
"David Cousens"
/>
The import transaction matcher window after opening a file to import
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
) language:
make C-guide-check
all the
guide and manual
Docbook files
for the
) language:
make C-check
all the guide and manual
Docbook files:
make check
So generally the check parameter to make is of the form
. You can omit
or
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
The
xsltproc
command used there is stricter than
make check
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.
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.15.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
'
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
tutorial and concepts guide.
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/
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
section
contains the metadata, which can also be shown as
About
from the documents start page. Verrify the first (=recent)
section
contains a alphabetical
list,
translations also a
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
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
– 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]
[2]
[3]
[4]
[5]
DocBook: The Definitive Guide
Some Distributions have it as a package named like
docbook-tdg
DocBook XSL: The Complete Guide
of its processing
[6]
[7]
[8]
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 marking
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:
"1"
640x480
Optionally you can here add a longer description than in the title.
If not required, remove the caption element.
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
blind people using a screenreader and
users of
Text-based web browser
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
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:
"figures/Report_Screen.png"
srccredit=
"your name"
/>
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
"html"
"figures/Help_Pref_AccntPeriod.png"
srccredit=
"your name"
width=
"&img-w;"
/>
"fo"
"figures/Help_Pref_AccntPeriod.png"
srccredit=
"your name"
/>
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
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
Imagemagick
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
in
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
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
Common
markup
s - refinement in progress:
block
Components
chapter-like
elements and many sections: should start with
Purpose and overview
or
. In some cases you should also consider to use
offers a good structure e.g. for
tutorial lessons
and the
steps in assistants
is better than
A Step
Another Step with substeps:
Substeps can be nested indefinitely deep.
A Final Step
[3]
for
definitions
at the begin of a chapter/section and the
descriptions of the gui elements of a dialog
like
LABEL
The GUI-ELEMENT-TYPE LABEL …
in the manual
are better than
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