Fixing Zabbix db-secret-file documentation.

Fixing Zabbix db-secret-file documentation.

[Tobias Geerinckx-Rice]

[-- Attachment #1.1: Type: text/plain, Size: 615 bytes --]

Guix,

We currently claim that db-secret-file is appended to 
zabbix.conf.php.

To me that can only mean:

  $ cat db-secret-file
  $DB['PASSWORD'] = 'supersecure'
  $DB['maybe'] = 'some more sekrit stuff too'

but it's really just:

  "$DB['PASSWORD'] = '" (with-input-from-file db-secret-file
                                             read-string) "';"

It's late into 1.2 to invalidate manual translations.  However, 
I'm sceptical of shipping a translated-but-IMO-incorrect snippet 
over a better English one just to boost coverage stats, and would 
like to push it anyway.  Thoughts?

Kind regards,

T G-R


[-- Attachment #1.2: 0001-doc-Better-document-Zabbix-db-secret-file.patch --]
[-- Type: text/x-patch, Size: 1340 bytes --]

From c6746726e4db7f674297de79ae599ca9686658a1 Mon Sep 17 00:00:00 2001
From: Tobias Geerinckx-Rice <me@tobias.gr>
Date: Fri, 6 Nov 2020 13:17:00 +0100
Subject: [PATCH 1/2] =?UTF-8?q?doc:=20Fix=20Zabbix=20?=
 =?UTF-8?q?=E2=80=98db-secret-file=E2=80=99=20documentation.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* doc/guix.texi (Monitoring Services): Document ‘db-secret-file’'s (lack
of) structure and gexp support.
---
 doc/guix.texi | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 217ed7a8a8..1c29799d6c 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -22168,9 +22168,10 @@ Defaults to @samp{""}.
 @end deftypevr
 
 @deftypevr {@code{zabbix-front-end-configuration} parameter} string db-secret-file
-Secret file which will be appended to @file{zabbix.conf.php} file.  This
-file contains credentials for use by Zabbix front-end.  You are expected
-to create it manually.
+Secret file containing the credentials for the Zabbix front end.  The value
+must be a local file name, not a G-expression.  You are expected to create
+this file manually.  Its contents will be copied into @file{zabbix.conf.php}
+as the value of @code{$DB['PASSWORD']}.
 
 Defaults to @samp{""}.
 
-- 
2.29.2


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

Re: Fixing Zabbix db-secret-file documentation.

[Oleg Pykhalov]

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

Hi,

Tobias Geerinckx-Rice <me@tobias.gr> writes:

[…]

>  @deftypevr {@code{zabbix-front-end-configuration} parameter} string db-secret-file
> -Secret file which will be appended to @file{zabbix.conf.php} file.  This
> -file contains credentials for use by Zabbix front-end.  You are expected
> -to create it manually.
> +Secret file containing the credentials for the Zabbix front end.
                                                         ^^^^^^^^^
                                                         front-end as in
                                                         other places of
                                                         the documentation

Otherwise I agree with a change.  Thanks.

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

Re: Fixing Zabbix db-secret-file documentation.

[Tobias Geerinckx-Rice]

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

Oleg Pykhalov 写道：
>>                                                         front 
>>                                                         end
>                                                          ^^^^^^^^^
>                                                          front-end 
>                                                          as in
>                                                          other 
>                                                          places 
>                                                          of
>                                                          the 
>                                                          documentation

Thanks for pointing it out, I hadn't noticed!  The other places 
are mistaken, though.

‘Front-end’ is an adjective (‘a front-end component’), not a noun 
(‘the front end’).  Worse, it looks jarring.  Even GCC agrees[0] 
with me for once.

I've changed it to front-end just for consistency... for now ;-) 
and pushed to master as 83dee0e5b29dee75cffd5aa2a7748697eb73b036. 
If nobody objects I'll cherry-pick it to version-1.2.0 before the 
release.  That'll be the on-line manual for some time to come.

Thanks!

T G-R

[0]: http://gcc.gnu.org/codingconventions.html#Spelling

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

Re: Fixing Zabbix db-secret-file documentation.

[Miguel Ángel Arruga Vivas]

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

Hi!

Tobias Geerinckx-Rice <me@tobias.gr> writes:
> I've changed it to front-end just for consistency... for now ;-) and
> pushed to master as 83dee0e5b29dee75cffd5aa2a7748697eb73b036. If
> nobody objects I'll cherry-pick it to version-1.2.0 before the
> release.  That'll be the on-line manual for some time to come.

I have to raise my hand here, as TP.org hasn't updated their page yet,
or at least I haven't received the email yet, but the tarball was
already sent.  Perhaps we're lucky and the first mail may end in
/dev/null with no fuss if we send the update soon....  Julien, WDYT?

Just for the record, I'm glad to translate that change or whatever comes
next, but it makes me a bit sad when that effort is reduced to a number,
because that "number" means making accessible the documentation to
people who don't speak English.  I understand what you meant, and I
agree about the change too; I just wanted to clarify that it isn't a
matter of boosting stats but working together.

Happy hacking!
Miguel

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

Re: Fixing Zabbix db-secret-file documentation.

[Tobias Geerinckx-Rice]

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

Miguel,

Thank you, and everyone else, for all your translation efforts. 
I've translated before.  It's ruddy hard work.

Miguel Ángel Arruga Vivas 写道：
> Tobias Geerinckx-Rice <me@tobias.gr> writes:
> Just for the record, I'm glad to translate that change or 
> whatever comes
> next, but it makes me a bit sad when that effort is reduced to a 
> number,

I'm not reducing your effort to a number, quite the opposite: I 
meant that keeping the old wording ‘just because it's already been 
translated’ would be doing so.  Nobody actually suggested that, 
and I'm very happy that you're both willing and able to translate 
new strings so late.  I wasn't expecting that.

Let me know what needs to happen if there's still time!

T G-R

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

Re: Fixing Zabbix db-secret-file documentation.

[Miguel Ángel Arruga Vivas]

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

Hi!

Tobias Geerinckx-Rice <me@tobias.gr> writes:
> Miguel,
>
> Thank you, and everyone else, for all your translation efforts. I've
> translated before.  It's ruddy hard work.

You're welcome, and thank you too: we had nothing to translate if nobody
pushed changes to make Guix even more awesome than it currently is. :-)

