[bug#63483] [PATCH 0/4] build: Update po4a process.

[bug#63483] [PATCH 0/4] build: Update po4a process.

[gemmaro]

Hello,

This patchset updates the po4a build process and is a follow-up to [1].

In particular, it now uses po4a command instead of po4a-updatepo and
po4a-translate in both Make tasks and `guix build -f doc/build.scm`.  So no
more warnings like "po4a-translate is deprecated.  The unified po4a(1) program
is more convenient and less error prone."

I have checked that the updated process works with `make`, `make dist`, `make
as-derivation` and `guix build -f doc/build.scm`, and there seem to be no
errors.  I don't think this affects other components like Weblate either
(Weblate components use po/doc/guix-manual.xx.po and
po/doc/guix-cookbook.xx.po, and these files are still to be generated).

Sorry for the delay in submitting this.  I hope there are no major mistakes
and that I'll no longer feel guilty every time I see po4a warnings.

[1] [PATCH 0/6] gnu: po4a: Update to 0.68
    https://issues.guix.gnu.org/60448

Best,
gemmaro.

gemmaro (4):
  build: Align Automake status lines of po4a and PO xref.
  build: Update po4a process for Makefiles.
  self: Update po4a process.
  doc: Update documentation about translation languages.

 Makefile.am           |  5 ++--
 configure.ac          |  3 +-
 doc/contributing.texi | 14 ++++-----
 doc/local.mk          | 67 ++++++++++++++++++++++++-------------------
 guix/self.scm         | 39 ++++++++++++-------------
 po/doc/local.mk       | 49 +++++++++++++------------------
 po/doc/po4a.cfg       | 42 +++++++++++++++++++++++++++
 7 files changed, 130 insertions(+), 89 deletions(-)
 create mode 100644 po/doc/po4a.cfg


base-commit: cf89a215cec346bc4d6622cbe353c058452b29b2
-- 
2.39.2

[bug#63483] [PATCH 1/4] build: Align Automake status lines of po4a and PO xref.

[gemmaro]

---
 Makefile.am | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Makefile.am b/Makefile.am
index 13718e4353a..1c7dc667311 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -17,6 +17,7 @@
 # Copyright © 2020, 2021, 2023 Maxim Cournoyer <maxim.cournoyer@gmail.com>
 # Copyright © 2021 Chris Marusich <cmmarusich@gmail.com>
 # Copyright © 2021 Andrew Tropin <andrew@trop.in>
+# Copyright © 2023 gemmaro <gemmaro.dev@gmail.com>
 #
 # This file is part of GNU Guix.
 #
@@ -1186,8 +1187,8 @@ AM_V_HELP2MAN_0 = @echo "  HELP2MAN" $@;
 
 AM_V_PO4A = $(AM_V_PO4A_$(V))
 AM_V_PO4A_ = $(AM_V_PO4A_$(AM_DEFAULT_VERBOSITY))
-AM_V_PO4A_0 = @echo "  PO4A" $@;
+AM_V_PO4A_0 = @echo "  PO4A    " $@;
 
 AM_V_POXREF = $(AM_V_POXREF_$(V))
 AM_V_POXREF_ = $(AM_V_POXREF_$(AM_DEFAULT_VERBOSITY))
-AM_V_POXREF_0 = @echo "  POXREF" $@;
+AM_V_POXREF_0 = @echo "  POXREF  " $@;
-- 
2.39.2

[bug#63483] [PATCH 2/4] build: Update po4a process for Makefiles.

[gemmaro]

---
po4a adds deprecation warnings for po4a-updatepo and po4a-translate as of
version 0.68[1].

Since po4a supports split mode[2] for POT files, intermediate POT files
po/doc/guix.pot and po/doc/contributing.pot are no longer generated.
Note that the po4a option translate-only can't be used here, because po4a
doesn't support it in this split mode.

In the po4a.cfg file, the destdir option is used to override it with the po4a
command line flag, which is needed by the translate-texi-manuals function in
guix/self.scm (see also third patch).

[1] mquinson/po4a: The High Hopes release
    https://github.com/mquinson/po4a/releases/tag/v0.68

[2] po4a(1): Centralized or split PO files?
    https://po4a.org/man/man1/po4a.1.php

 configure.ac    |  3 +--
 doc/local.mk    | 67 ++++++++++++++++++++++++++++---------------------
 po/doc/local.mk | 49 +++++++++++++++---------------------
 po/doc/po4a.cfg | 42 +++++++++++++++++++++++++++++++
 4 files changed, 101 insertions(+), 60 deletions(-)
 create mode 100644 po/doc/po4a.cfg

diff --git a/configure.ac b/configure.ac
index 92dede80141..a9488967c3f 100644
--- a/configure.ac
+++ b/configure.ac
@@ -255,8 +255,7 @@ dnl Manual pages.
 AM_MISSING_PROG([HELP2MAN], [help2man])
 
 dnl Documentation translation.
-AM_MISSING_PROG([PO4A_TRANSLATE], [po4a-translate])
-AM_MISSING_PROG([PO4A_UPDATEPO], [po4a-updatepo])
+AM_MISSING_PROG([PO4A], [po4a])
 
 case "$storedir" in
   /gnu/store)
diff --git a/doc/local.mk b/doc/local.mk
index 89285b9f35a..68e518a4933 100644
--- a/doc/local.mk
+++ b/doc/local.mk
@@ -5,6 +5,7 @@
 # Copyright © 2016 Taylan Ulrich Bayırlı/Kammer <taylanbayirli@gmail.com>
 # Copyright © 2016, 2018 Mathieu Lirzin <mthl@gnu.org>
 # Copyright © 2018, 2021 Julien Lepiller <julien@lepiller.eu>
+# Copyright © 2023 gemmaro <gemmaro.dev@gmail.com>
 #
 # This file is part of GNU Guix.
 #
@@ -21,32 +22,43 @@
 # You should have received a copy of the GNU General Public License
 # along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
 
-# If adding a language, update the following variables, and info_TEXINFOS.
-MANUAL_LANGUAGES = de es fr pt_BR ru zh_CN
-COOKBOOK_LANGUAGES = de fr ko sk
+info_TEXINFOS =					\
+  %D%/guix.texi					\
+  %D%/guix-cookbook.texi			\
+  $(TRANSLATED_INFO_TEXINFOS)
 
-# Arg1: A list of languages codes.
-# Arg2: The file name stem.
-lang_to_texinfo = $(foreach lang,$(1),%D%/$(2).$(lang).texi)
+%C%_guix_TEXINFOS =				\
+  %D%/contributing.texi				\
+  $(TRANSLATED_GUIX_TEXINFOS)			\
+  %D%/fdl-1.3.texi
 
+# If adding a language, update the following and po4a_langs section in
+# po/doc/po4a.cfg.  And if the file name is guix.xx.texi, also update
+# TRANSLATED_GUIX_TEXINFOS.
+#
 # Automake does not understand GNU Make non-standard extensions,
-# unfortunately, so we cannot use the above patsubst-based function here.
-info_TEXINFOS = %D%/guix.texi			\
+# unfortunately, so we cannot use the patsubst-based function here.
+TRANSLATED_INFO_TEXINFOS =			\
   %D%/guix.de.texi				\
   %D%/guix.es.texi				\
   %D%/guix.fr.texi				\
   %D%/guix.pt_BR.texi				\
   %D%/guix.ru.texi				\
   %D%/guix.zh_CN.texi				\
-  %D%/guix-cookbook.texi			\
   %D%/guix-cookbook.de.texi			\
   %D%/guix-cookbook.fr.texi			\
   %D%/guix-cookbook.ko.texi			\
   %D%/guix-cookbook.sk.texi
 
-%C%_guix_TEXINFOS = \
-  %D%/contributing.texi \
-  %D%/fdl-1.3.texi
+TRANSLATED_GUIX_TEXINFOS =			\
+  %D%/contributing.de.texi			\
+  %D%/contributing.es.texi			\
+  %D%/contributing.fr.texi			\
+  %D%/contributing.pt_BR.texi			\
+  %D%/contributing.ru.texi			\
+  %D%/contributing.zh_CN.texi
+
+TRANSLATED_INFO = $(TRANSLATED_INFO_TEXINFOS) $(TRANSLATED_GUIX_TEXINFOS)
 
 DOT_FILES =					\
   %D%/images/bootstrap-graph.dot		\
@@ -76,19 +88,13 @@ OS_CONFIG_EXAMPLES_TEXI =			\
   %D%/os-config-lightweight-desktop.texi	\
   %D%/he-config-bare-bones.scm
 
-TRANSLATED_INFO = 						\
-  $(call lang_to_texinfo,$(MANUAL_LANGUAGES),guix)		\
-  $(call lang_to_texinfo,$(MANUAL_LANGUAGES),contributing)	\
-  $(call lang_to_texinfo,$(COOKBOOK_LANGUAGES),guix-cookbook)
-
 # Bundle this file so that makeinfo finds it in out-of-source-tree builds.
 BUILT_SOURCES        += $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO)
 EXTRA_DIST           += $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO)
 MAINTAINERCLEANFILES  = $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO)
 
