From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:43106) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eEq9G-0004Sj-JZ for guix-patches@gnu.org; Wed, 15 Nov 2017 00:22:07 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eEq9C-00059d-J9 for guix-patches@gnu.org; Wed, 15 Nov 2017 00:22:06 -0500 Received: from debbugs.gnu.org ([208.118.235.43]:60415) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1eEq9C-00059P-FE for guix-patches@gnu.org; Wed, 15 Nov 2017 00:22:02 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1eEq9C-0008Gf-61 for guix-patches@gnu.org; Wed, 15 Nov 2017 00:22:02 -0500 Subject: [bug#29271] [PATCH 1/1] doc: Split the "Substitutes" section into subsections. Resent-Message-ID: From: Chris Marusich References: <20171112110233.1384-1-cmmarusich@gmail.com> <20171112110558.1447-1-cmmarusich@gmail.com> <87mv3rwqgo.fsf@gnu.org> <20171112202506.GA10629@jasmine.lan> <86lgjap7mz.fsf@gmail.com> Date: Tue, 14 Nov 2017 21:21:05 -0800 In-Reply-To: <86lgjap7mz.fsf@gmail.com> (myglc2@gmail.com's message of "Mon, 13 Nov 2017 09:37:08 -0500") Message-ID: <87efp0nmm6.fsf@gmail.com> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha256; protocol="application/pgp-signature" List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+kyle=kyleam.com@gnu.org Sender: "Guix-patches" To: myglc2 Cc: 29271@debbugs.gnu.org --=-=-= Content-Type: text/plain Content-Transfer-Encoding: quoted-printable Hi everyone, Thank you for taking the time to review my patch! myglc2 writes: > On 11/12/2017 at 20:25 Leo Famulari writes: > > ISTM that "disabled by default when using Guix on a foreign > distribution" is too strong. How about ... > > Substitutes from Hydra are enabled by default in the Guix System > Distribution (@pxref{GNU Distribution}) and by one of the recommended > installation steps for Guix on a foreign distribution > (@pxref{Installation}). What if we say something like "disabled by default when using Guix on a foreign distro, unless you've explicitly enabled them via one of the recommended installation steps (@pxref{Installation})"? Let me know if you think that would be OK. I want to clarify the fact that the substitutes are disabled by default when installing Guix on a foreign distro. That's a bit surprising, and it needs to be clear. At the same time, I think it's good to remind users that they are in full control and can enable the substitutes easily. Leo Famulari writes: > 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. No, there is no duplication (as far as I can tell!). 90% of this commit is about moving existing text into subsections. 9% is the new sub-section "Substitution Failure", and 1% is minor adjustments elsewhere (e.g., removing an incorrect statement from the "Invoking guix-daemon" section). If this were code, I might have broken it out more into separate commits, but since the GNU standards explicitly say that we don't even need ChangeLog entries for documentation, I think it's OK to conveniently squish these changes into one commit. >> +@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. I agree that is better, as long as we include a cross-reference to the more detailed "Substitution Failure" section (which is what Eric suggested). I'll update the patch along those lines. myglc2 writes: > Chris, > > I installed the patch and read the sections. This is great stuff. > > In addition to the minor suggestion in a sub-thread, how about > replacing... > >> +When substitutes are enabled and a substitute for a derivation is >> +available, but the substitution attempt fails, Guix will attempt to >> +build the derivation locally depending on whether or not >> +@code{--fallback} was given (@pxref{fallback-option}). Specifically, if >> +@code{--fallback} was omitted, then no local build will be performed, >> +and the derivation is considered to have failed. However, if >> +@code{--fallback} was given, then Guix will attempt to build the >> +derivation locally, and the success or failure of the derivation depends >> +on the success or failure of the local build. Note that when > > ... with... > > When substitutes are enabled and a substitute for a derivation is > available, but the substitution attempt fails, Guix will report an error > unless the @code{--fallback} was given (@pxref{fallback-option}), in > which case Guix will attempt to build the derivation locally Note that > when Personally, I prefer the more detailed explanation because it's less ambiguous. What does "report an error" mean? To those who already know, it might be clear, but to someone who is learning for the first time, the ambiguity is unhelpful. However, if others prefer the less verbose wording, I will use it. What do you think, Leo and Eric? =2D-=20 Chris --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAEBCAAdFiEEy/WXVcvn5+/vGD+x3UCaFdgiRp0FAloLzsEACgkQ3UCaFdgi Rp3f/Q//XgIdv+26mw3kb8nh7vbfDkxIu0CB+c/m/k9BzYzsEDpZcmBth5hPWRfi 7TUnddxe8sGCGMiFnTohYu1QOJ6M+pIGIWCCKcJOnxl60vIhHFLsqughybxfO+pM Gsrs2ipzuqRKxpm9hgSiShjkmN1dxHvrSKbhgYysJYm5IpGM8AJjxfqRMMXevce0 WAO3pHIOKVUgUqHSf1nWR3iviluVWziAD/YtSuMPiw89mA7PGohXJdmvT3lQsnpQ Zad07Au8WjooQVsZ0i1h8CfAD0lmD/RXECa+BDI2vfwpescvRaB3IVeQUwZ+VjE5 zKCNWopv/f39iQ8FQ3mGVzIDwQp0W9axz3VLWMai45fg36cv2VpxeVSPApdrbHva 67XgnlUuXmNo/WdvJRihvLD8ZcYuwpPQttKG3Ta6Cu2SNGNNfqkhadR0+isIEROo +EYK+nOlKVlDkrZPaf/GmQvBkC3Z2M+y5Q5n77s74Iffz906i6y7+xj4l+HH/2EQ vN1ZPJK1afI8HNmmDUf8OLpGdncyPzddVP1dAeVgSTgPUdGm2gyzehz/cWv+hWwk sCdDX3KoYbi3dxkl2ntBO3ms78kdz3nnCgRdVypg6XkY193Yx90g6GZ42B0XlC2R zOnF5Jd79ln81lIOEpRwInF6tCKXUWBc3/RzswXpS/QdBCB2X+k= =IjBA -----END PGP SIGNATURE----- --=-=-=--