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

[ludo@gnu.org (Ludovic Courtès)]

Nikita Karetnikov <nikita@karetnikov.org> 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’.