[PATCH] doc: Define canned recipes for creating translated manuals.

  • Open
  • quality assurance status badge
Details
2 participants
  • Ludovic Courtès
  • Maxime Devos
Owner
unassigned
Submitted by
Maxime Devos
Severity
normal
M
M
Maxime Devos wrote on 2 Mar 2021 14:40
(address . guix-patches@gnu.org)
d26260fe4874eceb3956fbb81a69ebdaf1d41f2a.camel@telenet.be
Hi Guix,

While looking at how to properly include the documentation
I noticed the build recipes for creating $MANUAL.%.texi
and $CHAPTER.%.texi are duplicated (modulo $MANUAL and $CHAPTER).

This patch should make defining new chapters and manuals in the
makefile somewhat simpler and less prone to errors (e.g. avoid
copy-paste + oops I forgot to change the .texinfo and .info file name).

Greetings,
Maxime.
From 140504026807af6d4e94154b629edb6c7bdf3c27 Mon Sep 17 00:00:00 2001
From: Maxime Devos <maximedevos@telenet.be>
Date: Tue, 2 Mar 2021 14:13:59 +0100
Subject: [PATCH] doc: Define canned recipes for creating translated manuals.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

It is expected that at some point in the future, the manual's
source will be split in several files per-chapter. Prevent
the build recipes from diverging by defining and using two
‘canned recipes’ in the makefile for translating the manual
and individual chapters.

* doc/local.mk
(guix.%.texi, guix-cookbook.%.texi): move recipe ...
(translate_manual_command): ... to here.
(contributing.%.texi): move recipe ...
(translate_chapter_command): ... to here.
---
doc/local.mk | 30 +++++++++++++++++++++---------
1 file changed, 21 insertions(+), 9 deletions(-)

Toggle diff (57 lines)
diff --git a/doc/local.mk b/doc/local.mk
index 97122c737d..fb1a6a2b37 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 Julien Lepiller <julien@lepiller.eu>
+# Copyright © 2021 Maxime Devos <maximedevos@telenet.be>
#
# This file is part of GNU Guix.
#
@@ -109,22 +110,33 @@ cat "$@.tmp" | egrep '@p?x?ref' -A1 | sed 'N;s|--\n||g;P;D' | sed 's|^| |g' | \
done
endef
-$(srcdir)/%D%/guix.%.texi: po/doc/guix-manual.%.po $(srcdir)/%D%/contributing.%.texi
- -$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "%D%/guix.texi" -p "$<" -l "$@.tmp"
- -sed -i "s|guix\.info|$$(basename "$@" | sed 's|texi$$|info|')|" "$@.tmp"
+# This canned recipe translates is used in the rules below
+# to translate a texinfo manual, using the translations
+# in po/doc. The argument $(1) is the name of the untranslated
+# manual, without a .texi extension or directory prefixes.
+define translate_manual_command
+ -$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "%D%/$(1).texi" -p "$<" -l "$@.tmp"
+ -sed -i "s|$(1)\.info|$$(basename "$@" | sed 's|texi$$|info|')|" "$@.tmp"
-$(AM_V_POXREF)$(xref_command)
-mv "$@.tmp" "$@"
+endef
-$(srcdir)/%D%/guix-cookbook.%.texi: po/doc/guix-cookbook.%.po
- -$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "%D%/guix-cookbook.texi" -p "$<" -l "$@.tmp"
- -sed -i "s|guix-cookbook\.info|$$(basename "$@" | sed 's|texi$$|info|')|" "$@.tmp"
+# Likewise, but for individual chapters (or sections), which do not have
+# an info file name to modify.
+define translate_chapter_command
+ -$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "%D%/$(1).texi" -p "$<" -l "$@.tmp"
-$(AM_V_POXREF)$(xref_command)
-mv "$@.tmp" "$@"
+endef
+
+$(srcdir)/%D%/guix.%.texi: po/doc/guix-manual.%.po $(srcdir)/%D%/contributing.%.texi
+ $(call translate_manual_command,guix)
+
+$(srcdir)/%D%/guix-cookbook.%.texi: po/doc/guix-cookbook.%.po
+ $(call translate_manual_command,guix-cookbook)
$(srcdir)/%D%/contributing.%.texi: po/doc/guix-manual.%.po
- -$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "%D%/contributing.texi" -p "$<" -l "$@.tmp"
- -$(AM_V_POXREF)$(xref_command)
- -mv "$@.tmp" "$@"
+ $(call translate_chapter_command,contributing)
%D%/os-config-%.texi: gnu/system/examples/%.tmpl
$(AM_V_GEN)$(MKDIR_P) "`dirname $@`"; \
--
2.30.1
-----BEGIN PGP SIGNATURE-----

iI0EABYIADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYD5ARBccbWF4aW1lZGV2
b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7hZiAQDv0HEaL94SgNQijRgTvOS+H4mP
xpFiojCw4GZij09+OwEAoqol8SvB4ti3BvfkU7GUeEQYX+aaSw6KoIIQaTRjVwA=
=x6m/
-----END PGP SIGNATURE-----


L
L
Ludovic Courtès wrote on 20 Jan 2022 15:05
(name . Maxime Devos)(address . maximedevos@telenet.be)(address . 46872@debbugs.gnu.org)
874k5y8puv.fsf@gnu.org
Hi Maxime,

Maxime Devos <maximedevos@telenet.be> skribis:

