[bug#47404] [PATCH 0/2] doc: Minor improvements

[bug#47404] [PATCH 0/2] doc: Minor improvements

[zimoun]

Hi,

The first patch is about keeping consistency with the previous Channels
reordering.

   <http://issues.guix.gnu.org/43482>


The second patch removes all the backtick substitutions by $() in shell
commands.  The POSIX is $() as explained:

<https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_03>
<https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xcu_chap02.html#tag_23_02_06_03>

This changed had already been discussed but I am not able to find where.
Well, at least it is mentioned here [1]:

        I propose to do a pass on that:
         - apply this rule: no-$ for only input and $ to distinguish between
        inputs and outputs.
         - backtick ` replaced by $(...) as discussed elsewhere
        and then send a "Fix typo" patch.  And maybe add a bullet in the
        Contributing Section.

i.e, the patch address the second point.

1: <https://yhetil.org/guix/CAJ3okZ3WfjR3tbgQX-B_WvihZFazvR7AfNquYYXE6+Hp5nOBzw@mail.gmail.com>


Cheers,
simon

zimoun (2):
  doc: Reorder "Channels with Substitutes".
  doc: Fix typos.

 doc/guix.texi | 84 +++++++++++++++++++++++++--------------------------
 1 file changed, 42 insertions(+), 42 deletions(-)


base-commit: 6e7ba45357078b31a369b23f8a9f38302dfcbb10
-- 
2.29.2

[bug#47404] [PATCH 1/2] doc: Reorder "Channels with Substitutes".

[zimoun]

Ordering consistency introduced by 12871cc8db701a89f7f64303e1f16a8537a12561.

* doc/guix.texi (Channels): Move section "Channels with Substitutes".
Update the master menu.
---
 doc/guix.texi | 54 +++++++++++++++++++++++++--------------------------
 1 file changed, 27 insertions(+), 27 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index c23d044ff5..3bc8d029d9 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -240,13 +240,13 @@ Channels
 * Using a Custom Guix Channel::  Using a customized Guix.
 * Replicating Guix::            Running the @emph{exact same} Guix.
 * Channel Authentication::      How Guix verifies what it fetches.
+* Channels with Substitutes::   Using channels with available substitutes.
 * Creating a Channel::          How to write your custom channel.
 * Package Modules in a Sub-directory::  Specifying the channel's package modules location.
 * Declaring Channel Dependencies::  How to depend on other channels.
 * Specifying Channel Authorizations::  Defining channel authors authorizations.
 * Primary URL::                 Distinguishing mirror to original.
 * Writing Channel News::        Communicating information to channel's users.
-* Channels with Substitutes::   Using channels with available substitutes.
 
 Development
 
@@ -5007,13 +5007,13 @@ updates.
 * Using a Custom Guix Channel::  Using a customized Guix.
 * Replicating Guix::            Running the @emph{exact same} Guix.
 * Channel Authentication::      How Guix verifies what it fetches.
+* Channels with Substitutes::   Using channels with available substitutes.
 * Creating a Channel::          How to write your custom channel.
 * Package Modules in a Sub-directory::  Specifying the channel's package modules location.
 * Declaring Channel Dependencies::  How to depend on other channels.
 * Specifying Channel Authorizations::  Defining channel authors authorizations.
 * Primary URL::                 Distinguishing mirror to original.
 * Writing Channel News::        Communicating information to channel's users.
-* Channels with Substitutes::   Using channels with available substitutes.
 @end menu
 
 @node Specifying Additional Channels
@@ -5169,6 +5169,31 @@ introduction from a trusted source since that is the root of your trust.
 
 If you're curious about the authentication mechanics, read on!
 
+@node Channels with Substitutes
+@section Channels with Substitutes
+
+When running @command{guix pull}, Guix will first compile the
+definitions of every available package.  This is an expensive operation
+for which substitutes (@pxref{Substitutes}) may be available.  The
+following snippet in @file{channels.scm} will ensure that @command{guix
+pull} uses the latest commit with available substitutes for the package
+definitions: this is done by querying the continuous integration
+server at @url{https://ci.guix.gnu.org}.
+
+@lisp
+(use-modules (guix ci))
+
+(list (channel-with-substitutes-available
+       %default-guix-channel
+       "https://ci.guix.gnu.org"))
+@end lisp
+
+Note that this does not mean that all the packages that you will
+install after running @command{guix pull} will have available
+substitutes.  It only ensures that @command{guix pull} will not try to
+compile package definitions.  This is particularly useful when using
+machines with limited resources.
+
 @node Creating a Channel
 @section Creating a Channel
 
@@ -5485,31 +5510,6 @@ xgettext -o news.po -l scheme -ken etc/news.txt
 To sum up, yes, you could use your channel as a blog.  But beware, this
 is @emph{not quite} what your users might expect.
 
-@node Channels with Substitutes
-@section Channels with Substitutes
-
-When running @command{guix pull}, Guix will first compile the
-definitions of every available package.  This is an expensive operation
-for which substitutes (@pxref{Substitutes}) may be available.  The
-following snippet in @file{channels.scm} will ensure that @command{guix
-pull} uses the latest commit with available substitutes for the package
-definitions: this is done by querying the continuous integration
-server at @url{https://ci.guix.gnu.org}.
-
-@lisp
-(use-modules (guix ci))
-
-(list (channel-with-substitutes-available
-       %default-guix-channel
-       "https://ci.guix.gnu.org"))
-@end lisp
-
-Note that this does not mean that all the packages that you will
-install after running @command{guix pull} will have available
-substitutes.  It only ensures that @command{guix pull} will not try to
-compile package definitions.  This is particularly useful when using
-machines with limited resources.
-
 @c *********************************************************************
 @node Development
 @chapter Development
-- 
2.29.2

[bug#47404] [PATCH 2/2] doc: Fix typos.

[zimoun]

* doc/guix.texi: Replace shell substitution (`) by $().
---
 doc/guix.texi | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 3bc8d029d9..eb4f711cf9 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -1043,10 +1043,10 @@ Bash syntax and the @code{shadow} commands):
 @c for why `-G' is needed.
 @example
 # groupadd --system guixbuild
-# for i in `seq -w 1 10`;
+# for i in $(seq -w 1 10);
   do
     useradd -g guixbuild -G guixbuild           \
-            -d /var/empty -s `which nologin`    \
+            -d /var/empty -s $(which nologin)   \
             -c "Guix build user $i" --system    \
             guixbuilder$i;
   done
@@ -4211,7 +4211,7 @@ Return the derivation(s) leading to the given store items
 For example, this command:
 
 @example
-guix gc --derivers `guix package -I ^emacs$ | cut -f4`
+guix gc --derivers $(guix package -I ^emacs$ | cut -f4)
 @end example
 
 @noindent
@@ -10120,7 +10120,7 @@ Similarly, the following command builds all the available packages:
 
 @example
 guix build --quiet --keep-going \
-  `guix package -A | cut -f1,2 --output-delimiter=@@`
+  $(guix package -A | cut -f1,2 --output-delimiter=@@)
 @end example
 
 @var{package-or-derivation} may be either the name of a package found in
@@ -10825,8 +10825,8 @@ This works regardless of how packages or derivations are specified.  For
 instance, the following invocations are equivalent:
 
 @example
-guix build --log-file `guix build -d guile`
-guix build --log-file `guix build guile`
+guix build --log-file $(guix build -d guile)
+guix build --log-file $(guix build guile)
 guix build --log-file guile
 guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
 @end example
@@ -12334,7 +12334,7 @@ For this type of graph, it is also possible to pass a @file{.drv} file
 name instead of a package name, as in:
 
 @example
-guix graph -t derivation `guix system build -d my-config.scm`
+guix graph -t derivation $(guix system build -d my-config.scm)
 @end example
 
 @item module
@@ -12363,7 +12363,7 @@ example, the command below produces the reference graph of your profile
 (which can be big!):
 
 @example
-guix graph -t references `readlink -f ~/.guix-profile`
+guix graph -t references $(readlink -f ~/.guix-profile)
 @end example
 
 @item referrers
@@ -12935,7 +12935,7 @@ their dependencies over to @var{host}, logged in as @var{user}:
 
 @example
 guix copy --to=@var{user}@@@var{host} \
-          coreutils `readlink -f ~/.guix-profile`
+          coreutils $(readlink -f ~/.guix-profile)
 @end example
 
 If some of the items to be copied are already present on @var{host},
@@ -32897,8 +32897,8 @@ system configuration file.  You can then load the image and launch a
 Docker container using commands like the following:
 
 @example
-image_id="`docker load < guix-system-docker-image.tar.gz`"
-container_id="`docker create $image_id`"
+image_id="$(docker load < guix-system-docker-image.tar.gz)"
+container_id="$(docker create $image_id)"
 docker start $container_id
 @end example
 
@@ -33422,7 +33422,7 @@ The default @command{run-vm.sh} script that is returned by an invocation of
 @command{guix system vm} does not add a @command{-nic user} flag by default.
 To get network access from within the vm add the @code{(dhcp-client-service)}
 to your system definition and start the VM using
-@command{`guix system vm config.scm` -nic user}.  An important caveat of using
+@command{$(guix system vm config.scm) -nic user}.  An important caveat of using
 @command{-nic user} for networking is that @command{ping} will not work, because
 it uses the ICMP protocol.  You'll have to use a different command to check for
 network connectivity, for example @command{guix download}.
@@ -33437,7 +33437,7 @@ To enable SSH inside a VM you need to add an SSH server like
 22 by default, to the host.  You can do this with
 
 @example
-`guix system vm config.scm` -nic user,model=virtio-net-pci,hostfwd=tcp::10022-:22
+$(guix system vm config.scm) -nic user,model=virtio-net-pci,hostfwd=tcp::10022-:22
 @end example
 
 To connect to the VM you can run
@@ -34491,7 +34491,7 @@ To verify which Bash your whole profile refers to, you can run
 (@pxref{Invoking guix gc}):
 
 @example
-guix gc -R `readlink -f ~/.guix-profile` | grep bash
+guix gc -R $(readlink -f ~/.guix-profile) | grep bash
 @end example
 
 @noindent
@@ -34499,7 +34499,7 @@ guix gc -R `readlink -f ~/.guix-profile` | grep bash
 Likewise for a complete Guix system generation:
 
 @example
-guix gc -R `guix system build my-config.scm` | grep bash
+guix gc -R $(guix system build my-config.scm) | grep bash
 @end example
 
 Lastly, to check which Bash running processes are using, you can use the
-- 
2.29.2

[bug#47404] [PATCH 2/2] doc: Fix typos.

[Christopher Baines]

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


zimoun <zimon.toutoune@gmail.com> writes:

> * doc/guix.texi: Replace shell substitution (`) by $().
> ---
>  doc/guix.texi | 30 +++++++++++++++---------------
>  1 file changed, 15 insertions(+), 15 deletions(-)

This seems reasonable, but the commit message should include why the
change is being made, so what's the motivation?

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 987 bytes --]

bug#47404: [PATCH 1/2] doc: Reorder "Channels with Substitutes".

[Mathieu Othacehe]

Hello zimoun,

> * doc/guix.texi: Replace shell substitution (`) by $().

I edited this commit message and pushed.

Thanks,

Mathieu