[bug#29271] [PATCH 1/1] doc: Split the "Substitutes" section into subsections.

[Leo Famulari]

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.

> address@hidden
>  @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
Description: PGP signature