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

  • Done
  • quality assurance status badge
Details
3 participants
  • Ludovic Courtès
  • Florian Pelz
  • Vincent Legoll
Owner
unassigned
Submitted by
Florian Pelz
Severity
normal

Debbugs page

Florian Pelz wrote 7 months ago
(address . guix-patches@gnu.org)(name . Florian Pelz)(address . pelzflorian@pelzflorian.de)
16e8cb82047987725668c1b493e4bde392779371.1722671885.git.pelzflorian@pelzflorian.de
* doc/guix.texi (Setting Up the Daemon): Specify intended audience.

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

Toggle diff (32 lines)
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
Florian Pelz wrote 7 months ago
[PATCH v2] doc: Setting Up the Daemon: Give guidance to whom this section is useful.
(address . 72439@debbugs.gnu.org)(name . Florian Pelz)(address . pelzflorian@pelzflorian.de)
acb6a7031dfda7e3e35f489d49ee42a341719295.1722857611.git.pelzflorian@pelzflorian.de
* 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(-)

Toggle diff (37 lines)
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
Florian Pelz wrote 7 months ago
[PATCH v3] doc: Setting Up the Daemon: Give guidance to whom this section is useful.
(address . 72439@debbugs.gnu.org)(name . Florian Pelz)(address . pelzflorian@pelzflorian.de)
59f10c77e60eea466a7cb08fc6510d01d0838b33.1722926720.git.pelzflorian@pelzflorian.de
* 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(-)

Toggle diff (38 lines)
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
Vincent Legoll wrote 7 months ago
[PATCH] doc: Setting Up the Daemon: Add paragraphs whom this section is for.
(address . 72439@debbugs.gnu.org)
CAEwRq=onRF22gYJ--a8qsXjPLsL_Y7=U3V6cRw8XRzN7JcMS7w@mail.gmail.com
Hello,

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

--
Vincent Legoll
Attachment: file
pelzflorian (Florian Pelz) wrote 7 months ago
(name . Vincent Legoll)(address . vincent.legoll@gmail.com)(address . 72439@debbugs.gnu.org)
87frrfgsyj.fsf@pelzflorian.de
Thank you for your feedback.

Vincent Legoll <vincent.legoll@gmail.com> writes:
Toggle quote (4 lines)
> 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:

Toggle diff (17 lines)
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
Florian Pelz wrote 7 months ago
[PATCH v4] doc: Setting Up the Daemon: Give guidance to whom this section is useful.
(address . 72439@debbugs.gnu.org)(name . Florian Pelz)(address . pelzflorian@pelzflorian.de)
e26918b6024fc693700234cc693ef3a519e54a55.1723194511.git.pelzflorian@pelzflorian.de
* 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(-)

Toggle diff (38 lines)
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
Vincent Legoll wrote 7 months ago
(name . Florian Pelz)(address . pelzflorian@pelzflorian.de)
CAEwRq=qR6F-XBc2gdpZbPnry1F1e53F4EOBON38SL6ENvR+O9g@mail.gmail.com
Hello Florian,

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

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

LGTM

--
Vincent Legoll
Attachment: file
pelzflorian (Florian Pelz) wrote 7 months ago
(name . Vincent Legoll)(address . vincent.legoll@gmail.com)
87o760jwmv.fsf@pelzflorian.de
Thank you Vincent for reviewing; pushed as
de714bcb46d61922e0efc10783ea23fb0202f583.

Regards,
Florian
Closed
Ludovic Courtès wrote 7 months ago
Re: [bug#72439] [PATCH] doc: Setting Up the Daemon: Add paragraphs whom this section is for.
(name . Florian Pelz)(address . pelzflorian@pelzflorian.de)
8734n4788z.fsf@gnu.org
Hi Florian,

Florian Pelz <pelzflorian@pelzflorian.de> skribis:

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

Good idea.

Toggle quote (2 lines)
> +During the installation, the @dfn{build daemon} that must be running

s/the// (I think?)

Toggle quote (4 lines)
> +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’.
pelzflorian (Florian Pelz) wrote 7 months ago
(name . Ludovic Courtès)(address . ludo@gnu.org)
878qwwb97a.fsf@pelzflorian.de
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:
Toggle quote (12 lines)
> 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.


Toggle quote (6 lines)
>> +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

Toggle quote (7 lines)
> 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

Toggle quote (7 lines)
> 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.


Toggle quote (7 lines)
> and s/Chroots/``chroots''/
>
> Otherwise LGTM, thanks!
>
> Ludo’.


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

Regards,
Florian
pelzflorian (Florian Pelz) wrote 7 months ago
(name . Ludovic Courtès)(address . ludo@gnu.org)
87wmkgyy96.fsf@pelzflorian.de
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:
Toggle quote (4 lines)
>> +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
Closed
?
Your comment

This issue is archived.

To comment on this conversation send an email to 72439@debbugs.gnu.org

To respond to this issue using the mumi CLI, first switch to it
mumi current 72439
Then, you may apply the latest patchset in this issue (with sign off)
mumi am -- -s
Or, compose a reply to this issue
mumi compose
Or, send patches to this issue
mumi send-email *.patch
You may also tag this issue. See list of standard tags. For example, to set the confirmed and easy tags
mumi command -t +confirmed -t +easy
Or, remove the moreinfo tag and set the help tag
mumi command -t -moreinfo -t +help