bug#70140: Missing ./doc/guix-cookbook.pt_BR.texi

bug#70140: Missing ./doc/guix-cookbook.pt_BR.texi

[Rostislav Svoboda]

$ guix shell --development guix direnv gnupg --pure --
bost@ecke ~/dev/guix [env]$ make doc/guix.texi
 cd . && /bin/sh /home/bost/dev/guix/build-aux/missing automake-1.16
--gnu Makefile
Makefile.am:922: warning: AM_GNU_GETTEXT used but 'po' not in SUBDIRS
automake-1.16: error: cannot open < ./doc/guix-cookbook.pt_BR.texi: No
such file or directory
make: *** [Makefile:4349: Makefile.in] Error 1

And I think it is caused by:

$ git show --format=medium fa98837b1d9586b9ca7bf77dae22c3bde0fc59b5 doc/local.mk
commit fa98837b1d9586b9ca7bf77dae22c3bde0fc59b5
Author: Florian Pelz <pelzflorian@pelzflorian.de>
Date:   Mon Apr 1 00:54:32 2024

    nls: Update translations.

    * po/guix/ar.po: New file.
    * po/guix/LINGUAS: Add 'ar'.
    * po/doc/guix-cookbook.pt_BR.po: New file.
    * po/doc/local.mk: Add 'pt_BR' cookbook.
    * doc/local.mk: Add 'pt_BR' cookbook.
    * doc/htmlxref.cnf: Update URLs for cookbook.
    * doc/build.scm (%cookbook-languages): Add 'ko', 'pt_BR'.
    * doc/guix-cookbook.texi (Top): Mention 'ko', 'pt_BR' cookbook.

    Change-Id: Id1846ca100263b3fc1fa2ed52654c670270ee809

diff --git a/doc/local.mk b/doc/local.mk
index 97f0c3a92a..0ff317a19e 100644
--- a/doc/local.mk
+++ b/doc/local.mk
@@ -23,7 +23,7 @@

 # 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
+COOKBOOK_LANGUAGES = de fr ko pt_BR sk

 # Arg1: A list of languages codes.
 # Arg2: The file name stem.
@@ -42,6 +42,7 @@ info_TEXINFOS = %D%/guix.texi                 \
   %D%/guix-cookbook.de.texi                    \
   %D%/guix-cookbook.fr.texi                    \
   %D%/guix-cookbook.ko.texi                    \
+  %D%/guix-cookbook.pt_BR.texi                 \
   %D%/guix-cookbook.sk.texi

 %C%_guix_TEXINFOS = \

bug#70140: Missing ./doc/guix-cookbook.pt_BR.texi

[Efraim Flashner]

