GNU bug report logs - #46872
[PATCH] doc: Define canned recipes for creating translated manuals.

Previous Next

To reply to this bug, email your comments to 46872 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Maxime Devos <maximedevos <at> telenet.be>
To: guix-patches <at> gnu.org
Subject: [PATCH] doc: Define canned recipes for creating translated manuals.
Date: Tue, 02 Mar 2021 14:40:20 +0100

[Message part 1 (text/plain, inline)]

Hi Guix,

While looking at how to properly include the documentation
in the makefile in <https://issues.guix.gnu.org/46800>,
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.

[0001-doc-Define-canned-recipes-for-creating-translated-ma.patch (text/x-patch, attachment)]

[signature.asc (application/pgp-signature, inline)]

Message #8 received at 46872 <at> debbugs.gnu.org (full text, mbox):

From: Ludovic Courtès <ludo <at> gnu.org>
To: Maxime Devos <maximedevos <at> telenet.be>
Cc: 46872 <at> debbugs.gnu.org
Subject: Re: bug#46872: [PATCH] doc: Define canned recipes for creating
 translated manuals.
Date: Thu, 20 Jan 2022 15:05:12 +0100

[Message part 1 (text/plain, inline)]

Hi Maxime,

Maxime Devos <maximedevos <at> telenet.be> skribis:

> From 140504026807af6d4e94154b629edb6c7bdf3c27 Mon Sep 17 00:00:00 2001
> From: Maxime Devos <maximedevos <at> 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:

--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.

WDYT?

Ludo’.

[Message part 2 (text/x-patch, inline)]

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 <at> gmail.com>
 # Copyright © 2016, 2018 Mathieu Lirzin <mthl <at> gnu.org>
 # Copyright © 2018, 2021 Julien Lepiller <julien <at> lepiller.eu>
+# Copyright © 2021 Maxime Devos <maximedevos <at> 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 $@`";	\

Message #11 received at 46872 <at> debbugs.gnu.org (full text, mbox):

From: Maxime Devos <maximedevos <at> telenet.be>
To: Ludovic Courtès <ludo <at> gnu.org>
Cc: 46872 <at> debbugs.gnu.org
Subject: Re: bug#46872: [PATCH] doc: Define canned recipes for creating
 translated manuals.
Date: Thu, 20 Jan 2022 16:44:14 +0000

[Message part 1 (text/plain, inline)]

Ludovic Courtès schreef op do 20-01-2022 om 15:05 [+0100]:
> [...] 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?) ...

> WDYT?

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

Greetings,
Maxime

[signature.asc (application/pgp-signature, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.