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

* 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(-)

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

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

Hi,

Am Montag, den 01.11.2021, 14:22 +0100 schrieb Xinglu Chen:
> [...]
> 
> The keys should be strings; the rules for
> ‘home-environment-variable-service-type’ apply here (see “11.3.1
> Essential Home Services”).
You might want to explicitly state that.

> > 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?
You can use whichever makes sense to you, I'm just pointing out that it
ought to be documented.

> > 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”.
Texinfo should support anchors, which can point to arbitrary text.  Of
course one could overdo it by linking each and every field, but imho
having one link for context is better than none.

Thoughts?

Hi,

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

> Hi,
>
> Am Montag, den 01.11.2021, 14:22 +0100 schrieb Xinglu Chen:
>> [...]
>> 
>> The keys should be strings; the rules for
>> ‘home-environment-variable-service-type’ apply here (see “11.3.1
>> Essential Home Services”).
> You might want to explicitly state that.

Yes, good idea.

>> > 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?
> You can use whichever makes sense to you, I'm just pointing out that it
> ought to be documented.
>
>> > 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”.
> Texinfo should support anchors, which can point to arbitrary text.  Of
> course one could overdo it by linking each and every field, but imho
> having one link for context is better than none.

Ah, that would do it.  Thanks for the pointer.

I will send an updated series.