From 2f665d4309053d5a9fe25bc93ee78d55dbc30cb7 Mon Sep 17 00:00:00 2001 From: Xinglu Chen Date: Sun, 7 Nov 2021 12:36:29 +0100 Subject: doc: Improve documentation of the Bash home service MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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: Signed-off-by: Ludovic Courtès --- 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 6d6dfd5177..76290d593e 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -36159,6 +36159,7 @@ Extend home-shell-profile service only if you really know what you do. @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 @@ Available @code{home-bash-configuration} fields are: 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 @@ be read in some cases (if the shell terminates by exec'ing another 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 @@ source ~/.profile "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 @@ if [ -f ~/.bashrc ]; then source ~/.bashrc; fi (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 @@ Install and configure Fish, the friendly interactive shell."))) '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 -- cgit 1.4.1