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

[Christian Miller <christian.miller@mail.dadoes.de>]

Hello,

I just want to mention that I am still in CC and my mail server is going 
offline. Need to optimize my budget and don't have any time for GNU 
anymore because of university.

--

Christian Miller

Am 10/04/2024 um 16:05 schrieb Matt:
> 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?