Fix grammar and markup (was Re: Feedback of the GNU Guix manual)

[Matt <matt@excalamus.com>]

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

We're working through a list of feedback one item at a time:
https://lists.gnu.org/archive/html/guix-devel/2024-01/msg00117.html

We have completed the first two items.

The next item reported is:

#+begin_quote
2.4 Setting up the deamon

Seems like an issue with info.  Have seen this in the Emacs manual as well.  There is also sometimes see see (doc)

L15 See also see Substitutes.
#+end_quote

This sounds like the use of an @xref instead of @ref.  However, I can't find it in the current version (5a95cf76) of the documentation, nor the reported version (ee7c9d25).  The last change to doc/guix.texi at that the reported time was in e5ed1712 (git log -n 1 ee7c9d25 -- doc/guix.texi).

The full reported sentence currently reads,

#+begin_quote
See also @ref{Substitutes}, for information on how to allow the daemon to download pre-built binaries.
#+end_quote

The use of the comma after "Substitutes" is inappropriate, if I have the terminology correct, because "See also Substitutes" is not a participial phrase.  "Also" and "information on" are also unnecessary.  I suggest the following:

#+begin_quote
See @ref{Substitutes} for how to allow the daemon to download pre-built binaries.
#+end_quote

Searching for "see also" turns up the following in 'Mail Services':

#+begin_quote
See also ssl=required setting.
#+end_quote

This needs "the" before "ssl=required" as it refers to a specific setting.  It should probably use the @option or @samp markup:

#+begin_quote
See also the @samp{ssl=required} setting.
#+end_quote

I have opted for @samp because it's used elsewhere for similar items.  In the same section is:

#+begin_quote
NOTE: See also @samp{disable-plaintext-auth} setting.
#+end_quote

This too should have "the" before the setting.  The "NOTE:" designation is also unnecessary.  I suggest:

#+begin_quote
See also the @samp{disable-plaintext-auth} setting.
#+end_quote

Included is a patch which makes these suggested changes.

It was advised to submit the previous patch to guix-patches.  I opted to submit this next patch here to keep the thread connected since it's part of a larger discussion (I suppose).  If we're agreed that guix-patches is more appropriate, I can submit the next item in a new thread there using the same message format I've been following.  Thoughts?

[-- Attachment #2: 0001-doc-Fix-grammar-and-markup.patch --]
[-- Type: application/octet-stream, Size: 1986 bytes --]

From 880264a6887621891a35e637788ddcd63c5bcb54 Mon Sep 17 00:00:00 2001
From: Matthew Trzcinski <matt@excalamus.com>
Date: Wed, 10 Apr 2024 15:44:36 +0200
Subject: [PATCH] doc: Fix grammar and markup

doc/guix.texi (Setting Up the Daemon): Remove comma and extra words.

doc/guix.texi (Mail Services): Add definite article to setting.  Use
@samp markup on setting.
---
 doc/guix.texi | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 5827e0de14..5efbd00984 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -848,8 +848,8 @@ goes through the daemon.  For instance, command-line tools such as
 daemon (@i{via} remote procedure calls) to instruct it what to do.
 
 The following sections explain how to prepare the build daemon's
-environment.  See also @ref{Substitutes}, for information on how to allow
-the daemon to download pre-built binaries.
+environment.  See @ref{Substitutes} for how to allow the daemon to
+download pre-built binaries.
 
 @menu
 * Build Environment Setup::     Preparing the isolated build environment.
@@ -26641,7 +26641,7 @@ Disable LOGIN command and all other plaintext authentications unless
 SSL/TLS is used (LOGINDISABLED capability).  Note that if the remote IP
 matches the local IP (i.e.@: you're connecting from the same computer),
 the connection is considered secure and plaintext authentication is
-allowed.  See also ssl=required setting.
+allowed.  See also the @samp{ssl=required} setting.
 Defaults to @samp{#t}.
 @end deftypevr
 
@@ -26781,7 +26781,7 @@ Defaults to @samp{#f}.
 List of wanted authentication mechanisms.  Supported mechanisms are:
 @samp{plain}, @samp{login}, @samp{digest-md5}, @samp{cram-md5},
 @samp{ntlm}, @samp{rpa}, @samp{apop}, @samp{anonymous}, @samp{gssapi},
-@samp{otp}, @samp{skey}, and @samp{gss-spnego}.  NOTE: See also
+@samp{otp}, @samp{skey}, and @samp{gss-spnego}.  See also the
 @samp{disable-plaintext-auth} setting.
 @end deftypevr
 
-- 
2.41.0