all messages for Guix-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: Xinglu Chen <public@yoctocell.xyz>
To: 51543@debbugs.gnu.org
Cc: Liliana Marie Prikler <liliana.prikler@gmail.com>
Subject: [bug#51543] [PATCH v3 2/2] doc: Improve documentation of the Bash home service
Date: Sun, 07 Nov 2021 12:36:29 +0100	[thread overview]
Message-ID: <8945ebff245fc62c8ba59133e3116b6f68d0aa9c.1636284793.git.public@yoctocell.xyz> (raw)
In-Reply-To: <cover.1636284793.git.public@yoctocell.xyz>

* doc/guix.texi (Shells Home Services): Document ‘home-bash-extension’
  configuration record.
* gnu/home/services/shells.scm (generate-home-bash-documentation): Extract
  docstrings from ‘home-bash-extension’.
  (home-bash-configuration): Expound on docstrings.
  (home-bash-extension): Likewise.

Fixes: <https://issues.guix.gnu.org/50991>
---
 doc/guix.texi                | 50 ++++++++++++++++++++++++++++++++----
 gnu/home/services/shells.scm | 45 ++++++++++++++++++++++----------
 2 files changed, 76 insertions(+), 19 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index f7312a5b30..db1bf6efa7 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -36159,6 +36159,7 @@
 
 @subsubheading Bash Home Service
 
+@anchor{home-bash-configuration}
 @deftp {Data Type} home-bash-configuration
 Available @code{home-bash-configuration} fields are:
 
@@ -36167,15 +36168,20 @@
 The Bash package to use.
 
 @item @code{guix-defaults?} (default: @code{#t}) (type: boolean)
-Add sane defaults like reading @file{/etc/bashrc}, coloring output for
-@code{ls} provided by guix to @file{.bashrc}.
+Add sane defaults like reading @file{/etc/bashrc} and coloring the output of
+@command{ls} to the end of the @file{.bashrc} file.
 
 @item @code{environment-variables} (default: @code{()}) (type: alist)
-Association list of environment variables to set for the Bash session.
+Association list of environment variables to set for the Bash session.  The
+rules for the @code{home-environment-variables-service-type} apply
+here (@pxref{Essential Home Services}).  The contents of this field will be
+added after the contents of the @code{bash-profile} field.
 
 @item @code{aliases} (default: @code{()}) (type: alist)
-Association list of aliases to set for the Bash session.  The alias will
-automatically be quoted, so something line this:
+Association list of aliases to set for the Bash session.  The aliases
+will be defined after the contents of the @code{bashrc} field has been
+put in the @file{.bashrc} file.  The alias will automatically be quoted,
+so something line this:
 
 @lisp
 '((\"ls\" . \"ls -alF\"))
@@ -36206,7 +36212,41 @@
 process for example).
 
 @end table
+@end deftp
+
+You can extend the Bash service by using the @code{home-bash-extension}
+configuration record, whose fields most mirror that of
+@code{home-bash-configuration} (@pxref{home-bash-configuration}).  The
+contents of the extensions will be added to the end of the corresponding
+Bash configuration files (@pxref{Bash Startup Files,,, bash, The GNU
+Bash Reference Manual}.
+
+@deftp {Data Type} home-bash-extension
+Available @code{home-bash-extension} fields are:
+
+@table @asis
+@item @code{environment-variables} (default: @code{()}) (type: alist)
+Additional environment variables to set.  These will be combined with the
+environment variables from other extensions and the base service to form one
+coherent block of environment variables.
+
+@item @code{aliases} (default: @code{()}) (type: alist)
+Additional aliases to set.  These will be combined with the aliases from
+other extensions and the base service.
 
+@item @code{bash-profile} (default: @code{()}) (type: text-config)
+Additional text blocks to add to @file{.bash_profile}, which will be combined
+with text blocks from other extensions and the base service.
+
+@item @code{bashrc} (default: @code{()}) (type: text-config)
+Additional text blocks to add to @file{.bashrc}, which will be combined
+with text blocks from other extensions and the base service.
+
+@item @code{bash-logout} (default: @code{()}) (type: text-config)
+Additional text blocks to add to @file{.bash_logout}, which will be combined
+with text blocks from other extensions and the base service.
+
+@end table
 @end deftp
 
 @subsubheading Zsh Home Service
diff --git a/gnu/home/services/shells.scm b/gnu/home/services/shells.scm
index f24e47f762..81d07da86c 100644
--- a/gnu/home/services/shells.scm
+++ b/gnu/home/services/shells.scm
@@ -323,16 +323,21 @@ (define-configuration home-bash-configuration
    "The Bash package to use.")
   (guix-defaults?
    (boolean #t)
-   "Add sane defaults like reading @file{/etc/bashrc}, coloring output
-for @code{ls} provided by guix to @file{.bashrc}.")
+   "Add sane defaults like reading @file{/etc/bashrc} and coloring the output of
+@command{ls} to the end of the @file{.bashrc} file.")
   (environment-variables
    (alist '())
-   "Association list of environment variables to set for the Bash session."
+   "Association list of environment variables to set for the Bash session.  The
+rules for the @code{home-environment-variables-service-type} apply
+here (@pxref{Essential Home Services}).  The contents of this field will be
+added after the contents of the @code{bash-profile} field."
    serialize-posix-env-vars)
   (aliases
    (alist '())
-   "Association list of aliases to set for the Bash session.  The alias will
-automatically be quoted, so something line this:
+   "Association list of aliases to set for the Bash session.  The aliases will be
+defined after the contents of the @code{bashrc} field has been put in the
+@file{.bashrc} file.  The alias will automatically be quoted, so something line
+this:
 
 @lisp
 '((\"ls\" . \"ls -alF\"))
@@ -450,19 +455,25 @@ (define (add-bash-packages config)
 (define-configuration/no-serialization home-bash-extension
   (environment-variables
    (alist '())
-   "Association list of environment variables to set.")
+   "Additional environment variables to set.  These will be combined with the
+environment variables from other extensions and the base service to form one
+coherent block of environment variables.")
   (aliases
    (alist '())
-   "Association list of aliases to set.")
+   "Additional aliases to set.  These will be combined with the aliases from
+other extensions and the base service.")
   (bash-profile
    (text-config '())
-   "List of file-like objects.")
+   "Additional text blocks to add to @file{.bash_profile}, which will be combined
+with text blocks from other extensions and the base service.")
   (bashrc
    (text-config '())
-   "List of file-like objects.")
+   "Additional text blocks to add to @file{.bashrc}, which will be combined
+with text blocks from other extensions and the base service.")
   (bash-logout
    (text-config '())
-   "List of file-like objects."))
+   "Additional text blocks to add to @file{.bash_logout}, which will be combined
+with text blocks from other extensions and the base service."))
 
 (define (home-bash-extensions original-config extension-configs)
   (match original-config
@@ -646,10 +657,16 @@ (define (generate-home-shell-profile-documentation)
    'home-shell-profile-configuration))
 
 (define (generate-home-bash-documentation)
-  (generate-documentation
-   `((home-bash-configuration
-      ,home-bash-configuration-fields))
-   'home-bash-configuration))
+  (string-append
+   (generate-documentation
+    `((home-bash-configuration
+       ,home-bash-configuration-fields))
+    'home-bash-configuration)
+   "\n\n"
+   (generate-documentation
+    `((home-bash-extension
+       ,home-bash-extension-fields))
+    'home-bash-extension)))
 
 (define (generate-home-zsh-documentation)
   (generate-documentation
-- 
2.33.0







  parent reply	other threads:[~2021-11-07 11:37 UTC|newest]

Thread overview: 18+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-11-01  9:43 [bug#51543] [PATCH 0/2] Some improvements to the Bash home service Xinglu Chen
2021-11-01  9:45 ` [bug#51543] [PATCH 1/2] home: services: bash: Add ‘aliases’ field Xinglu Chen
2021-11-01  9:45 ` [bug#51543] [PATCH 2/2] doc: Document ‘home-bash-extension’ configuration record Xinglu Chen
2021-11-01 10:45   ` Liliana Marie Prikler
2021-11-01 13:22     ` Xinglu Chen
2021-11-01 16:38       ` Liliana Marie Prikler
2021-11-05 11:56         ` Xinglu Chen
2021-11-05 14:03 ` [bug#51543] [PATCH 0/2] Some improvements to the Bash home service Xinglu Chen
2021-11-05 14:03   ` [bug#51543] [PATCH 1/2] home: services: bash: Add ‘aliases’ field Xinglu Chen
2021-11-05 14:03   ` [bug#51543] [PATCH 2/2] doc: Improve documentation of the Bash home service Xinglu Chen
2021-11-05 19:36     ` Liliana Marie Prikler
2021-11-07 11:20       ` Xinglu Chen
2021-11-07 11:36   ` [bug#51543] [PATCH v3 0/2] Some improvements to " Xinglu Chen
2021-11-07 11:36     ` [bug#51543] [PATCH v3 1/2] home: services: bash: Add ‘aliases’ field Xinglu Chen
2021-11-07 11:36     ` Xinglu Chen [this message]
2021-11-07 20:18       ` [bug#51543] [PATCH v3 2/2] doc: Improve documentation of the Bash home service Liliana Marie Prikler
2021-11-07 20:58     ` bug#51543: [PATCH 0/2] Some improvements to " Ludovic Courtès
2021-11-13 20:35     ` [bug#51543] " Ludovic Courtès

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=8945ebff245fc62c8ba59133e3116b6f68d0aa9c.1636284793.git.public@yoctocell.xyz \
    --to=public@yoctocell.xyz \
    --cc=51543@debbugs.gnu.org \
    --cc=liliana.prikler@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/guix.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.