Missing ./doc/guix-cookbook.pt_BR.texi

Done

Details

3 participants

Efraim Flashner
pelzflorian (Florian Pelz)
Rostislav Svoboda

Owner: unassigned

Submitted by: Rostislav Svoboda

Severity: normal

Rostislav Svoboda wrote on 2 Apr 15:59 +0200

Recipients:

Message-ID:CAEtmmew9hTFFGFShJwXpisSpTvm8BS-kmoBq-e13hxoj+U=qDQ@mail.gmail.com

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

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

Toggle diff (21 lines)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 wrote on 2 Apr 18:20 +0200

Recipients:(name . Rostislav Svoboda)(address . rostislav.svoboda@gmail.com)

Message-ID:ZgwwU_bMPL1_AXk7@3900XT

Rerun ./bootstrap and configure, then make

On Tue, Apr 02, 2024 at 03:59:36PM +0200, Rostislav Svoboda wrote:

Toggle quote (54 lines)> $ 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

Rostislav Svoboda wrote on 3 Apr 01:37 +0200

Recipients:(address . pelzflorian@pelzflorian.de)

Message-ID:CAEtmmewUg6mXwLniqa7LjJ7Ge7kO2kzAqe1vHR=U26qk1ioZwg@mail.gmail.com

Toggle quote (2 lines)

> 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

pelzflorian (Florian Pelz) wrote on 3 Apr 12:11 +0200

Recipients:(name . Rostislav Svoboda)(address . rostislav.svoboda@gmail.com)

Message-ID:87zfuaoiw5.fsf@pelzflorian.de

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

Rostislav Svoboda wrote on 3 Apr 15:41 +0200

Recipients:(name . pelzflorian (Florian Pelz))(address . pelzflorian@pelzflorian.de)

Message-ID:CAEtmmewkS7oRi-c_ydO019UaYbXykUb7+oSQKrOStN-mrXFWgQ@mail.gmail.com

Hi Florian,

Toggle quote (2 lines)

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

Toggle quote (2 lines)

> 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

pelzflorian (Florian Pelz) wrote on 3 Apr 20:14 +0200

Recipients:(name . Rostislav Svoboda)(address . rostislav.svoboda@gmail.com)

Message-ID:87a5mafh3x.fsf@pelzflorian.de

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

Rostislav Svoboda wrote on 4 Apr 14:09 +0200

Recipients:(name . pelzflorian (Florian Pelz))(address . pelzflorian@pelzflorian.de)

Message-ID:CAEtmmeyhmZ+vz9nckW7HiYtcs5Rp64b7bd4piN-BLCfOccvetQ@mail.gmail.com

Toggle quote (2 lines)

> 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

pelzflorian (Florian Pelz) wrote on 4 Apr 20:33 +0200

Recipients:(name . Rostislav Svoboda)(address . rostislav.svoboda@gmail.com)

Message-ID:87jzldx9k0.fsf@pelzflorian.de

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:

Toggle diff (33 lines)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}

Would that be OK?

Regards,

Florian

Rostislav Svoboda wrote on 5 Apr 12:14 +0200

Recipients:(name . pelzflorian (Florian Pelz))(address . pelzflorian@pelzflorian.de)

Message-ID:CAEtmmezNPDt2TzXDMx0xabSsj_bTuUzJP2hkPV5sAPMq5+DRTA@mail.gmail.com

Hello Florian,

Toggle quote (2 lines)

> 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

pelzflorian (Florian Pelz) wrote on 5 Apr 17:01 +0200

Recipients:(name . Rostislav Svoboda)(address . rostislav.svoboda@gmail.com)

Message-ID:87cyr3ua44.fsf@pelzflorian.de

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

Closed

Your comment

This issue is archived.

To comment on this conversation send an email to 70140@debbugs.gnu.org

To respond to this issue using the mumi CLI, first switch to it

mumi current 70140

Then, you may apply the latest patchset in this issue (with sign off)

mumi am -- -s

Or, compose a reply to this issue

mumi compose

Or, send patches to this issue

mumi send-email *.patch

is:open	open issues
is:done	closed issues
submitter:<who>	search issue submitter
author:<who>	search by message author
date:yesterday..now	search by issue date
mdate:3m..2d	search by message date