> Miguel Ángel Arruga Vivas 写道：
>> Tobias Geerinckx-Rice <me@tobias.gr> writes:
>> Just for the record, I'm glad to translate that change or whatever
>> comes
>> next, but it makes me a bit sad when that effort is reduced to a
>> number,
>
> I'm not reducing your effort to a number, quite the opposite: I meant
> that keeping the old wording ‘just because it's already been
> translated’ would be doing so.

No problem, I understood, but my point really was that it isn't a
problem because "it's already been translated" but because "it triggers
again a procedure which was already taking place".

> Nobody actually suggested that, and I'm very happy that you're both
> willing and able to translate new strings so late.  I wasn't expecting
> that.

I try to maintain the translation up to date, as I'd like to keep "info
guix.es" as close as possible to a fully translated "info guix" (quite
hard to do though, and not really an option with our current flow), so
for me it actually means just one change in my working PO file, but that
isn't usually the case for everybody.

> Let me know what needs to happen if there's still time!

I guess that pushing another tarball to TP isn't the path we're going to
take as I feel it will cause more friction on that side, but surely we
could do it, even only sending one for the manual is a possibility
there.  On the other hand, removing that phrase is an editorial change
that perhaps could be done at project level instead of at TP: querying
the translators directly how to remove the old bits from their
translation may be an option for this.  The last option (that I don't
like neither, but it isn't on my hand to take a final decision) is to
keep the release as it is: it wouldn't affect the manual shown by the
installation, but it'll be lost as soon as a pull is performed.

WDYT?

Happy hacking!
Miguel

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