From mboxrd@z Thu Jan 1 00:00:00 1970 From: Alex Sassmannshausen Subject: Re: [PATCH] doc: Improve wording and fix typos in "Introduction" and "Requirements". Date: Sun, 26 May 2013 01:28:42 +0200 Message-ID: <1369524522.3627.2.camel@Nokia-N900> References: <87r4gwh8jm.fsf@karetnikov.org> <87ip28wfj1.fsf@gnu.org> <87k3mnnboc.fsf@karetnikov.org> <8761y75fjt.fsf@gnu.org> Reply-To: Alex Sassmannshausen Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Return-path: Received: from eggs.gnu.org ([208.118.235.92]:46862) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UgO0U-0007D3-PO for bug-guix@gnu.org; Sat, 25 May 2013 19:36:17 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UgO0R-0001Wt-CM for bug-guix@gnu.org; Sat, 25 May 2013 19:36:14 -0400 In-Reply-To: <8761y75fjt.fsf@gnu.org> Content-ID: <1369524522.3627.1.camel@Nokia-N900> 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: Ludovic =?ISO-8859-1?Q?Court=E8?= , Nikita Karetnikov Cc: bug-guix@gnu.org 'Consists of' is the correct phrase in this context. Best wishes, Alex On sam. 25 mai 2013 15:56:22 CEST, Ludovic Courtès wrote: > 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’re 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’s better to not fill, and it’s acceptable 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 ``ɡiːks'' > > 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, > > “Consists of” may be OK (any native speaker around, though?). > > “Preserving” instead of “honoring” 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 “package management discipline” (as in the phrase > “memory management discipline”), 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 “upgrade” 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 “which”. > > > 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 package +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=/nix/store} and @code{--localstatedir=/nix/var}. > > -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’s really a matter of taste.  I think the patch contains a > little of both, but I’d 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’. >