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

[Xinglu Chen]

Hi,

On Mon, Nov 01 2021, Liliana Marie Prikler wrote:

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

Indeed, that sounds better.

>> +@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?

The keys should be strings; the rules for
‘home-environment-variable-service-type’ apply here (see “11.3.1
Essential Home Services”).

> At which point are these fields inserted into which files (e.g. do the
> aliases come before profile or after it)?

Good question!  The contents of ‘aliases’ and ‘bashrc’ are put into
~/.bashrc, in that order.  The contents of ‘bash-profile’ and
‘environment-variables’ are put into ~/.bash_profile, in that order.
This doesn’t seem that consistent, is there any preference to what order
should be used?

> 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?)

I don’t think there is a way to link to ‘home-bash-configuration’ using
Texinfo; one can only link to “Shells Home Services”.

signature.asc
Description: PGP signature