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

* 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.

Fixes: <https://issues.guix.gnu.org/50991>
---
 doc/guix.texi                | 44 ++++++++++++++++++++++++++++++++----
 gnu/home/services/shells.scm | 29 ++++++++++++++++--------
 2 files changed, 59 insertions(+), 14 deletions(-)

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

Hi,

On Fri, Nov 05 2021, Liliana Marie Prikler wrote:

> 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.

That sounds like a good idea!

>> [...]
>>  @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?

I didn’t change the docstrings for ‘home-bash-extension’, only for
‘home-bash-configuration’.

> 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.

Yeah, that sounds a lot more informative than the current docstring.