[bug#72439] [PATCH] doc: Setting Up the Daemon: Add paragraphs whom this section is for.

[bug#72439] [PATCH] doc: Setting Up the Daemon: Add paragraphs whom this section is for.

[Florian Pelz]

* doc/guix.texi (Setting Up the Daemon): Specify intended audience.

Change-Id: I784c5f720aa87bddb6455e42181a1e9de5d7ec9a
---
 doc/guix.texi | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 41814042f5..abd7e2f279 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -860,8 +860,22 @@ Setting Up the Daemon
 @section Setting Up the Daemon
 
 @cindex daemon
+During the installation, the @dfn{build daemon} that must be running
+to use Guix has already been set up and you can run @command{guix}
+commands in your terminal program.  For plain usage, feel free to skip
+this section.  You should continue with the following section,
+@ref{Application Setup}.
+
+However, some of us have reason to replace outdated daemon versions,
+tweak it, perform builds on other machines (@pxref{Daemon Offload
+Setup}) or start it manually in special environments like Chroots
+(@pxref{Chrooting into an existing system}) or WSL (manual start-up is
+not needed, though, for WSL images created with Guix, @pxref{System
+Images, @code{wsl2-image-type}}).  If you want to know more or
+optimize your system, this section is worth reading.
+
 Operations such as building a package or running the garbage collector
-are all performed by a specialized process, the @dfn{build daemon}, on
+are all performed by a specialized process, the build daemon, on
 behalf of clients.  Only the daemon may access the store and its
 associated database.  Thus, any operation that manipulates the store
 goes through the daemon.  For instance, command-line tools such as

base-commit: b20956651a53a8f23828fdeb6945e1a31e6997a8
-- 
2.45.2

[bug#72439] [PATCH v2] doc: Setting Up the Daemon: Give guidance to whom this section is useful.

[Florian Pelz]

* doc/guix.texi (Setting Up the Daemon): Specify intended audience.

Change-Id: I784c5f720aa87bddb6455e42181a1e9de5d7ec9a
---
Changes since v1:
* better commit message
* give command to test daemon
* shortened WSL

 doc/guix.texi | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index b7eb8fd346..201573b5b1 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -860,8 +860,27 @@ Setting Up the Daemon
 @section Setting Up the Daemon
 
 @cindex daemon
+During the installation, the @dfn{build daemon} that must be running
+to use Guix has already been set up and you can run @command{guix}
+commands in your terminal program, @pxref{Getting Started}:
+
+@example
+guix build hello
+@end example
+
+If this works, feel free to skip this section.  You should continue
+with the following section, @ref{Application Setup}.
+
+However, some of us have reason to replace outdated daemon versions,
+tweak it, perform builds on other machines (@pxref{Daemon Offload
+Setup}) or start it manually in special environments like Chroots
+(@pxref{Chrooting into an existing system}) or WSL (not needed for WSL
+images created with Guix, @pxref{System Images,
+@code{wsl2-image-type}}).  If you want to know more or optimize your
+system, this section is worth reading.
+
 Operations such as building a package or running the garbage collector
-are all performed by a specialized process, the @dfn{build daemon}, on
+are all performed by a specialized process, the build daemon, on
 behalf of clients.  Only the daemon may access the store and its
 associated database.  Thus, any operation that manipulates the store
 goes through the daemon.  For instance, command-line tools such as

base-commit: 3c309a7b7020a9645bfe775d9f53f43f05d076bf
-- 
2.45.2

[bug#72439] [PATCH v3] doc: Setting Up the Daemon: Give guidance to whom this section is useful.

[Florian Pelz]

* doc/guix.texi (Setting Up the Daemon): Specify intended audience.

Change-Id: I784c5f720aa87bddb6455e42181a1e9de5d7ec9a
---
Changes since v2:
* reword: If this works -> If this runs through without error

 doc/guix.texi | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index b7eb8fd346..71c9c5c7ff 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -860,8 +860,28 @@ Setting Up the Daemon
 @section Setting Up the Daemon
 
 @cindex daemon
+During the installation, the @dfn{build daemon} that must be running
+to use Guix has already been set up and you can run @command{guix}
+commands in your terminal program, @pxref{Getting Started}:
+
+@example
+guix build hello
+@end example
+
+If this runs through without error, feel free to skip this section.
+You should continue with the following section, @ref{Application
+Setup}.
+
+However, some of us have reason to replace outdated daemon versions,
+tweak it, perform builds on other machines (@pxref{Daemon Offload
+Setup}) or start it manually in special environments like Chroots
+(@pxref{Chrooting into an existing system}) or WSL (not needed for WSL
+images created with Guix, @pxref{System Images,
+@code{wsl2-image-type}}).  If you want to know more or optimize your
+system, this section is worth reading.
+
 Operations such as building a package or running the garbage collector
-are all performed by a specialized process, the @dfn{build daemon}, on
+are all performed by a specialized process, the build daemon, on
 behalf of clients.  Only the daemon may access the store and its
 associated database.  Thus, any operation that manipulates the store
 goes through the daemon.  For instance, command-line tools such as

base-commit: 3c309a7b7020a9645bfe775d9f53f43f05d076bf
-- 
2.45.2

[bug#72439] [PATCH] doc: Setting Up the Daemon: Add paragraphs whom this section is for.

[Vincent Legoll]

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

Hello,

I'd not use "some of us have reason to", maybe something like: "if you want
to"

-- 
Vincent Legoll

[-- Attachment #2: Type: text/html, Size: 331 bytes --]

[bug#72439] [PATCH] doc: Setting Up the Daemon: Add paragraphs whom this section is for.

[pelzflorian (Florian Pelz)]

Thank you for your feedback.

Vincent Legoll <vincent.legoll@gmail.com> writes:
> Hello,
>
> I'd not use "some of us have reason to", maybe something like: "if you want to"

Yes, “some of us have reason to” was unclear.
“if you want to” also says that it is optional.

What I wanted to make clear, though, is that there is a benefit to
reading the section.

Maybe:

diff --git a/doc/guix.texi b/doc/guix.texi
index 71c9c5c7ff..d3e615e02c 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -872,7 +872,8 @@ Setting Up the Daemon
 You should continue with the following section, @ref{Application
 Setup}.
 
-However, some of us have reason to replace outdated daemon versions,
+However, if it applies to you, now would be a good time to
+replace outdated daemon versions,
 tweak it, perform builds on other machines (@pxref{Daemon Offload
 Setup}) or start it manually in special environments like Chroots
 (@pxref{Chrooting into an existing system}) or WSL (not needed for WSL

Regards,
Florian

[bug#72439] [PATCH v4] doc: Setting Up the Daemon: Give guidance to whom this section is useful.

[Florian Pelz]

* doc/guix.texi (Setting Up the Daemon): Specify intended audience.

Change-Id: I784c5f720aa87bddb6455e42181a1e9de5d7ec9a
---
Changes since v3:
* reword: some of us have reason to -> now would be a good time to

 doc/guix.texi | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index b7eb8fd346..6e03d8bbcc 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -860,8 +860,28 @@ Setting Up the Daemon
 @section Setting Up the Daemon
 
 @cindex daemon
+During the installation, the @dfn{build daemon} that must be running
+to use Guix has already been set up and you can run @command{guix}
+commands in your terminal program, @pxref{Getting Started}:
+
+@example
+guix build hello
+@end example
+
+If this runs through without error, feel free to skip this section.
+You should continue with the following section, @ref{Application
+Setup}.
+
+However, now would be a good time to replace outdated daemon versions,
+tweak it, perform builds on other machines (@pxref{Daemon Offload
+Setup}) or start it manually in special environments like Chroots
+(@pxref{Chrooting into an existing system}) or WSL (not needed for WSL
+images created with Guix, @pxref{System Images,
+@code{wsl2-image-type}}).  If you want to know more or optimize your
+system, this section is worth reading.
+
 Operations such as building a package or running the garbage collector
-are all performed by a specialized process, the @dfn{build daemon}, on
+are all performed by a specialized process, the build daemon, on
 behalf of clients.  Only the daemon may access the store and its
 associated database.  Thus, any operation that manipulates the store
 goes through the daemon.  For instance, command-line tools such as

base-commit: 20dbf225f332ccc707578263ed710dcf2a8fb78e
-- 
2.45.2

[bug#72439] [PATCH v4] doc: Setting Up the Daemon: Give guidance to whom this section is useful.

[Vincent Legoll]

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

Hello Florian,

On Fri, Aug 9, 2024 at 9:12 AM Florian Pelz <pelzflorian@pelzflorian.de>
wrote:

> * doc/guix.texi (Setting Up the Daemon): Specify intended audience.
>

LGTM

-- 
Vincent Legoll

[-- Attachment #2: Type: text/html, Size: 621 bytes --]

bug#72439: [PATCH v4] doc: Setting Up the Daemon: Give guidance to whom this section is useful.

[pelzflorian (Florian Pelz)]

Thank you Vincent for reviewing; pushed as
de714bcb46d61922e0efc10783ea23fb0202f583.

Regards,
Florian

[bug#72439] [PATCH] doc: Setting Up the Daemon: Add paragraphs whom this section is for.

[Ludovic Courtès]

Hi Florian,

Florian Pelz <pelzflorian@pelzflorian.de> skribis:

> * doc/guix.texi (Setting Up the Daemon): Specify intended audience.
>
> Change-Id: I784c5f720aa87bddb6455e42181a1e9de5d7ec9a

Good idea.

> +During the installation, the @dfn{build daemon} that must be running

s/the// (I think?)

> +However, some of us have reason to replace outdated daemon versions,
> +tweak it, perform builds on other machines (@pxref{Daemon Offload
> +Setup}) or start it manually in special environments like Chroots

I’d add a comma before “or”, and s/Chroots/``chroots''/

Otherwise LGTM, thanks!

Ludo’.

[bug#72439] [PATCH] doc: Setting Up the Daemon: Add paragraphs whom this section is for.

[pelzflorian (Florian Pelz)]

Hi Ludo.  Ohh sorry, I pushed this already when it had one review and a
week was over.

Ludovic Courtès <ludo@gnu.org> writes:
> Florian Pelz <pelzflorian@pelzflorian.de> skribis:
>
>> * doc/guix.texi (Setting Up the Daemon): Specify intended audience.
>>
>> Change-Id: I784c5f720aa87bddb6455e42181a1e9de5d7ec9a
>
> Good idea.
>
>> +During the installation, the @dfn{build daemon} that must be running
>
> s/the// (I think?)

IMHO a definite article is warranted, because the installation was
described in the previous section.


>> +However, some of us have reason to replace outdated daemon versions,
>> +tweak it, perform builds on other machines (@pxref{Daemon Offload
>> +Setup}) or start it manually in special environments like Chroots
>
> I’d add a comma before “or”,

An Oxford comma is often used and sometimes not in the manual.

Such as

> 22.6 Alternative Setups
> =======================
> 
> Alternative setups than Emacs may let you work on Guix with a similar
> development experience and they might work better with the tools you
> currently use or help you make the transition to Emacs.

or

> 22.8.6 Cyclic Module Dependencies
> ---------------------------------
> […]
>    Care would need to be taken to ensure the above procedure is only
> ever used in a package delayed fields or within another procedure also
> not called at the top level.

We could enforce one unified style, it just is less natural to me.


> and s/Chroots/``chroots''/
>
> Otherwise LGTM, thanks!
>
> Ludo’.


Yes, I will prepare a follow-up patch for chroots.

Regards,
Florian

[bug#72439] [PATCH] doc: Setting Up the Daemon: Add paragraphs whom this section is for.

[pelzflorian (Florian Pelz)]

Hi Ludo, I pushed all three of your reported typos: "the", Oxford comma
and chroots.  Pushed as follow-up commit
91cf240308def2fed3b8649f5e98891171327c78

Ludovic Courtès <ludo@gnu.org> writes:
>> +During the installation, the @dfn{build daemon} that must be running
>
> s/the// (I think?)

Yes, because the reader might visit ``Setting Up the Daemon'' much later
than “the” installation, no definite article is better.

Regards,
Florian