GNU bug report logs - #29271
[PATCH 0/1] Improve the "Substitutes" documentation

Previous Next

Full log

View this message in rfc822 format

From: Leo Famulari <leo <at> famulari.name>
To: Chris Marusich <cmmarusich <at> gmail.com>
Cc: myglc2 <at> gmail.com, 29271 <at> debbugs.gnu.org
Subject: [bug#29271] [PATCH 1/1] doc: Split the "Substitutes" section into subsections.
Date: Sun, 12 Nov 2017 15:36:44 -0500

[Message part 1 (text/plain, inline)]

On Sun, Nov 12, 2017 at 03:05:58AM -0800, Chris Marusich wrote:
> * doc/guix.texi (Substitutes): Move information into sections, and create one
>   new subsection regarding substitution failure.
>   (Top): In the detailed listing, add entries for the new subsections.
>   (Hydra): Move info about Hydra here.  Add information that explains when
>   substitutes are enabled by default.
>   (Substitute Server Authorization): Move information about how to enable or
>   disable substitutes here.
>   (Substitute Authentication): Move information about how Guix authenticates
>   substitutes here.
>   (Proxy Settings): Move information about how to download substitutes via
>   proxy here.
>   (Substitution Failure): New section.  Add information about how Guix handles
>   substitution failure.  Be extra clear about behavior concerning --fallback.
>   (On Trusting Binaries): Move information about trusting binaries here.
>   (Invoking guix-daemon): Remove an incorrect statement about when substitutes
>   are enabled by default.
>   (Common Build Options): Clarify the behavior of --fallback.

Hi, thanks for your efforts to improve the documentation.

Personally, I find it impossible to read diffs of natural language text;
it just doesn't work for me like it does with code.

So, I will just ask, does this duplicate instructions regarding
substitutes in other sections? We should be careful to avoid that.

> +@anchor{fallback-option}
>  @item --fallback
> -When substituting a pre-built binary fails, fall back to building
> -packages locally.
> +Attempt to build locally instead of issuing an error when substitutes
> +are enabled and a substitute is available, but the substitution attempt
> +fails (@pxref{Substitution Failure}).

I was able to read this smaller change. I think the new sentence is too
byzantine. I know what --fallback does but I found this sentence hard to
understand.

The condition that determines whether we "attempt to build locally"
should be at the beginning of the sentence, like this:

"When substitutes are enabled and a substitute is available, but the
substitution fails, fall back to building the derivation locally."

This is basically the same as before, but with some more detail about
the condition.

[signature.asc (application/pgp-signature, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.