[-- Attachment #1: Type: text/plain, Size: 2310 bytes --]

Rerun ./bootstrap and configure, then make

On Tue, Apr 02, 2024 at 03:59:36PM +0200, Rostislav Svoboda wrote:
> $ guix shell --development guix direnv gnupg --pure --
> bost@ecke ~/dev/guix [env]$ make doc/guix.texi
>  cd . && /bin/sh /home/bost/dev/guix/build-aux/missing automake-1.16
> --gnu Makefile
> Makefile.am:922: warning: AM_GNU_GETTEXT used but 'po' not in SUBDIRS
> automake-1.16: error: cannot open < ./doc/guix-cookbook.pt_BR.texi: No
> such file or directory
> make: *** [Makefile:4349: Makefile.in] Error 1
> 
> And I think it is caused by:
> 
> $ git show --format=medium fa98837b1d9586b9ca7bf77dae22c3bde0fc59b5 doc/local.mk
> commit fa98837b1d9586b9ca7bf77dae22c3bde0fc59b5
> Author: Florian Pelz <pelzflorian@pelzflorian.de>
> Date:   Mon Apr 1 00:54:32 2024
> 
>     nls: Update translations.
> 
>     * po/guix/ar.po: New file.
>     * po/guix/LINGUAS: Add 'ar'.
>     * po/doc/guix-cookbook.pt_BR.po: New file.
>     * po/doc/local.mk: Add 'pt_BR' cookbook.
>     * doc/local.mk: Add 'pt_BR' cookbook.
>     * doc/htmlxref.cnf: Update URLs for cookbook.
>     * doc/build.scm (%cookbook-languages): Add 'ko', 'pt_BR'.
>     * doc/guix-cookbook.texi (Top): Mention 'ko', 'pt_BR' cookbook.
> 
>     Change-Id: Id1846ca100263b3fc1fa2ed52654c670270ee809
> 
> diff --git a/doc/local.mk b/doc/local.mk
> index 97f0c3a92a..0ff317a19e 100644
> --- a/doc/local.mk
> +++ b/doc/local.mk
> @@ -23,7 +23,7 @@
> 
>  # 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
> +COOKBOOK_LANGUAGES = de fr ko pt_BR sk
> 
>  # Arg1: A list of languages codes.
>  # Arg2: The file name stem.
> @@ -42,6 +42,7 @@ info_TEXINFOS = %D%/guix.texi                 \
>    %D%/guix-cookbook.de.texi                    \
>    %D%/guix-cookbook.fr.texi                    \
>    %D%/guix-cookbook.ko.texi                    \
> +  %D%/guix-cookbook.pt_BR.texi                 \
>    %D%/guix-cookbook.sk.texi
> 
>  %C%_guix_TEXINFOS = \
> 
> 
> 

-- 
Efraim Flashner   <efraim@flashner.co.il>   רנשלפ םירפא
GPG key = A28B F40C 3E55 1372 662D  14F7 41AA E7DC CA3D 8351
Confidentiality cannot be guaranteed on emails sent or received unencrypted

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

bug#70140: Missing ./doc/guix-cookbook.pt_BR.texi

[Rostislav Svoboda]

> Rerun ./bootstrap and configure, then make

Yeap that helped. Thank you Efraim.

BTW there's a corresponding comment in the doc/local.mk which could be improved:

modified   doc/local.mk
@@ -21,7 +21,8 @@
 # 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.
+# If adding a language, update the following variables, and info_TEXINFOS and
+# rerun ./configure

And while at it, also the manual
https://guix.gnu.org/manual/devel/en/html_node/Writing-Documentation.html:

modified   doc/contributing.texi
@@ -2737,9 +2737,9 @@ Writing Documentation
 @xref{Translating Guix} for more information.

 To render documentation, you must first make sure that you ran
-@command{./configure} in your source tree (@pxref{Running Guix Before
-It Is Installed}).  After that you can run one of the following
-commands:
+@command{./configure} in your source tree (@pxref{Running Guix Before It
+Is Installed}).  This step must be done when adding a new language, too.
+After that you can run one of the following commands:


What do you think, should we patch these files?

Cheers Bost

bug#70140: Missing ./doc/guix-cookbook.pt_BR.texi

[pelzflorian (Florian Pelz)]

Hello Rostislav,

This advice would not be read by most affected Guix developers.  The
problem is that every guix developer must rerun ./bootstrap and
./configure on pulling certain changes like ABI breaks (when a new
record is added) and new cookbook versions.

Every Guix developer making a breaking change could put a notice
somewhere where it can be displayed from a pull hook, if that is
possible, but I don’t think developers would remember or that it is
worth the notification, also many would not read it.

Regards,
Florian

bug#70140: Missing ./doc/guix-cookbook.pt_BR.texi

[Rostislav Svoboda]

Hi Florian,

> This advice [...] I don’t think [...] it is worth the notification [...]

It ate me away ~1 work-hour, from the "It doesn't compile, what the
hell!?!" moment, all the way through the "What am I doing wrong?...
Nothing!" phases, until I found the culprit. And then the search for a
solution... in vain. So I wrote a bug report. Then it ate some 3
minutes from Efraim's time and 10 minutes of yours, I guess, and now
15 minutes of mine again.

And this will repeat basically every time we add a new language.
Currently, we're at 7 for the manual and 6 for the cookbook. Adding 5
new in each... In short, this is going to cost us 1 or 2
person-work-days, I estimate. And the indirect costs may be much
higher. E.g. if somebody thinks "I'm going to learn Guix while
translating it to my mother language" trips over this, well then he or
she may just throw it all away in frustration. Ups.

> also, many would not read it.

Except, it will be picked up by search engines and the AI(!):

Q: Hello, ChatGPT, tell me, am I the most handsome on this planet and
why doesn't the `make doc/guix.texi` compile? Somebody added a new
language aaaaand... it doesn't work anymore. Grrrh!
A: Oh well, you just need to rerun `./bootstrap` and `./configure`
when a new language is added to the Guix manual or cookbook. And the
most handsome on this planet? Forward-thinking people, kind enough to
write things down, so that others like me and you can learn from them.

Cheers, Bost

bug#70140: Missing ./doc/guix-cookbook.pt_BR.texi

[pelzflorian (Florian Pelz)]

My apologies for not giving a good response.

Yes, the issue you mention is indeed different from a record ABI
mismatch, in that the error message for an ABI message says
“recompilation needed” and is documented in the manual, unlike the
problematic error message that you reported.

Adding a note to doc/guix.texi would target the wrong audience, though,
because every Guix developer needs to rerun ./bootstrap, not only the
developer who added the translation.

The error message you reported

automake-1.16: error: cannot open < ./doc/guix-cookbook.pt_BR.texi: No
such file or directory

can be traced with “make --trace”.  It is because the
Autotools-generated Makefile recognizes that doc/local.mk has changed
and therefore runs “automake-1.16 --gnu Makefile”, which scans for the
Texinfo files mentioned in info_TEXINFOS and cannot open the mentioned
file.

Currrently the file “bootstrap” is a script that creates
“doc/guix.${lang}.texi” stub files.  When you don’t run “bootstrap”, the
files are missing.

At first sight, instead of creating the stub files in “bootstrap”, files
with

@setfilename guix.pt_BR.info
@include version-pt_BR.texi

for all languages could be pushed to guix.git by the developer who adds
the translation.  However, this is not enough, because “bootstrap” still
must run “touch po/doc/guix-manual.eo.po”, otherwise the PO4A rule to
create “doc/version-pt_BR.texi” is not run by GNU Make.

So there is no solution, is there?

Regards,
Florian

bug#70140: Missing ./doc/guix-cookbook.pt_BR.texi

[Rostislav Svoboda]

> So there is no solution, is there?

In short, you provided a detailed explanation why there's no automatic
solution for failing `make doc/guix.texi` when a new language is added
to the documentation. So far so good. I appreciate that.

However, this is exactly the kind of situation that is begging to be
documented somewhere, along with the instructions on how to get around
the problem. But no, what you're saying (and I'm paraphrasing here) is
"It's not worth it."

