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

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

[Nikita Karetnikov]

[-- Attachment #1.1: Type: text/plain, Size: 92 bytes --]

Is it possible to use ’ instead of ' for the apostrophe and keep the
source in ASCII?


[-- Attachment #1.2: 0001-doc-Improve-wording-and-fix-typos-in-Introduction-an.patch --]
[-- Type: text/x-diff, Size: 6164 bytes --]

From 3384e3e2e00d3cbef37b913c9a17df5842522ef8 Mon Sep 17 00:00:00 2001
From: Nikita Karetnikov <nikita@karetnikov.org>
Date: Fri, 24 May 2013 12:02:15 +0000
Subject: [PATCH] doc: Improve wording and fix typos in "Introduction" and
 "Requirements".

* doc/guix.texi (Introduction, Requirements): Rephrase and fix typos.
---
 doc/guix.texi |   66 +++++++++++++++++++++++++++-----------------------------
 1 files changed, 32 insertions(+), 34 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index c3aab81..9a12ff9 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -96,42 +96,39 @@ 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,
-installing packages in user environments, upgrading installed packages
-to new versions or rolling back to a previous set, removing unused
-software packages, etc.
+of all activities that relate to building packages from sources,
+preserving their build-time and run-time dependencies, installing
+packages in user environments, upgrading installed packages to new
+versions or rolling back to a previous set, removing unused software
+packages, etc.
 
 @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
-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
-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.
+The term @dfn{functional} refers to a specific set of package management
+features.  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 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 the same set of inputs.  It cannot alter the
+system's environment in 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 isolated environments (or
+@dfn{chroots}), where only their explicit inputs are visible.
 
 @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
 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
-input yields a different directory name.
+Store}).  Each installed package has its own directory there.  The
+directory name contains a hash of all the inputs used to build that
+package; thus, changing an input yields a different directory name.
 
 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}).
 
-Guix has a command-line interface allowing users to build, install,
+Guix has a command-line interface which allows users to build, install,
 upgrade, and remove packages, as well as a Scheme programming interface.
