guix-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Matt
Subject: Fix grammar and markup (was Re: Feedback of the GNU Guix manual)
Date: Wed, 10 Apr 2024 16:05:09 +0200
User-agent: Zoho Mail

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: 0001-doc-Fix-grammar-and-markup.patch
Description: Binary data


reply via email to

[Prev in Thread] Current Thread [Next in Thread]