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

[Matt <matt@excalamus.com>]

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

 ---- On Fri, 12 Apr 2024 22:16:39 +0200  Ludovic Courtès  wrote --- 

 > > See @ref{Substitutes} for how to allow the daemon to download pre-built binaries.
 > 
 > Nitpick: this works but I believe the recommended approach is
 > “@xref{Substitutes} for how…”.
 > 
 >   https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Cross-Reference-Commands.html
 
Good catch!  I took the opportunity and found several similar issues elsewhere.  The attached patch tries to correct them.

 > Thanks for reporting these issues!

I appreciate your assistance with these details :)

[-- Attachment #2: 0001-doc-Fix-cross-references.patch --]
[-- Type: application/octet-stream, Size: 3111 bytes --]

From bc8d3654f8c1d3271596d0eafb48b02421236e1c Mon Sep 17 00:00:00 2001
From: Matthew Trzcinski <matt@excalamus.com>
Date: Sat, 13 Apr 2024 10:12:05 +0200
Subject: [PATCH] doc: Fix cross-references

* doc/guix.texi (Setting Up the Daemon): use @xref to start sentence.
(Build Systems): capitalize "python" and start parenthesized reference with
@pxref.
(Linux Services): use @xref to start phrase.
(Configuring the Shell): use @xref to start phrase.
---
 doc/guix.texi | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 5efbd00984..b117a2d03c 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 @ref{Substitutes} for how to allow the daemon to
-download pre-built binaries.
+environment.  @xref{Substitutes} for how to allow the daemon to download
+pre-built binaries.
 
 @menu
 * Build Environment Setup::     Preparing the isolated build environment.
@@ -9086,7 +9086,7 @@ package name should be prefixed with the lisp implementation, such as
 @code{sbcl-} for @code{asdf-build-system/sbcl}.
 
 Additionally, the corresponding source package should be labeled using
-the same convention as python packages (see @ref{Python Modules}), using
+the same convention as Python packages (@pxref{Python Modules}), using
 the @code{cl-} prefix.
 
 In order to create executable programs and images, the build-side
@@ -39603,9 +39603,9 @@ The package providing the @command{fstrim} command.
 
 @item @code{schedule} (default: @code{"0 0 * * 0"}) (type: mcron-time)
 Schedule for launching @command{fstrim}.  This can be a procedure, a
-list or a string.  For additional information, see @ref{Guile
-Syntax,,Job specification,mcron,the mcron manual}.  By default this is
-set to run weekly on Sunday at 00:00.
+list or a string.  For additional information, @xref{Guile Syntax,,Job
+specification,mcron,the mcron manual}.  By default this is set to run
+weekly on Sunday at 00:00.
 
 @item @code{listed-in} (default: @code{'("/etc/fstab" "/proc/self/mountinfo")}) (type: maybe-list-of-strings)
 List of files in fstab or kernel mountinfo format.  All missing or empty
@@ -44229,9 +44229,9 @@ Guix Home.  Otherwise, read it carefully.
 There are a few scripts that must be evaluated by a login shell to
 activate the home environment.  The shell startup files only read by
 login shells often have @code{profile} suffix.  For more information
-about login shells see @ref{Invoking Bash,,, bash, The GNU Bash
-Reference Manual} and see @ref{Bash Startup Files,,, bash, The GNU Bash
-Reference Manual}.
+about login shells, @xref{Invoking Bash,,, bash, The GNU Bash Reference
+Manual} and @xref{Bash Startup Files,,, bash, The GNU Bash Reference
+Manual}.
 
 The first script that needs to be sourced is @file{setup-environment},
 which sets all the necessary environment variables (including variables
-- 
2.41.0