-The remainder of this manual describes them.
 
 Last but not least, Guix is used to build a distribution of the GNU
 system, with many GNU and non-GNU free software packages.  @xref{GNU
@@ -175,19 +172,20 @@ following packages are also needed:
 @item @url{http://gcc.gnu.org, GCC's g++}
 @end itemize
 
-When a working installation of 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.
+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, Nix replaces the three
+dependencies above.
 
 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.
 
 @node Setting Up the Daemon
 @section Setting Up the Daemon
-- 
1.7.5.4


[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

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

[Ludovic Courtès]

Nikita Karetnikov <nikita@karetnikov.org> skribis:

> Is it possible to use ’ instead of ' for the apostrophe and keep the
> source in ASCII?

There’s a contradiction: ’ is not ASCII.

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.)

> From 3384e3e2e00d3cbef37b913c9a17df5842522ef8 Mon Sep 17 00:00:00 2001
> From: Nikita Karetnikov <nikita@karetnikov.org>
> Date: Fri, 24 May 2013 12:02:15 +0000
> Subject: [PATCH] doc: Improve wording and fix typos in "Introduction" and
>  "Requirements".
>
> * doc/guix.texi (Introduction, Requirements): Rephrase and fix typos.
> ---
>  doc/guix.texi |   66 +++++++++++++++++++++++++++-----------------------------
>  1 files changed, 32 insertions(+), 34 deletions(-)
>
> diff --git a/doc/guix.texi b/doc/guix.texi
> index c3aab81..9a12ff9 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -96,42 +96,39 @@ 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,
> -installing packages in user environments, upgrading installed packages
> -to new versions or rolling back to a previous set, removing unused
> -software packages, etc.
> +of all activities that relate to building packages from sources,
> +preserving their build-time and run-time dependencies, installing
> +packages in user environments, upgrading installed packages to new
> +versions or rolling back to a previous set, removing unused software
> +packages, etc.

There seems to be some paragraph filling at least here.

Could you rearrange the patch to avoid paragraph filling, so that only
the parts that were really changed show up?

Thanks for looking into this!

Ludo’.

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

[Nikita Karetnikov]

[-- Attachment #1.1: Type: text/plain, Size: 587 bytes --]

> 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.

> 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.

> Could you rearrange the patch to avoid paragraph filling, so that only
> the parts that were really changed show up?

Is it OK?


[-- Attachment #1.2: 0001-doc-Improve-wording-and-fix-typos-in-Introduction-an.patch --]
[-- Type: text/x-diff, Size: 5577 bytes --]

From 91df1e8c54d824807a1681b381e76cf25d40538a Mon Sep 17 00:00:00 2001
From: Nikita Karetnikov <nikita@karetnikov.org>
Date: Sat, 25 May 2013 00:04:00 +0000
Subject: [PATCH] doc: Improve wording and fix typos in "Introduction" and
 "Requirements".

* doc/guix.texi (Introduction, Requirements): Rephrase and fix typos.
---
 doc/guix.texi |   50 +++++++++++++++++++++++++-------------------------
 1 files changed, 25 insertions(+), 25 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index cf54fe4..28b8d84 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -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,
 installing packages in user environments, upgrading installed packages
 to new versions or rolling back to a previous set, removing unused
 software packages, etc.
 
 @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.  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
 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
 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.
 
 @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
 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.
 
 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}).
 
-Guix has a command-line interface allowing users to build, install,
+Guix has a command-line interface which allows users to build, install,
 upgrade, and remove packages, as well as a Scheme programming interface.
-The remainder of this manual describes them.
 
 Last but not least, Guix is used to build a distribution of the GNU
 system, with many GNU and non-GNU free software packages.  @xref{GNU
@@ -175,19 +174,20 @@ following packages are also needed:
 @item @url{http://gcc.gnu.org, GCC's g++}
 @end itemize
 
-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.
 
 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.
 
 @node Setting Up the Daemon
 @section Setting Up the Daemon
-- 
1.7.5.4


[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

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

[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’.

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

[Nikita Karetnikov]

[-- Attachment #1: Type: text/plain, Size: 886 bytes --]

> “Consists of” may be OK (any native speaker around, though?).

"Consist in" means "To have the thing mentioned as the only or most
important part." [1]  "Consist of" is usually about several things [2],
AFAICT.

Which one should I use?

> “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?

I meant the same.  Should I keep "honoring"?

> Actually, documentation-wise, my wish would be for people to primarily
> focus on those parts of the manual that are *not* written yet.  :-)

Which parts would you like to see documented before the next release?

[1] https://en.wiktionary.org/wiki/consist_in
[2] http://idioms.thefreedictionary.com/Consist+Of

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

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 <ludo@gnu.org> wrote:

> 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’.
> 

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

[Ludovic Courtès]

Nikita Karetnikov <nikita@karetnikov.org> skribis:

>> “Consists of” may be OK (any native speaker around, though?).
>
> "Consist in" means "To have the thing mentioned as the only or most
> important part." [1]  "Consist of" is usually about several things [2],
> AFAICT.
>
> Which one should I use?

“Consists of” appears to be the correct one (thanks, Alex ;-)).

>> “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?
>
> I meant the same.  Should I keep "honoring"?

I would say so (though again, I’m not a native speaker.)

(Feel free to commit a revised patch that takes into account this
discussion.)

>> Actually, documentation-wise, my wish would be for people to primarily
>> focus on those parts of the manual that are *not* written yet.  :-)
>
> Which parts would you like to see documented before the next release?

The “GNU Distribution” section could be improved.  For instance, the
bits about bootstrapping from the ELS paper could be incorporated
somehow, because I think it’s an interesting topic, and a distinguishing
feature as well.  Also bits about the API, in particular ‘build-system’
objects.

WDYT?

Thanks,
Ludo’.