As found by the GitLab Continuous Integration job on CentOS 7 with
itstool 2.0.2, building the GParted Manual breaks on the Russian
translation like this:
$ ./autogen.sh
$ make clean
$ cd help
$ make
...
if ! test -d "ru/"; then mkdir "ru/"; fi
if test -d "C"; then d="../"; else d="/home/mike/programming/c/gparted/help/"; fi; \
mo="ru/ru.mo"; \
if test -f "${mo}"; then mo="../${mo}"; else mo="/home/mike/programming/c/gparted/help/${mo}"; fi; \
(cd "ru/" && itstool -m "${mo}" ${d}/C/index.docbook) && \
touch "ru/ru.stamp"
Error: Could not merge translations:
'NoneType' object has no attribute 'node'
make: *** [ru/ru.stamp] Error 1
On Fedora 35 with itstool 2.0.6 building the GParted Manual merely
reports a warning, leaving one paragraph untranslated, but the build
completes successfully:
$ ./autogen.sh
$ make clean
$ cd help
$ make
...
if ! test -d "ru/"; then mkdir "ru/"; fi
if test -d "C"; then d="../"; else d="/home/fedora/programming/c/gparted/help/"; fi; \
mo="ru/ru.mo"; \
if test -f "${mo}"; then mo="../${mo}"; else mo="/home/fedora/programming/c/gparted/help/${mo}"; fi; \
(cd "ru/" && itstool -m "${mo}" ${d}/C/index.docbook) && \
touch "ru/ru.stamp"
Warning: Could not merge translation for msgid:
Set the <application>grub</application> root device by specifying the device returned by the <command>find</command> command. This should be the partition containing the boot directory. <_:screen-1/>
...
$ echo $?
0
Fix translation of DocBook markup tag in the Russian translation of the
GParted Manual by commit:
17f4c3176d
Update Russian translation
Closes!98 - Fix translation of DocBook markup tag of the GParted Manual
Now with GNOME 3 style help installed, running 'yelp help:gparted'
results in this error being displayed in yelp:
Page Not Found
The requested page was not found in the document 'help:gparted'.
Where as running 'yelp help:gparted/gparted' correctly displays the
GParted Manual.
Fix by renaming the article tag to the default 'index' that yelp is
expecting when using the new GNOME 3 'help:' prefix.
Closes!24 - Port to GNOME 3 yelp-tools documentation infrastructure
Second part is to use yelp-tools to build and install the documentation.
Have to rename the help Manual from help/C/gparted.xml to
help/C/index.docbook in accordance with this note from the GNOME Goal:
Port to New Documentation Infrastructure [1]:
IMPORTANT: If this is for a DocBook document, the top-level DocBook
file MUST be renamed to index.docbook. Do a "git mv" and include
index.docbook in HELP_FILES.
Commits from gucharmap [4] and totem [5], projects which have DocBook
documentation, making this same change are also useful references.
[1] GNOME Goal: Port To New Documentation Infrastructure
https://wiki.gnome.org/Initiatives/GnomeGoals/NewDocumentationInfrastructure
[2] Yelp > Yelp Tools > yelp.m4
http://yelp.io/tools/yelp.m4.html
[3] GNOME application developement overview / User help / Set up your
build system
https://developer.gnome.org/platform-overview/stable/dev-help-build.html.en
[4] gucharmap commit "Port to new documentation infrastructure"
3e1526c056
[5] totem commit "Use new documentation infrastructure"
59a6bd6064Closes!24 - Port to GNOME 3 yelp-tools documentation infrastructure
Details of old GNOME 2 gnome-doc-utils:
Migrating your documentation to gnome-doc-utils
https://wiki.gnome.org/Projects/GnomeDocUtils/MigrationHowTo
First part is to stop using gnome-doc-utils to build and install the
documentation. Also since updating the OMF catalog was only needed for
GNOME 2 yelp, use of scrollkeeper is completely removed too.
Closes!24 - Port to GNOME 3 yelp-tools documentation infrastructure
I generated this by running:
find ./ -type f -exec sed -i 's/ghelp:fdl/help:fdl/g' {} \;
By updating the translations at the same time, it should be easier on
the translators as there's no reason to invalidate these strings.
https://bugzilla.gnome.org/show_bug.cgi?id=704634#c8
[Mike Fleetwood: Explain the underlying cause and distro versions.]
This gnome-desktop commit, first included in version 3.5.5, switched the
package from using gnome-doc-utils to yelp-tools so changed the
installed location of the GNU FDL license file from
/usr/share/gnome/help/fdl/C/fdl.xml to
/usr/share/help/C/fdl/index.docbook, thus changing the yelp URI from
'ghelp:fdl' to 'help:fdl':
8b7e059e2c
Port to new documentation infrastructure
The oldest supported distributions with Gtk/GNOME 3 all have at least
3.10, therefore use this fix unconditionally.
Distribution EOL Gtk/GNOME 3
RHEL / CentOS 7 2024-Jun 3.22
Ubuntu 14.04 LTS 2019-Apr 3.10
Ubuntu 16.04 LTS 2021-Apr 3.18
Debian 8 2023-Apr 3.14
SLES 12 2027-Oct 3.10
Closes!24 - Port to GNOME 3 yelp-tools documentation infrastructure
The file has been redundant since it was first added [1]. It was never
listed in configure.ac (or configure.in) in AC_CONFIG_FILES. Therefore
autoconf has never produced help/C/Makefile.in and ./configure has never
produced help/C/Makefile. Therefore it isn't used during the build and
install of GParted. Remove it.
[1] 46ca7c74dc
Added code hooks to prepare for GParted Manual
Closes!24 - Port to GNOME 3 yelp-tools documentation infrastructure
The Open and Close pages use third person present tense for the "Choose:" paragraph. On the Close instruction, it had "closed" next to a "refreshes". So this commit simply applies present tense to "closed".
Mike Fleetwood