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

[Leo Famulari <leo@famulari.name>]

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

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.

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