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

[Eric Bavier <ericbavier@centurylink.net>]

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

On Sun, 12 Nov 2017 15:36:44 -0500
Leo Famulari <leo@famulari.name> 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.

> 
> 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.

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

`~Eric

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