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

From: [email-masked] (Ludovic Courtès)
Date: Mon, 20 Nov 2017 23:40:53 +0100

Hello!

Eric Bavier <[email-masked]> skribis:

> On Sun, 12 Nov 2017 15:36:44 -0500
> Leo Famulari <[email-masked]> wrote:
>
>> On Sun, Nov 12, 2017 at 03:05:58AM -0800, Chris Marusich wrote:
>> > +@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.
>
> Same here.

[...]

> IMHO, the original text is just fine, and succinctly conveys the
> origin of the option name. Perhaps just add the cross reference.

I agree, but I’m biased.  ;-)

Apart from that, the rest LGTM.  I have one minor request:

> +* Hydra::                           One particular source of substitutes.

I would call this “Official Substitute Server” or something like that,
and not mention Hydra (as a proper noun) since we’re not defining it,
and since the server won’t run Hydra forever.

With these two changes, I think you can push.

Thanks for improving the manual!

Ludo’.