Re: [PATCH] doc: Improve wording and fix typos in "Introduction" and "Requirements".

[Alex Sassmannshausen]

'Consists of' is the correct phrase in this context.

Best wishes, 

Alex 

On sam. 25 mai 2013 15:56:22 CEST, Ludovic Courtès <address@hidden> wrote:

> Nikita Karetnikov <address@hidden> 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 address@hidden'' 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,
> > address@hidden://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
> > address@hidden 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
> > address@hidden 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’.
>