From mboxrd@z Thu Jan 1 00:00:00 1970 From: ludo@gnu.org (Ludovic =?utf-8?Q?Court=C3=A8s?=) Subject: Re: [PATCH] doc: Improve wording and fix typos in "Introduction" and "Requirements". Date: Sat, 25 May 2013 15:56:22 +0200 Message-ID: <8761y75fjt.fsf@gnu.org> References: <87r4gwh8jm.fsf@karetnikov.org> <87ip28wfj1.fsf@gnu.org> <87k3mnnboc.fsf@karetnikov.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([208.118.235.92]:34627) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UgExa-0006Is-Fp for bug-guix@gnu.org; Sat, 25 May 2013 09:56:42 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UgExW-0002xO-0e for bug-guix@gnu.org; Sat, 25 May 2013 09:56:38 -0400 Received: from [2a01:e0b:1:123:ca0a:a9ff:fe03:271e] (port=50084 helo=xanadu.aquilenet.fr) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UgExV-0002vn-OB for bug-guix@gnu.org; Sat, 25 May 2013 09:56:33 -0400 In-Reply-To: <87k3mnnboc.fsf@karetnikov.org> (Nikita Karetnikov's message of "Sat, 25 May 2013 04:30:27 +0400") List-Id: Bug reports for GNU Guix List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-guix-bounces+gcggb-bug-guix=m.gmane.org@gnu.org Sender: bug-guix-bounces+gcggb-bug-guix=m.gmane.org@gnu.org To: Nikita Karetnikov Cc: bug-guix@gnu.org Nikita Karetnikov skribis: >> But anyway, the normal way to use Texinfo is like TeX: you use ASCII >> quotes, and it does the right thing (see the PDF output, and the Info >> output if you=E2=80=99re using makeinfo 5.x.) > > I know, I was talking about the output of 'makeinfo --html'. I'm using > 4.13. The same applies. >> There seems to be some paragraph filling at least here. > > Yes, I did that to keep the length under 79 characters and to avoid the > lines which consist of a couple of words. OK. For review, it=E2=80=99s better to not fill, and it=E2=80=99s acceptab= le to break the 79-char rule for that. >> Could you rearrange the patch to avoid paragraph filling, so that only >> the parts that were really changed show up? > > Is it OK? Mostly OK, see comments below. > @@ -96,42 +96,41 @@ Documentation License.'' > GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``=C9=A1i=CB= =90ks'' > using the international phonetic alphabet (IPA).} is a functional > package management tool for the GNU system. Package management consists > -in all the activities that relate to building packages from source, > -honoring the build-time and run-time dependencies on packages, > +of all activities that relate to building packages from sources, > +preserving their build-time and run-time dependencies, =E2=80=9CConsists of=E2=80=9D may be OK (any native speaker around, though?= ). =E2=80=9CPreserving=E2=80=9D instead of =E2=80=9Chonoring=E2=80=9D changes = the meaning. The intended meaning of the sentence was that the system would automatically install any dependencies, or, if building from source, install any build time dependencies. What did you mean? > @cindex functional package management > -The term @dfn{functional} refers to a specific package management > -discipline. In Guix, the package build and installation process is seen > -as a function, in the mathematical sense: that function takes inputs, > -such as build scripts, a compiler, and libraries depended on, and > -returns the installed package. As a pure function, its result depends > +The term @dfn{functional} refers to a specific set of package management > +features. No, I really meant =E2=80=9Cpackage management discipline=E2=80=9D (as in t= he phrase =E2=80=9Cmemory management discipline=E2=80=9D), because features are just = a byproduct. > In Guix, the package build and installation process is seen > +as a function, in the mathematical sense. That function takes inputs, > +such as build scripts, a compiler, and libraries, and > +returns an installed package. As a pure function, its result depends OK. > solely on its inputs---for instance, it cannot refer to software or > scripts that were not explicitly passed as inputs. A build function > -always produces the same result when passed a given set of inputs. Last > -but not least, a build function cannot alter the system's environment in > +always produces the same result when passed the same set of inputs. It > +cannot alter the system's environment in OK. > any way; for instance, it cannot create, modify, or delete files outside > of its build and installation directories. This is achieved by running > -build processes in dedicated ``chroots'', where only their explicit > -inputs are visible. > +build processes in isolated environments (or @dfn{chroots}), where only = their > +explicit inputs are visible. OK. > @cindex store > -The result of package build functions is @dfn{cached} in the file > +The result of package's build functions is @dfn{cached} in the file No. > system, in a special directory called @dfn{the store} (@pxref{The > -Store}). Each package is installed in a directory of its own, in the > -store---by default under @file{/nix/store}. The directory name contains > -a hash of all the inputs used to build that package; thus, changing an > +Store}). Each installed package has its own directory there. > +The directory name contains > +a hash of all build inputs of that package; thus, changing an > input yields a different directory name. I prefer the initial wording. > This approach is the foundation of Guix's salient features: support for > -transactional package upgrades and rollback, per-user installation, and > +transactional package upgrades and rollbacks, per-user installation, and > garbage collection of packages (@pxref{Features}). Rather make =E2=80=9Cupgrade=E2=80=9D singular. > -Guix has a command-line interface allowing users to build, install, > +Guix has a command-line interface which allows users to build, install, Comma before =E2=80=9Cwhich=E2=80=9D. > upgrade, and remove packages, as well as a Scheme programming interface. > -The remainder of this manual describes them. OK. > -When a working installation of the Nix package manager is available, you > +When a working installation of @url{http://nixos.org/nix/, the Nix packa= ge > +manager} is available, you > can instead configure Guix with @code{--disable-daemon}. In that case, > -@url{http://nixos.org/nix/, Nix} replaces the three dependencies above. > +Nix replaces the three dependencies above. OK. > Guix is compatible with Nix, so it is possible to share the same store > between both. To do so, you must pass @command{configure} not only the > same @code{--with-store-dir} value, but also the same > -@code{--localstatedir} value (the latter is essential because it > -specifies where the database that store meta-data about the store is > -located, among other things.) The default values are > +@code{--localstatedir} value. The latter is essential because it > +specifies where the database that stores metadata about the store is > +located, among other things. The default values are > @code{--with-store-dir=3D/nix/store} and @code{--localstatedir=3D/nix/va= r}. > -Note that @code{--disable-daemon} is orthogonal and is not required if > -your goal is to share the same store as Nix. > +Note that @code{--disable-daemon} is not required if > +your goal is to share the store with Nix. OK. Note that sometimes wording really deserves an improvement, but sometimes it=E2=80=99s really a matter of taste. I think the patch contain= s a little of both, but I=E2=80=99d really prefer a focus on the former. Actually, documentation-wise, my wish would be for people to primarily focus on those parts of the manual that are *not* written yet. :-) Thanks! Ludo=E2=80=99.