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

  • Done
  • quality assurance status badge
Details
3 participants
  • Efraim Flashner
  • pelzflorian (Florian Pelz)
  • Rostislav Svoboda
Owner
unassigned
Submitted by
Rostislav Svoboda
Severity
normal
R
R
Rostislav Svoboda wrote on 2 Apr 15:59 +0200
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>
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

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 = \
E
E
Efraim Flashner wrote on 2 Apr 18:20 +0200
(name . Rostislav Svoboda)(address . rostislav.svoboda@gmail.com)
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
-----BEGIN PGP SIGNATURE-----

iQIzBAABCAAdFiEEoov0DD5VE3JmLRT3Qarn3Mo9g1EFAmYMMFMACgkQQarn3Mo9
g1GpnQ/+JIac/GsUznUQdQO5/OjHikcjRwr1tyQmq8oDw8M8DdliBsBy6H9LugPM
DInB0tp1csalmv4R/byqdYSpBKnjT2SHkWOqqeIBhpVedrYQ5bEabgAFk0xzEoEV
MUS6V/H4/0LhqliErBNZlur4cogbDg5k3M/uUE0aNB5Gma8OcgbVkmGt5L6tbtji
4mNvM3JCP5rud2+dnVlDC2l2lt5wl+qgQf3giCR5QDuc2x+uAw/xx/R8BJm9mAPX
bpq5FGb6sW/f7ysSWnN6Z0cZygONFhnEc4n0x5kiUjqPfua1G5Vs85+o4vn/J9gx
jilMvwCWsox4GGaal17/ng/k5ocMzLC9vJlki0HasvmNm8WWjMNSDb5itGVET91G
Z3uUROHt25vIvGzjr7RmJNKDR/BPMptob1RQZSyMnUF0QWE7/bUSUm3XSCa6EItt
r1CKByd+CUnBW7fxflGC/yZ3ZTxjXF5VfIaqEEpc+Kxc2LLOJc9jRqg5OQaQLNsL
D/Z2z9AeoFpPZKVB5969svI7fVLVkcRsNCNdysk1ax2kHpkBitAJ6dYKZldt5T8V
XxamwoQ0mzsfj2Jh5+sdQ5s9GhS3ELKFCJo8o+8Fgm0AIQpC59CranQvOQssLxff
hvpv4VCxFUMlCF+xw8/SMM3TXCKFBo67+m7Dx8fZKoFHHbHqqKU=
=LrSk
-----END PGP SIGNATURE-----


R
R
Rostislav Svoboda wrote on 3 Apr 01:37 +0200
(address . pelzflorian@pelzflorian.de)
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

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
P
P
pelzflorian (Florian Pelz) wrote on 3 Apr 12:11 +0200
(name . Rostislav Svoboda)(address . rostislav.svoboda@gmail.com)
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
R
R
Rostislav Svoboda wrote on 3 Apr 15:41 +0200
(name . pelzflorian (Florian Pelz))(address . pelzflorian@pelzflorian.de)
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
P
P
pelzflorian (Florian Pelz) wrote on 3 Apr 20:14 +0200
(name . Rostislav Svoboda)(address . rostislav.svoboda@gmail.com)
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
R
R
Rostislav Svoboda wrote on 4 Apr 14:09 +0200
(name . pelzflorian (Florian Pelz))(address . pelzflorian@pelzflorian.de)
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
P
P
pelzflorian (Florian Pelz) wrote on 4 Apr 20:33 +0200
(name . Rostislav Svoboda)(address . rostislav.svoboda@gmail.com)
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
R
R
Rostislav Svoboda wrote on 5 Apr 12:14 +0200
(name . pelzflorian (Florian Pelz))(address . pelzflorian@pelzflorian.de)
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
P
P
pelzflorian (Florian Pelz) wrote on 5 Apr 17:01 +0200
(name . Rostislav Svoboda)(address . rostislav.svoboda@gmail.com)
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
?