Subject: Re: [bug#78463] [PATCH 2/2] news: Add news entry for new 'guix refresh' partial version syntax.
From: Maxim Cournoyer <[email-masked]>
To: "pelzflorian (Florian Pelz)" <[email-masked]>
Cc: Julien Lepiller <[email-masked]>, [email-masked]
Date: Mon, 19 May 2025 10:10:52 +0900
List-Id: <debbugs-submit.debbugs.gnu.org>

Hi Florian,

"pelzflorian (Florian Pelz)" <[email-masked]> writes:

> A good change (untested).
>
> It is not appropriate to write XXX: in comments on your first
> patch’s unit tests, as I understand the Wiktionary definition of XXX:
>
> 2. (computing) Used as a placeholder in source code to mark that some work
> still has to be done.

That's close to the meaning I use it for: something inelegant or dirty,
that would better be rewritten if someone knows better.  In other words,
it's functional but not ideal/hacky.  To mark some work that would need
doing in the future, I'd use a TODO instead.

I'm not sure if that's the most correct definition, but that's at least
how I've always understood it to be used in the Guix code base, e.g. by
Ludovic.

> Could you add this German translation?

Done, thank you!

> Additionally, I surrounded the info command in @command{} markup in the
> last line of the English news, too.
>
>         (title
>          (en "@samp{guix refresh} can now target partial versions")
>          (de "@samp{guix refresh} kann jetzt unvollständige Versionen als Ziel
> nehmen"))
>         (body
>          (en "While it had been possible for some time to use the
> @option{--target-version} to update to a partially defined version, this can
> now be more conveniently expressed via the package version specification
> directly, by prefixing it with the tilde (@samp{~}) character:
>
> @example
> $ guix refresh bash=~5.2
> gnu/packages/bash.scm:150:15: bash would be upgraded from 5.1.16 to 5.2.37
> @end example
>
> For more information, see @command{info \"(guix) Invoking guix refresh\"}.")

It doesn't seem to be explained in the Texinfo manual, but @command is
really only supposed to be used with a single word/command, not a
command line.  For the later @samp should be used instead.  That's
explained in (info "(texinfo) @command").

In this case though, I meant it to be this way: I've recently discovered
that when visiting a Texinfo node in a manual in Emacs, you can copy the
reference to it with 'C-0 c', then paste it somewhere.  Emacs users can
then jump straight to it by evaluating it with C-x C-e (with the cursor
placed after the closing parens).  I recently found that trick, I think
it's neat!  I seem to recall that Gnus also had a means to linkify such
references directly in email.

Thanks for the review and translation, as well as to Ludovic's.

Pushed with commit 450a3615325.  Closing.

-- 
Thanks,
Maxim