-PO4A_PARAMS := -M UTF-8 -L UTF-8 #master and localized encoding
-PO4A_PARAMS += -k 0 # produce an output even if the translation is not complete
-PO4A_PARAMS += -f texinfo # texinfo format
+$(foreach texi,$(TRANSLATED_INFO),$(texi).tmp) &: $(DOC_PO_FILES)
+	-$(AM_V_PO4A)$(PO4A) --no-update $(srcdir)/po/doc/po4a.cfg
 
 # When a change to guix.texi occurs, it is not translated immediately.
 # Because @pxref and @xref commands are references to sections by name, they
@@ -101,22 +107,25 @@ $(top_srcdir)/pre-inst-env $(GUILE) --no-auto-compile	\
   $@.tmp $<
 endef
 
-$(srcdir)/%D%/guix.%.texi: po/doc/guix-manual.%.po $(srcdir)/%D%/contributing.%.texi guix/build/po.go
-	-$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "%D%/guix.texi" -p "$<" -l "$@.tmp"
+$(srcdir)/%D%/guix.%.texi: po/doc/guix-manual.%.po		\
+		$(srcdir)/%D%/guix.%.texi.tmp			\
+		guix/build/po.go
 	-sed -i "s|guix\.info|$$(basename "$@" | sed 's|texi$$|info|')|" "$@.tmp"
 	-$(AM_V_POXREF)LC_ALL=en_US.UTF-8 $(xref_command)
-	-mv "$@.tmp" "$@"
+	-cp "$@.tmp" "$@"
 
-$(srcdir)/%D%/guix-cookbook.%.texi: po/doc/guix-cookbook.%.po guix/build/po.go
-	-$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "%D%/guix-cookbook.texi" -p "$<" -l "$@.tmp"
+$(srcdir)/%D%/guix-cookbook.%.texi: po/doc/guix-cookbook.%.po	\
+		$(srcdir)/%D%/guix-cookbook.%.texi.tmp		\
+		guix/build/po.go
 	-sed -i "s|guix-cookbook\.info|$$(basename "$@" | sed 's|texi$$|info|')|" "$@.tmp"
 	-$(AM_V_POXREF)LC_ALL=en_US.UTF-8 $(xref_command)
