[bug#51543] [PATCH 2/2] doc: Document ‘home-bash-extension’ configuration record.

[Liliana Marie Prikler]

Hi,

Am Montag, den 01.11.2021, 10:45 +0100 schrieb Xinglu Chen:
> * 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’.
> 
> Fixes: <https://issues.guix.gnu.org/50991>
> ---
>  doc/guix.texi                | 24 ++++++++++++++++++++++++
>  gnu/home/services/shells.scm | 14 ++++++++++----
>  2 files changed, 34 insertions(+), 4 deletions(-)
> 
> diff --git a/doc/guix.texi b/doc/guix.texi
> index f7312a5b30..a3b440f5c9 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -36206,7 +36206,31 @@
>  process for example).
>  
>  @end table
> +@end deftp
> +
> +To extend the Bash service, one has to use a @code{home-bash-
> extension},
> +which contains mostly the same fields as @code{home-bash-
> configuration}.
This sounds like you're forcing people to extend their services.  Write
it "You can extend the bash service by using home-bash-extension, whose
fields mostly mirror that of home-bash-service".

> +@deftp {Data Type} home-bash-extension
> +Available @code{home-bash-extension} fields are:
> +
> +@table @asis
> +@item @code{environment-variables} (default: @code{()}) (type:
> alist)
> +Association list of environment variables to set.
> +
> +@item @code{aliases} (default: @code{()}) (type: alist)
> +Association list of aliases to set.
>  
> +@item @code{bash-profile} (default: @code{()}) (type: text-config)
> +List of file-like objects.
> +
> +@item @code{bashrc} (default: @code{()}) (type: text-config)
> +List of file-like objects.
> +
> +@item @code{bash-logout} (default: @code{()}) (type: text-config)
> +List of file-like objects.
> +
> +@end table
>  @end deftp
This documentation is a little sparse, don't you agree?  Are the keys
to environment-variables strings or symbols?  At which point are these
fields inserted into which files (e.g. do the aliases come before
profile or after it)?

If some field is already described as part of home-bash-service, you
might also want to link back to it, but you should still state where
the extension occurs.  Is new code added to the front or to the back
for instance.  (On that note, is the text-config type well-documented?)

Regards,
Liliana