???

The whole point of your fa98837b1d commit was to update the
documentation. And now the documentation doesn't compile and you
effectively don't want to do anything about it, except explaining why.

Maybe we could add a small note to the "Writing Documentation"
chapter: "If the doc/guix.texi doesn't compile... well, we don't think
it's important enough to tell you what to do about it."

That would at least be an honest statement.

Cheers, Bost

bug#70140: Missing ./doc/guix-cookbook.pt_BR.texi

[pelzflorian (Florian Pelz)]

[-- Attachment #1: Type: text/plain, Size: 297 bytes --]

Hello Rostislav.

I do not know how to address the issue properly or where to document it.
The Writing Documentation section is the wrong place, because everyone
has to bootstrap again, not only the one who is writing documentation;
if we put a notice somewhere, then it would be something like:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: make-fails.diff --]
[-- Type: text/x-patch, Size: 1528 bytes --]

diff --git a/doc/contributing.texi b/doc/contributing.texi
index f5b01f42fd..2dd4be951f 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -194,24 +194,28 @@ After updating the repository, @command{make} might fail with an error
 similar to the following example:
 
 @example
 error: failed to load 'gnu/packages/linux.scm':
 ice-9/eval.scm:293:34: In procedure abi-check: #<record-type <origin>>: record ABI mismatch; recompilation needed
 @end example
 
 This means that one of the record types that Guix defines (in this
 example, the @code{origin} record) has changed, and all of guix needs
 to be recompiled to take that change into account.  To do so, run
 @command{make clean-go} followed by @command{make}.
 
+If after updating, @command{make} fails with another error message,
+you probably have to repeat all steps described here, starting with
+@command{./bootstrap}.
+
 @node Running Guix Before It Is Installed
 @section Running Guix Before It Is Installed
 
 In order to keep a sane working environment, you will find it useful to
 test the changes made in your local source tree checkout without
 actually installing them.  So that you can distinguish between your
 ``end-user'' hat and your ``motley'' costume.
 
 To that end, all the command-line tools can be used even if you have not
 run @code{make install}.  To do that, you first need to have an
 environment with all the dependencies available (@pxref{Building from
 Git}), and then simply prefix each command with @command{./pre-inst-env}

[-- Attachment #3: Type: text/plain, Size: 37 bytes --]


Would that be OK?

Regards,
Florian

bug#70140: Missing ./doc/guix-cookbook.pt_BR.texi

[Rostislav Svoboda]

Hello Florian,

> Would that be OK?

Yeah, that's it. Sure, it's not much but it is at least "something" we
can refer to and later improve upon.

Here is a different wording of your text (,aided by AI. Pick the one
of your liking and commit it please):

Should @command{make} fail with a new error message after updating, it
is recommended to revisit and repeat the steps outlined in this section,
commencing with @command{./bootstrap}.

Thanks & Cheers

bug#70140: Missing ./doc/guix-cookbook.pt_BR.texi

[pelzflorian (Florian Pelz)]

Pushed as 74517806f80dab17474a3c5f0b91d437e4d4e052.

I picked up some of your rewording and have changed the wording slightly
to mention Automake, to make it more likely to be picked up by search
engines when given the error.

Thank you for being insistent.

Regards,
Florian