-	-mv "$@.tmp" "$@"
+	-cp "$@.tmp" "$@"
 
-$(srcdir)/%D%/contributing.%.texi: po/doc/guix-manual.%.po guix/build/po.go
-	-$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "%D%/contributing.texi" -p "$<" -l "$@.tmp"
+$(srcdir)/%D%/contributing.%.texi: po/doc/guix-manual.%.po	\
+		$(srcdir)/%D%/contributing.%.texi.tmp		\
+		guix/build/po.go
 	-$(AM_V_POXREF)LC_ALL=en_US.UTF-8 $(xref_command)
-	-mv "$@.tmp" "$@"
+	-cp "$@.tmp" "$@"
 
 %D%/os-config-%.texi: gnu/system/examples/%.tmpl
 	$(AM_V_GEN)$(MKDIR_P) "`dirname $@`";	\
diff --git a/po/doc/local.mk b/po/doc/local.mk
index 49258cbb97c..eacd7d8c922 100644
--- a/po/doc/local.mk
+++ b/po/doc/local.mk
@@ -1,6 +1,7 @@
 # GNU Guix --- Functional package management for GNU
 # Copyright © 2018 Julien Lepiller <julien@lepiller.eu>
 # Copyright © 2021 Maxim Cournoyer <maxim.cournoyer@gmail.com>
+# Copyright © 2023 gemmaro <gemmaro.dev@gmail.com>
 #
 # This file is part of GNU Guix.
 #
@@ -17,38 +18,28 @@
 # You should have received a copy of the GNU General Public License
 # along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
 
-DOC_PO_FILES =					\
-  %D%/guix-manual.de.po				\
-  %D%/guix-manual.es.po				\
-  %D%/guix-manual.fr.po				\
-  %D%/guix-manual.pt_BR.po			\
-  %D%/guix-manual.ru.po				\
-  %D%/guix-manual.zh_CN.po
+DOC_POT_FILES = %D%/guix-manual.pot %D%/guix-cookbook.pot
 
-DOC_COOKBOOK_PO_FILES =				\
-  %D%/guix-cookbook.de.po			\
-  %D%/guix-cookbook.fr.po			\
-  %D%/guix-cookbook.ko.po			\
+DOC_PO_FILES =						\
+  %D%/guix-manual.de.po					\
+  %D%/guix-manual.es.po					\
+  %D%/guix-manual.fr.po					\
+  %D%/guix-manual.pt_BR.po				\
+  %D%/guix-manual.ru.po					\
+  %D%/guix-manual.zh_CN.po				\
+  %D%/guix-cookbook.de.po				\
+  %D%/guix-cookbook.fr.po				\
+  %D%/guix-cookbook.ko.po				\
   %D%/guix-cookbook.sk.po
 
-EXTRA_DIST = \
-  %D%/guix-manual.pot \
-  %D%/guix-cookbook.pot \
-  $(DOC_PO_FILES) \
-  $(DOC_COOKBOOK_PO_FILES)
+EXTRA_DIST = $(DOC_POT_FILES) $(DOC_PO_FILES)
 
-POT_OPTIONS = \
-	--package-name "guix manual" --package-version "$(VERSION)" 	\
-	--copyright-holder "the authors of Guix (msgids)" 		\
-	--msgid-bugs-address "bug-guix@gnu.org"
+$(DOC_POT_FILES) &: $(srcdir)/doc/guix.texi		\
+		$(srcdir)/doc/guix-cookbook.texi	\
+		$(srcdir)/doc/contributing.texi
+	$(AM_V_PO4A)$(PO4A) --no-translations		\
+		--package-version "$(VERSION)"		\
+		%D%/po4a.cfg
 
-%D%/%.pot: $(srcdir)/doc/%.texi
-	$(AM_V_PO4A)$(PO4A_UPDATEPO) -M UTF-8 -f texinfo -m "$<" \
-	   -p "$@" $(POT_OPTIONS) && \
-	touch $@
-
-%D%/guix-manual.pot: %D%/guix.pot %D%/contributing.pot
-	msgcat $^ > $@
-
-doc-pot-update: %D%/guix-manual.pot %D%/guix-cookbook.pot
+doc-pot-update: $(DOC_POT_FILES)
 .PHONY: doc-pot-update
diff --git a/po/doc/po4a.cfg b/po/doc/po4a.cfg
new file mode 100644
index 00000000000..27a7599d9aa
--- /dev/null
+++ b/po/doc/po4a.cfg
@@ -0,0 +1,42 @@
+# GNU Guix --- Functional package management for GNU
+# Copyright © 2023 gemmaro <gemmaro.dev@gmail.com>
+#
+# This file is part of GNU Guix.
+#
+# GNU Guix is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or (at
+# your option) any later version.
+#
+# GNU Guix is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
+
+# --keep 0: produce an output even if the translation is not complete
+[options] --package-name "guix manual"                      \
+          --copyright-holder "the authors of Guix (msgids)" \
+          --msgid-bugs-address "bug-guix@gnu.org"           \
+          --keep 0                                          \
+          --master-charset=UTF-8                            \
+          --localized-charset=UTF-8                         \
+          --destdir=doc
+
+[po4a_langs] de es fr pt_BR ru zh_CN ko sk
+
+[po4a_paths] po/doc/$master.pot $lang:po/doc/$master.$lang.po
+
+[type:texinfo] doc/guix-cookbook.texi                       \
+               $lang:guix-cookbook.$lang.texi.tmp           \
+               pot=guix-cookbook
+
+[type:texinfo] doc/guix.texi                                \
+               $lang:guix.$lang.texi.tmp                    \
+               pot=guix-manual
+
+[type:texinfo] doc/contributing.texi                        \
+               $lang:contributing.$lang.texi.tmp            \
+               pot=guix-manual
-- 
2.39.2

