… this commit required additional content be created to accommodate links, resulting in the addition of ch_configuring.xml and ch_importing.xml to the documentation source.

…te files. xmllint yields:

ch_basics.xml:1520: parser error : Premature end of data in tag chapter line 18

^
gnucash-guide.xml:497: parser error : Failure to process entity chapter2
&chapter2;
          ^
gnucash-guide.xml:497: parser error : Entity 'chapter2' not defined
&chapter2;
          ^

…h_GettingStarted.xml

…originally slated for Help in bug 796856

Note this commit readds the custom html entity definitions.
This is needed for itstool 2.0.2 to be able to parse the files.
Due to a bug it won't properly parse the DTD.

…into itstool

With some adjustments to get the branch up to speed with the XInclude changes

The xml files I have kept are those needed to merge in sunfish62's PR.
That should give enough context to evaluate how pot based translations
work when moving texts from one book to another.

This is the first step to extract translations into a po file.
When the tag structure across the documents is exactly the same on
the document files across different languages, the extraction
of translatable strings/translated messages can be done in a semi
automated way.
Note some sections exist only in one language. ITS has a mechanism to
handle this, but that can only be used *after* the documents have
been converted to po based translations. So in the interim missing
sections are added with markers that can later be searched for. I am
currently using these markers:
* LANG-DE: will be found in the C documents to indicate this section
  only exists in the German translation, not in the English original
* UNTRANSLATED-DE: used in the German translation to indicate this
  section did not exist in the translation, but does in the English
  original.
* FUZZY-DE: used in the German translation, indicating the context
  of this section has changed and needs review.

Sections marked with LANG-DE or UNTRANSLATED-DE are either candidates
for a special ITS marker (if the section is only relevant for one
language) or for future translation.

Note also that whitespace differences are not important. ITS cleans up
whitespace before extracting the strings. The sequence of the tags in
a file is what matters.

…r conversion to po

At the top level, these global targets have been defined:
- gnucash-docs-de-english.fpot, gnucash-docs-de-native.fpot,
  gnucash-docs-it-english.fpot, gnucash-docs-it-native.fpot,
  gnucash-docs-ja-english.fpot, gnucash-docs-ja-native.fpot,
  gnucash-docs-pt-english.fpot, gnucash-docs-pt-native.fpot,
  gnucash-docs-ru-english.fpot, gnucash-docs-ru-native.fpot:
  These all generate a po template file based on the native language (de, it, ja, pt, ru).
  The files having "native" will have msgids in the native language. The files having
  "english" in their name will have English msgids to go with the native language. (For example
  for the de language, these fpot files will have msgids for both the guide and the help manual,
  while the fpot files for ru will only consider the guide).
  Note the 'f' stands for 'fake' as the template files for other languages are not really meant
  as template files: they have msgid's in the native language instead of English. But
  this fake template file can later be used to compile a proper po message catalog including that
  language's translations.
- gnucash-docs-de-english.struct, gnucash-docs-de-native.struct,...: these rules will extract
  the msgid order as found in the respective fpot with similar name and stores this order as
  gnucash-docs-<lang>-<english,native>.struct. This roughly maps with the xml tag
  hierarchy of the original xml files. This extracted order can be used to verify if the msgid order
  in the English pot file (in srcdir/po) is identical to the msgid order in the fpot file for another
  language. This is crucial for a later automatic generation of po files.
  If the msgid order doesn't match exactly the automatic compilation can't work.
  Note to fix misalignments, xml nodes may have to be added or combined in the original xml files
  (either the English ones or the translated ones depending on the mismatch) or extracted strings
  should be harmonized (match capitalization and punctuation in the same language such that one
  msgid is used the same number of times in both files).
- fpot-de, fpot-pt,...: pseudo targets that will generate the proper gnucash-docs-xy.fpot and .struct for that language
- de.po, it.po,...: will generate a po file in the given language starting from
  gnucash-docs.pot and the fpot file for the given language. Again if the associated
  .struct files differ, this command will print an error and exit.

Aside from these global targets, there are similar targets per book (guide/C, help/de, ...)
- <entity>.fpot: will generate an fpot file for a single entity. For example ch_accts.fpot
  will generate such a file for ch_accts.xml. It will also generate the associated ch_accts.struct
  which again can be used to compare the same source file in different languages.
- fpots: will run the *.fpot rule for each source file in the current directory.
These additional targets are provided as it's likely easier to start the msgid alignment
on a file per file basis. After all files in a language have been lined up with the same files
in the C sources, the global fpot file for a language can be evaluated to make sure the
alignment holds when all files are parsed into one pot file.

Note this likely obscures the rule to extract a <lang>.po file from
two fake pot files. If this happens, the file in src/po/<lang>.po should
temporarily be renamed for the extraction to work.