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

[Xinglu Chen]

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.

signature.asc
Description: PGP signature