[bug#51543] [PATCH 2/2] doc: Improve documentation of the Bash home service

[Liliana Marie Prikler]

Hi,

Am Freitag, den 05.11.2021, 15:03 +0100 schrieb Xinglu Chen:
> @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.
Regarding this option, you might want to instead provide a sane-
defaults-bash-service or something along those lines instead of using
an extra field.  However, as this field already existed before, this is
not a blocker for this series.



> [...]
>  @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)
> +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
Is there a reason why this documentation stayed more or less the same? 
I see the fields have an updated documentation, but it appears not to
be reflected here.  Or are strings taken from the [1/2] patch?

Either way, since the data types ought to be already known, you should
write something along the lines of "Additional environment variables to
set.  These will be concatenated with the environment variables from
other extensions and the base service to form one coherent block of
environment variables." and so on, focusing on what it does rather than
what it is.

Cheers