From e09b40e0d0b68ca7c3646ddffb50e1356daec997 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Sun, 5 Mar 2023 02:36:26 +0100
Subject: [PATCH] reword documentation on trusted users and substituters

this is to make it slightly easier to scan over
---
 src/libstore/globals.hh | 14 ++++++--------
 src/nix/daemon.cc       | 30 +++++++++++++++---------------
 2 files changed, 21 insertions(+), 23 deletions(-)

diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh
index 820898350..b0c025c8e 100644
--- a/src/libstore/globals.hh
+++ b/src/libstore/globals.hh
@@ -700,8 +700,8 @@ public:
 
           At least one of the following conditions must be met for Nix to use a substituter:
 
-          - the substituter is in the [`trusted-substituters`](#conf-trusted-substituters) list
-          - the user calling Nix is in the [`trusted-users`](#conf-trusted-users) list
+          - The substituter is in the [`trusted-substituters`](#conf-trusted-substituters) list
+          - The user calling Nix is in the [`trusted-users`](#conf-trusted-users) list
 
           In addition, each store path should be trusted as described in [`trusted-public-keys`](#conf-trusted-public-keys)
         )",
@@ -710,12 +710,10 @@ public:
     Setting<StringSet> trustedSubstituters{
         this, {}, "trusted-substituters",
         R"(
-          A list of [URLs of Nix stores](@docroot@/command-ref/new-cli/nix3-help-stores.md#store-url-format),
-          separated by whitespace. These are
-          not used by default, but can be enabled by users of the Nix daemon
-          by specifying `--option substituters urls` on the command
-          line. Unprivileged users are only allowed to pass a subset of the
-          URLs listed in `substituters` and `trusted-substituters`.
+          A list of [URLs of Nix stores](@docroot@/command-ref/new-cli/nix3-help-stores.md#store-url-format), separated by whitespace.
+          These are not used by default, but can be enabled by users of the Nix daemon by specifying [`substituters`](#conf-substituters).
+
+          Unprivileged users are only allowed to pass as `substituters` only those URLs listed in `trusted-substituters`.
         )",
         {"trusted-binary-caches"}};
 
diff --git a/src/nix/daemon.cc b/src/nix/daemon.cc
index 9fe9b3b1e..09adab5d3 100644
--- a/src/nix/daemon.cc
+++ b/src/nix/daemon.cc
@@ -55,19 +55,16 @@ struct AuthorizationSettings : Config {
     Setting<Strings> trustedUsers{
         this, {"root"}, "trusted-users",
         R"(
-          A list of names of users (separated by whitespace) that have
-          additional rights when connecting to the Nix daemon, such as the
-          ability to specify additional binary caches, or to import unsigned
-          NARs. You can also specify groups by prefixing them with `@`; for
-          instance, `@wheel` means all users in the `wheel` group. The default
-          is `root`.
+          A list of user names, separated by whitespace.
+          These users will have additional rights when connecting to the Nix daemon, such as the ability to specify additional [substituters](#conf-substituters), or to import unsigned [NAR](@docroot@/glossary.md#gloss-nar)s.
+
+          You can also specify groups by prefixing names with `@`.
+          For instance, `@wheel` means all users in the `wheel` group.
 
           > **Warning**
           >
-          > Adding a user to `trusted-users` is essentially equivalent to
-          > giving that user root access to the system. For example, the user
-          > can set `sandbox-paths` and thereby obtain read access to
-          > directories that are otherwise inacessible to them.
+          > Adding a user to `trusted-users` is essentially equivalent to giving that user root access to the system.
+          > For example, the user can set [`sandbox-paths`](#conf-sandbox-paths) and thereby obtain read access to directories that are otherwise inacessible to them.
         )"};
 
     /**
@@ -76,12 +73,15 @@ struct AuthorizationSettings : Config {
     Setting<Strings> allowedUsers{
         this, {"*"}, "allowed-users",
         R"(
-          A list of names of users (separated by whitespace) that are allowed
-          to connect to the Nix daemon. As with the `trusted-users` option,
-          you can specify groups by prefixing them with `@`. Also, you can
-          allow all users by specifying `*`. The default is `*`.
+          A list user names, separated by whitespace.
+          These users are allowed to connect to the Nix daemon.
 
-          Note that trusted users are always allowed to connect.
+          As with the [`trusted-users`](#conf-trusted-users) option, you can specify groups by prefixing names with `@`.
+          Also, you can allow all users by specifying `*`.
+
+          > **Note**
+          >
+          > Trusted users are always allowed to connect to the Nix daemon.
         )"};
 };