[bug#63483] [PATCH 3/4] self: Update po4a process.

[gemmaro]

---
 guix/self.scm | 39 +++++++++++++++++++--------------------
 1 file changed, 19 insertions(+), 20 deletions(-)

diff --git a/guix/self.scm b/guix/self.scm
index 74c953bd50e..c9fedae0ea3 100644
--- a/guix/self.scm
+++ b/guix/self.scm
@@ -1,6 +1,7 @@
 ;;; GNU Guix --- Functional package management for GNU
 ;;; Copyright © 2017-2022 Ludovic Courtès <ludo@gnu.org>
 ;;; Copyright © 2020 Martin Becze <mjbecze@riseup.net>
+;;; Copyright © 2023 gemmaro <gemmaro.dev@gmail.com>
 ;;;
 ;;; This file is part of GNU Guix.
 ;;;
@@ -307,12 +308,14 @@ (define (translate-texi-manuals source)
                        (ice-9 vlist) (ice-9 threads)
                        (srfi srfi-1))
 
-          (define (translate-tmp-texi po source output)
-            "Translate Texinfo file SOURCE using messages from PO, and write
-the result to OUTPUT."
-            (invoke #+(file-append po4a "/bin/po4a-translate")
-              "-M" "UTF-8" "-L" "UTF-8" "-k" "0" "-f" "texinfo"
-              "-m" source "-p" po "-l" output))
+          (define (translate-tmp-texi)
+            "Translate Texinfo files using messages from PO, except for cross
+references."
+            (invoke #+(file-append po4a "/bin/po4a")
+                    "--no-update"
+                    (string-append "--srcdir=" #$source)
+                    "--destdir=."
+                    #+(file-append documentation-po "/po4a.cfg")))
 
           (define (canonicalize-whitespace str)
             ;; Change whitespace (newlines, etc.) in STR to #\space.
@@ -322,17 +325,11 @@ (define (translate-texi-manuals source)
                               chr))
                         str))
 
-          (define* (translate-texi prefix po lang
-                                   #:key (extras '()))
-            "Translate the manual for one language LANG using the PO file.
-PREFIX must be the prefix of the manual, 'guix' or 'guix-cookbook'.  EXTRAS is
-a list of extra files, such as '(\"contributing\")."
-            (for-each (lambda (file)
-                        (translate-tmp-texi po (string-append file ".texi")
-                                            (string-append file "." lang
-                                                           ".texi.tmp")))
-                      (cons prefix extras))
-
+          (define* (translate-texi-xrefs prefix po lang
+                                         #:key (extras '()))
+            "Translate cross references in the manual for one language LANG using the
+PO file.  PREFIX must be the prefix of the manual, 'guix' or 'guix-cookbook'.  EXTRAS
+is a list of extra files, such as '(\"contributing\")."
             (for-each (lambda (file)
                         (let* ((texi (string-append file "." lang ".texi"))
                                (tmp  (string-append texi ".tmp")))
@@ -374,17 +371,19 @@ (define (translate-texi-manuals source)
           (setenv "LC_ALL" "en_US.UTF-8")
           (setlocale LC_ALL "en_US.UTF-8")
 
+          (translate-tmp-texi)
+
           (n-par-for-each parallel-jobs
                           (match-lambda
                             ((language . po)
-                             (translate-texi "guix" po language
-                                             #:extras '("contributing"))))
+                             (translate-texi-xrefs "guix" po language
+                                                   #:extras '("contributing"))))
                           (available-translations "." "guix-manual"))
 
           (n-par-for-each parallel-jobs
                           (match-lambda
                             ((language . po)
-                             (translate-texi "guix-cookbook" po language)))
+                             (translate-texi-xrefs "guix-cookbook" po language)))
                           (available-translations "." "guix-cookbook"))
 
           (for-each (lambda (file)
-- 
2.39.2

[bug#63483] [PATCH 4/4] doc: Update documentation about translation languages.

[gemmaro]

---
 doc/contributing.texi | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 7bf350ee0dc..4c76641d7cc 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -2270,15 +2270,15 @@ Translating Guix
 @item New po files for the @code{documentation-manual} component must be
       registered by adding the file name to @code{DOC_PO_FILES} in
       @file{po/doc/local.mk}, the generated @file{%D%/guix.xx.texi} manual to
-      @code{info_TEXINFOS} in @file{doc/local.mk} and the generated
-      @file{%D%/guix.xx.texi} and @file{%D%/contributing.xx.texi} to
-      @code{TRANSLATED_INFO} also in @file{doc/local.mk}.
+      @code{TRANSLATED_INFO_TEXINFOS} in @file{doc/local.mk}, the generated
+      @file{%D%/contributing.xx.texi} to @code{TRANSLATED_GUIX_TEXINFOS} also
+      in @file{doc/local.mk}, and @code{po4a_langs} section in
+      @file{po/doc/po4a.cfg}.
 @item New po files for the @code{documentation-cookbook} component must be
-      registered by adding the file name to @code{DOC_COOKBOOK_PO_FILES} in
+      registered by adding the file name to @code{DOC_PO_FILES} in
       @file{po/doc/local.mk}, the generated @file{%D%/guix-cookbook.xx.texi}
-      manual to @code{info_TEXINFOS} in @file{doc/local.mk} and the generated
-      @file{%D%/guix-cookbook.xx.texi} to @code{TRANSLATED_INFO} also
-      in @file{doc/local.mk}.
+      manual to @code{TRANSLATED_INFO_TEXINFOS} in @file{doc/local.mk}, and
+      @code{po4a_langs} section in @file{po/doc/po4a.cfg}.
 @item New po files for the @code{website} component must be added to the
       @code{guix-artwork} repository, in @file{website/po/}.
       @file{website/po/LINGUAS} and @file{website/po/ietf-tags.scm} must
-- 
2.39.2

[bug#63483] [PATCH 0/4] build: Update po4a process.

[Maxim Cournoyer]

tags 63483 + moreinfo
quit

Hi gemmaro,

Thanks for doing this!

I have surveyed the series, and I'll need to dive into the details to
see if everything adds up, but it looks good!

We include a GNU ChangeLog in our git commit messages, as mentioned in
info '(guix) Submitting Patches'.  There's a cross-reference to 'info
(standards)Change Logs', which is made available upon installing the
'standards' Guix package (and 'info-reader').  This changelog should be
a high level description of the changes, which is handy when reviewing.

I hope this helps!  I hope to see a v2 soon :-)

-- 
Thanks,
Maxim

[bug#63483] [PATCH v2 0/4] build: Update po4a process.

[gemmaro]

Hello,

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> tags 63483 + moreinfo
> quit
>
> Hi gemmaro,
>
> Thanks for doing this!
>
> I have surveyed the series, and I'll need to dive into the details to
> see if everything adds up, but it looks good!
>
> We include a GNU ChangeLog in our git commit messages, as mentioned in
> info '(guix) Submitting Patches'.  There's a cross-reference to 'info
> (standards)Change Logs', which is made available upon installing the
> 'standards' Guix package (and 'info-reader').  This changelog should be
> a high level description of the changes, which is handy when reviewing.
>
> I hope this helps!  I hope to see a v2 soon :-)
>
> -- 
> Thanks,
> Maxim

Thank you for your response.  I read the chapter on Change Logs and rewrote it
to tried to make it more descriptive and more purposeful.

To recap, the goal of this change is to eliminate the po4a warning
("po4a-{updatepo,translate} is deprecated.  The unified po4a(1) program is
more convenient and less error prone.").  I checked it works by running "make"
and "make as-derivation".  The location of the PO files is not changed, so
Weblate can continue to be used as is.

Several things have changed since revision 1.  Firstly, I have broken down the
process and tried to write better commit messages and comments to make the
changes easier to grasp.  Secondly, I used po4a in batches in revision 1, but
this may not be suitable for the use case for Guix, so I left as is.

If it is the case to run po4a in batches, the change might be similar to the
revision 1.  However, there are the following concerns.  Because of these and
the aim here to clear po4a warnings, I don't use po4a in bulk.

 1) It may take more time to process the translations.  Combining them in one
    configuration file increases the number of target files to be handled.

 2) The Makefiles (doc/local.mk and po/doc/local.mk) become more complex,
    since a single run of po4a will update multiple files.

 3) PO files will need to be addressed.  Currently two are covered - manuals
    and cookbooks - but the merging of gettext entries will cause conflicts if
    there are different translations (msgstr) for the same source text
    (msgid).  I also think that the configuration of Weblate will then need to
    be changed[3] simultaneously.

 4) There would be some new almost empty PO files generated.

I noticed that the similar change[1] has been proposed.  It is possible that
action will be taken on the po4a side, but in the meantime we may encounter
problems that were not addressed in po4a-{updatepo,translate} [2].

[1] [PATCH] gnu: Replace deprecated po4a-* calls with po4a,
https://issues.guix.gnu.org/70042

[2] Why are the individual scripts deprecated?,
https://po4a.org/man/man7/po4a.7.php.en

[3] Translation projects / Allow translation propagation,
https://docs.weblate.org/en/latest/admin/projects.html#allow-translation-propagation

Regards,
gemmaro.

gemmaro (4):
  build: Align the Automake status lines of the po4a and the PO xref.
  build: Update the POT creation task with the po4a command.
  build: Use the po4a command for the translation generation.
  self: Use po4a instead of po4a-translate.

 Makefile.am     |  5 +++--
 configure.ac    |  3 +--
 doc/local.mk    | 30 +++++++++++++++++++++++-------
 guix/self.scm   | 12 +++++++++---
 po/doc/local.mk | 15 ++++++++-------
 po/doc/po4a.cfg | 32 ++++++++++++++++++++++++++++++++
 6 files changed, 76 insertions(+), 21 deletions(-)
 create mode 100644 po/doc/po4a.cfg


base-commit: 51de844a0ff6ea224367a384092896bce6848b9f
-- 
2.41.0

[bug#63483] [PATCH v2 1/4] build: Align the Automake status lines of the po4a and the PO xref.

[gemmaro]

* Makefile.am (AM_V_PO4A_0, AM_V_POXREF_0): Align the Automake status lines of
the po4a and the PO xref, since the common width is 10 characters.

Change-Id: Ic8c32f73294ba6e4ca71ab4aa889a558e4d7fcee
---
 Makefile.am | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Makefile.am b/Makefile.am
index 1c5688ac13..faf16defc9 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -19,6 +19,7 @@
 # Copyright © 2021 Andrew Tropin <andrew@trop.in>
 # Copyright © 2023 Clément Lassieur <clement@lassieur.org>
 # Copyright © 2023, 2024 Wilko Meyer <w@wmeyer.eu>
+# Copyright © 2024 gemmaro <gemmaro.dev@gmail.com>
 #
 # This file is part of GNU Guix.
 #
@@ -1263,8 +1264,8 @@ AM_V_HELP2MAN_0 = @echo "  HELP2MAN" $@;
 
 AM_V_PO4A = $(AM_V_PO4A_$(V))
 AM_V_PO4A_ = $(AM_V_PO4A_$(AM_DEFAULT_VERBOSITY))
-AM_V_PO4A_0 = @echo "  PO4A" $@;
+AM_V_PO4A_0 = @echo "  PO4A    " $@;
 
 AM_V_POXREF = $(AM_V_POXREF_$(V))
 AM_V_POXREF_ = $(AM_V_POXREF_$(AM_DEFAULT_VERBOSITY))
-AM_V_POXREF_0 = @echo "  POXREF" $@;
+AM_V_POXREF_0 = @echo "  POXREF  " $@;
-- 
2.41.0

[bug#63483] [PATCH v2 2/4] build: Update the POT creation task with the po4a command.

[gemmaro]

* configure.ac (Documentation translation): Add the po4a program and remove
the po4a-updatepo program.  The PO4A defined here can be used in
Makefiles (e.g. po/doc/local.mk below).  The po4a command integrates the
functionality of po4a-updatepo and is currently recommended for use [1].  The
po4a-updatepo command has been replaced by the po4a command and are not used
from anywhere.
* po/doc/local.mk (%D%/%.pot): Use a po4a command instead of the po4a-updatepo
for the POT generation.  This eliminates the warning of po4a-updatepo;
"po4a-updatepo is deprecated.  The unified po4a(1) program is more convenient
and less error prone."  Here, the file paths are passed using variables.  This
is because the po4a command needs to be executed for each language and each
file.  Dummy values are passed for those that are not needed to update the POT
file.
* po/doc/po4a.cfg: Add a po4a config file for the POT generation.  The po4a
command requires a configulation file.

[1] https://po4a.org/man/man7/po4a.7.php.en#lbAS

Change-Id: Ica39a0d1f77b6a64d37c592ac2e693319443d3c5
---
 configure.ac    |  2 +-
 po/doc/local.mk | 10 ++++++++--
 po/doc/po4a.cfg | 32 ++++++++++++++++++++++++++++++++
 3 files changed, 41 insertions(+), 3 deletions(-)
 create mode 100644 po/doc/po4a.cfg

diff --git a/configure.ac b/configure.ac
index ecbd596a34..68542f0348 100644
--- a/configure.ac
+++ b/configure.ac
@@ -262,8 +262,8 @@ dnl Manual pages.
 AM_MISSING_PROG([HELP2MAN], [help2man])
 
 dnl Documentation translation.
+AM_MISSING_PROG([PO4A], [po4a])
 AM_MISSING_PROG([PO4A_TRANSLATE], [po4a-translate])
-AM_MISSING_PROG([PO4A_UPDATEPO], [po4a-updatepo])
 
 case "$storedir" in
   /gnu/store)
diff --git a/po/doc/local.mk b/po/doc/local.mk
index dd6ba30133..8a78fb23f8 100644
--- a/po/doc/local.mk
+++ b/po/doc/local.mk
@@ -1,6 +1,7 @@
 # GNU Guix --- Functional package management for GNU
 # Copyright © 2018 Julien Lepiller <julien@lepiller.eu>
 # Copyright © 2021 Maxim Cournoyer <maxim.cournoyer@gmail.com>
+# Copyright © 2024 gemmaro <gemmaro.dev@gmail.com>
 #
 # This file is part of GNU Guix.
 #
@@ -44,8 +45,13 @@ POT_OPTIONS = \
 	--msgid-bugs-address "bug-guix@gnu.org"
 
 %D%/%.pot: $(srcdir)/doc/%.texi
-	$(AM_V_PO4A)$(PO4A_UPDATEPO) -M UTF-8 -f texinfo -m "$<" \
-	   -p "$@" $(POT_OPTIONS) && \
+	$(AM_V_PO4A)$(PO4A) --no-translations -M UTF-8	\
+		--package-version "$(VERSION)"		\
+		--variable master="$<"			\
+		--variable pot="$@"			\
+		--variable po=/dev/null			\
+		--variable localized=/dev/null		\
+		$(POT_OPTIONS) %D%/po4a.cfg
 	touch $@
 
 %D%/guix-manual.pot: %D%/guix.pot %D%/contributing.pot
diff --git a/po/doc/po4a.cfg b/po/doc/po4a.cfg
new file mode 100644
index 0000000000..7d2ef71773
--- /dev/null
+++ b/po/doc/po4a.cfg
@@ -0,0 +1,32 @@
+# GNU Guix --- Functional package management for GNU
+# Copyright © 2024 gemmaro <gemmaro.dev@gmail.com>
+#
+# This file is part of GNU Guix.
+#
+# GNU Guix is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or (at
+# your option) any later version.
+#
+# GNU Guix is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with GNU Guix.  If not, see <http://www.gnu.org/licenses/>.
+
+# "--keep 0": produce an output even if the translation is not complete
+[options]                                                   \
+          --package-name "guix manual"                      \
+          --copyright-holder "the authors of Guix (msgids)" \
+          --msgid-bugs-address "bug-guix@gnu.org"           \
+          --master-charset UTF-8                            \
+          --localized-charset UTF-8                         \
+          --keep 0
+
+[po4a_langs] de es fr pt_BR ru zh_CN ko sk
+
+[po4a_paths] $(pot) $lang:$(po)
+
+[type:texinfo] $(master) $lang:$(localized)
-- 
2.41.0

[bug#63483] [PATCH v2 3/4] build: Use the po4a command for the translation generation.

[gemmaro]

* configure.ac (Documentation translation): Remove the po4a-translate command.
This command has been replaced by the po4a command and are not used from
anywhere.
* doc/local.mk ($(srcdir)/%D%/guix.%.texi, $(srcdir)/%D%/guix-cookbook.%.texi)
($(srcdir)/%D%/contributing.%.texi): Use the po4a command instead of the
po4a-translate for the translation generation.  This eliminates the warning of
po4a-translate; "po4a-translate is deprecated.  The unified po4a(1) program is
more convenient and less error prone."
(PO4A_PARAMS): Remove the Texinfo format option.  This option is specified in
the configuration file (po/doc/po4a.cfg).
(dummy_pot): Add a variable for the temporary POT file location.

Change-Id: I542b934c3c03b8701e9f86823191224f8b0ccf81
---
 configure.ac    |  1 -
 doc/local.mk    | 30 +++++++++++++++++++++++-------
 po/doc/local.mk |  5 -----
 3 files changed, 23 insertions(+), 13 deletions(-)

diff --git a/configure.ac b/configure.ac
index 68542f0348..ad148f33b6 100644
--- a/configure.ac
+++ b/configure.ac
@@ -263,7 +263,6 @@ AM_MISSING_PROG([HELP2MAN], [help2man])
 
 dnl Documentation translation.
 AM_MISSING_PROG([PO4A], [po4a])
-AM_MISSING_PROG([PO4A_TRANSLATE], [po4a-translate])
 
 case "$storedir" in
   /gnu/store)
diff --git a/doc/local.mk b/doc/local.mk
index 8df003b891..a6234b2e3e 100644
--- a/doc/local.mk
+++ b/doc/local.mk
@@ -5,6 +5,7 @@
 # Copyright © 2016 Taylan Ulrich Bayırlı/Kammer <taylanbayirli@gmail.com>
 # Copyright © 2016, 2018 Mathieu Lirzin <mthl@gnu.org>
 # Copyright © 2018, 2021 Julien Lepiller <julien@lepiller.eu>
+# Copyright © 2024 gemmaro <gemmaro.dev@gmail.com>
 #
 # This file is part of GNU Guix.
 #
@@ -87,10 +88,6 @@ BUILT_SOURCES        += $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO)
 EXTRA_DIST           += $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO)
 MAINTAINERCLEANFILES  = $(OS_CONFIG_EXAMPLES_TEXI) $(TRANSLATED_INFO)
 
-PO4A_PARAMS := -M UTF-8 -L UTF-8 #master and localized encoding
-PO4A_PARAMS += -k 0 # produce an output even if the translation is not complete
-PO4A_PARAMS += -f texinfo # texinfo format
-
 # When a change to guix.texi occurs, it is not translated immediately.
 # Because @pxref and @xref commands are references to sections by name, they
 # should be translated. If a modification adds a reference to a section, this
@@ -102,20 +99,39 @@ $(top_srcdir)/pre-inst-env $(GUILE) --no-auto-compile	\
   $@.tmp $<
 endef
 
+# If /dev/null is used for this POT file path, a warning will be issued
+# because the path extension is not 'pot'.
+dummy_pot = $(shell mktemp --suffix=.pot)
+
 $(srcdir)/%D%/guix.%.texi: po/doc/guix-manual.%.po $(srcdir)/%D%/contributing.%.texi guix/build/po.go
-	-$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "%D%/guix.texi" -p "$<" -l "$@.tmp"
+	-$(AM_V_PO4A)$(PO4A) --no-update		\
+		--variable localized="$@.tmp"		\
+		--variable master="%D%/guix.texi"	\
+		--variable po="$<"			\
+		--variable pot=$(dummy_pot)		\
+		po/doc/po4a.cfg
 	-sed -i "s|guix\.info|$$(basename "$@" | sed 's|texi$$|info|')|" "$@.tmp"
 	-$(AM_V_POXREF)LC_ALL=en_US.UTF-8 $(xref_command)
 	-mv "$@.tmp" "$@"
 
 $(srcdir)/%D%/guix-cookbook.%.texi: po/doc/guix-cookbook.%.po guix/build/po.go
-	-$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "%D%/guix-cookbook.texi" -p "$<" -l "$@.tmp"
+	-$(AM_V_PO4A)$(PO4A) --no-update			\
+		--variable localized="$@.tmp"			\
+		--variable master="%D%/guix-cookbook.texi"	\
+		--variable po="$<"				\
+		--variable pot=$(dummy_pot)			\
+		po/doc/po4a.cfg
 	-sed -i "s|guix-cookbook\.info|$$(basename "$@" | sed 's|texi$$|info|')|" "$@.tmp"
 	-$(AM_V_POXREF)LC_ALL=en_US.UTF-8 $(xref_command)
 	-mv "$@.tmp" "$@"
 
 $(srcdir)/%D%/contributing.%.texi: po/doc/guix-manual.%.po guix/build/po.go
-	-$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "%D%/contributing.texi" -p "$<" -l "$@.tmp"
+	-$(AM_V_PO4A)$(PO4A) --no-update			\
+		--variable localized="$@.tmp"			\
+		--variable master="%D%/contributing.texi"	\
+		--variable po="$<"				\
+		--variable pot=$(dummy_pot)			\
+		po/doc/po4a.cfg
 	-$(AM_V_POXREF)LC_ALL=en_US.UTF-8 $(xref_command)
 	-mv "$@.tmp" "$@"
 
diff --git a/po/doc/local.mk b/po/doc/local.mk
index 8a78fb23f8..a1f1875623 100644
--- a/po/doc/local.mk
+++ b/po/doc/local.mk
@@ -39,11 +39,6 @@ EXTRA_DIST = \
   $(DOC_PO_FILES) \
   $(DOC_COOKBOOK_PO_FILES)
 
-POT_OPTIONS = \
-	--package-name "guix manual" --package-version "$(VERSION)" 	\
-	--copyright-holder "the authors of Guix (msgids)" 		\
-	--msgid-bugs-address "bug-guix@gnu.org"
-
 %D%/%.pot: $(srcdir)/doc/%.texi
 	$(AM_V_PO4A)$(PO4A) --no-translations -M UTF-8	\
 		--package-version "$(VERSION)"		\
-- 
2.41.0

[bug#63483] [PATCH v2 4/4] self: Use po4a instead of po4a-translate.

[gemmaro]

* guix/self.scm (translate-tmp-texi): Use po4a instead of po4a-translate.
This eliminates the po4a-translate warning; "po4a-translate is deprecated.
The unified po4a(1) program is more convenient and less error prone."

Change-Id: Id85c7478b1b237f31010994fcd2d38765993c1ad
---
 guix/self.scm | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/guix/self.scm b/guix/self.scm
index 19c6d08e01..153cdec7ad 100644
--- a/guix/self.scm
+++ b/guix/self.scm
@@ -317,9 +317,15 @@ (define (translate-texi-manuals source)
           (define (translate-tmp-texi po source output)
             "Translate Texinfo file SOURCE using messages from PO, and write
 the result to OUTPUT."
-            (invoke #+(file-append po4a "/bin/po4a-translate")
-              "-M" "UTF-8" "-L" "UTF-8" "-k" "0" "-f" "texinfo"
-              "-m" source "-p" po "-l" output))
+            (invoke #+(file-append po4a "/bin/po4a")
+              "--no-update"
+              "--variable" (string-append "localized=" output)
+              "--variable" (string-append "master=" source)
+              "--variable" (string-append "po=" po)
+              "--variable" (string-append "pot=" (string-append (tmpnam) ".pot"))
+              (string-append "--srcdir=" #$source)
+              "--destdir=."
+              #+(file-append documentation-po "/po4a.cfg")))
 
           (define (canonicalize-whitespace str)
             ;; Change whitespace (newlines, etc.) in STR to #\space.
-- 
2.41.0

[bug#63483] [PATCH v2 0/4] build: Update po4a process.

[pelzflorian (Florian Pelz)]

Thank you, gemmaro, for driving this necessary change.  It is a good
idea to switch to the actual PO4A script that still gets updates by
PO4A maintainers.

You will have to coordinate with Julien Lepiller (added to Cc) who
controls the Guix-translations repository. [1]

Guix-translations is the repository that Weblate has access to (because
we do not want Weblate to push directly to Guix.git directly).  It will
need your po4a.cfg and the same kind of Makefile updates.

In your original v1 patch, you had updated contributing.texi.
contributing.texi is already out of date, but I believe we better update
it at a later time when we can refer people adding new languages to
prior commits where new languages have been added.

Regards,
Florian

[1] https://framagit.org/tyreunom/guix-translations

[bug#63483] [PATCH v2 0/4] build: Update po4a process.

[gemmaro]

Hello Florian Pelz and Julien Lepiller,

"pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> writes:

> Thank you, gemmaro, for driving this necessary change.  It is a good
> idea to switch to the actual PO4A script that still gets updates by
> PO4A maintainers.
>
> You will have to coordinate with Julien Lepiller (added to Cc) who
> controls the Guix-translations repository. [1]

Thank you very much for telling me about the repository.  I also got an
idea of the translation flow in Guix using Weblate; Weblate refers to
and updates the PO files in the Guix-translations repository, and that
the PO files in the Guix.git cloned in it are updated by the Makefile.

> Guix-translations is the repository that Weblate has access to (because
> we do not want Weblate to push directly to Guix.git directly).  It will
> need your po4a.cfg and the same kind of Makefile updates.

The changes in revision 2 don't alter the location of PO files and the
scripts under the scripts directory.  I couldn't find additional changes
to the po4a.cfg and the Makefiles.

What do you think, Julien Lepiller?  If there are any changes that
should be made, I would appreciate it if you could correct me.

The po4a.cfg added by this change allows quite flexible specification of
file paths by passing variables (with po4a's "--variable key=value"
option.)  It would be therefore possible to make the Guix-translations
repository also use the integrated po4a program anytime.  The Texinfo
parser used by po4a (and po4a-* scripts) is the same before and after
the change, so there should be no side-effect on the PO files.

> In your original v1 patch, you had updated contributing.texi.
> contributing.texi is already out of date, but I believe we better update
> it at a later time when we can refer people adding new languages to
> prior commits where new languages have been added.
>
> Regards,
> Florian
>
> [1] https://framagit.org/tyreunom/guix-translations

When I was writing this, I noticed that I have transferred some
configuration to po4a.cfg and now there is one more place to specify the
languages (in the po4a_langs section.)  The documentation will need to
be updated in the future in this respect.

Regards,
gemmaro.