From: Leo Famulari <leo@famulari.name>
To: Chris Marusich <cmmarusich@gmail.com>
Cc: 29271@debbugs.gnu.org, myglc2@gmail.com
Subject: [bug#29271] [PATCH 1/1] doc: Split the "Substitutes" section into subsections.
Date: Sun, 12 Nov 2017 15:36:44 -0500 [thread overview]
Message-ID: <20171112203644.GB10629@jasmine.lan> (raw)
In-Reply-To: <20171112110558.1447-1-cmmarusich@gmail.com>
[-- 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 --]
next prev parent reply other threads:[~2017-11-12 20:38 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-11-12 11:02 [bug#29271] [PATCH 0/1] Improve the "Substitutes" documentation Chris Marusich
2017-11-12 11:05 ` [bug#29271] [PATCH 1/1] doc: Split the "Substitutes" section into subsections Chris Marusich
2017-11-12 13:56 ` Jan Nieuwenhuizen
2017-11-12 20:25 ` Leo Famulari
2017-11-13 14:37 ` myglc2
2017-11-15 5:21 ` Chris Marusich
2017-11-15 13:31 ` myglc2
2017-11-12 20:36 ` Leo Famulari [this message]
2017-11-12 19:17 ` Eric Bavier
2017-11-20 22:40 ` Ludovic Courtès
2017-11-13 17:27 ` myglc2
2017-11-12 11:21 ` [bug#29271] [PATCH 0/1] Improve the "Substitutes" documentation Adonay Felipe Nogueira
2017-11-22 4:29 ` bug#29271: Status: " Chris Marusich
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20171112203644.GB10629@jasmine.lan \
--to=leo@famulari.name \
--cc=29271@debbugs.gnu.org \
--cc=cmmarusich@gmail.com \
--cc=myglc2@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/guix.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.