Toggle quote (20 lines)
> From 140504026807af6d4e94154b629edb6c7bdf3c27 Mon Sep 17 00:00:00 2001
> From: Maxime Devos <maximedevos@telenet.be>
> Date: Tue, 2 Mar 2021 14:13:59 +0100
> Subject: [PATCH] doc: Define canned recipes for creating translated manuals.
> MIME-Version: 1.0
> Content-Type: text/plain; charset=UTF-8
> Content-Transfer-Encoding: 8bit
>
> It is expected that at some point in the future, the manual's
> source will be split in several files per-chapter. Prevent
> the build recipes from diverging by defining and using two
> ‘canned recipes’ in the makefile for translating the manual
> and individual chapters.
>
> * doc/local.mk
> (guix.%.texi, guix-cookbook.%.texi): move recipe ...
> (translate_manual_command): ... to here.
> (contributing.%.texi): move recipe ...
> (translate_chapter_command): ... to here.

This had fallen through the cracks.

I updated it so it applies on current master (see below). However, it
doesn’t work as expected:

Toggle snippet (7 lines)
$ rm -f doc/contributing.fr.texi
$ make doc/contributing.fr.texi
make: 'doc/contributing.fr.texi' is up to date.
$ ls -l doc/contributing.fr.texi
ls: ne eblas atingi 'doc/contributing.fr.texi': Dosiero a? dosierujo ne ekzistas

If I inline the expansion of ‘translate_chapter_command’, everything
works as expected.

My GNU Make is rusty and fuzzy, but I wonder if we can expand text that
includes tabs. I vaguely remember that I’d usually define functions
that would expand the whole text: target/prerequisites + commands.

WDYT?

Ludo’.
Toggle diff (57 lines)
diff --git a/doc/local.mk b/doc/local.mk
index 9619971296..627d27a5ef 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 © 2021 Maxime Devos <maximedevos@telenet.be>
#
# This file is part of GNU Guix.
#
@@ -111,22 +112,33 @@ $(top_srcdir)/pre-inst-env $(GUILE) --no-auto-compile \
$@.tmp $<
endef
+# This canned recipe is used in the rules below to translate a Texinfo manual
+# using the translations in po/doc. The argument $(1) is the name of the
+# untranslated manual, without a .texi extension or directory prefixes.
+define translate_manual_command
+ -$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "%D%/$(1).texi" -p "$<" -l "$@.tmp"
+ -sed -i "s|$(1)\.info|$$(basename "$@" | sed 's|texi$$|info|')|" "$@.tmp"
+ -$(AM_V_POXREF)LC_ALL=en_US.UTF-8 $(xref_command)
+ -mv "$@.tmp" "$@"
+endef
+
+# Likewise, but for individual chapters (or sections), which do not have an
+# Info file name to modify.
+define translate_chapter_command
+ -$(AM_V_PO4A)$(PO4A_TRANSLATE) $(PO4A_PARAMS) -m "%D%/$(1).texi" -p "$<" -l "$@.tmp"
+ -$(AM_V_POXREF)LC_ALL=en_US.UTF-8 $(xref_command)
+ -mv "$@.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"
- -sed -i "s|guix\.info|$$(basename "$@" | sed 's|texi$$|info|')|" "$@.tmp"
- -$(AM_V_POXREF)LC_ALL=en_US.UTF-8 $(xref_command)
- -mv "$@.tmp" "$@"
+ $(call translate_manual_command,guix)
$(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"
- -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" "$@"
+ $(call translate_manual_command,guix-cookbook)
$(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_POXREF)LC_ALL=en_US.UTF-8 $(xref_command)
- -mv "$@.tmp" "$@"
+ $(call translate_manual_chapter,contributing)
%D%/os-config-%.texi: gnu/system/examples/%.tmpl
$(AM_V_GEN)$(MKDIR_P) "`dirname $@`"; \
M
M
Maxime Devos wrote on 20 Jan 2022 17:44
(name . Ludovic Courtès)(address . ludo@gnu.org)(address . 46872@debbugs.gnu.org)
d204f88a7ff395dc2c8a97628247fabfbb1d278c.camel@telenet.be
Ludovic Courtès schreef op do 20-01-2022 om 15:05 [+0100]:
Toggle quote (17 lines)
> [...] However, it doesn’t work as expected:
>
> --8<---------------cut here---------------start------------->8---
> $ rm -f doc/contributing.fr.texi
> $ make doc/contributing.fr.texi
> make: 'doc/contributing.fr.texi' is up to date.
> $ ls -l doc/contributing.fr.texi
> ls: ne eblas atingi 'doc/contributing.fr.texi': Dosiero a? dosierujo ne ekzistas
> --8<---------------cut here---------------end--------------->8---
>
> If I inline the expansion of ‘translate_chapter_command’, everything
> works as expected.
>
> My GNU Make is rusty and fuzzy, but I wonder if we can expand text that
> includes tabs. I vaguely remember that I’d usually define functions
> that would expand the whole text: target/prerequisites + commands.

My GNU Make is practically non-existent, e.g. I always forget whether
to use $< or $@ or $? (does $? even exist?) ...

Toggle quote (2 lines)
> WDYT?

... so as long as it works, it is seems ok to me.

Greetings,
Maxime
-----BEGIN PGP SIGNATURE-----

iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYemRXhccbWF4aW1lZGV2
b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7llAAP9cqWE2ieKpnTnDgX/Lv4OrnoTA
rIcKSFf62OWpaWBmlQD/eWz4aVRCyS50GS3D/6njvZCZQ8t4ORfOuLSIqbn8ygo=
=6hPO
-----END PGP SIGNATURE-----


?