[bug#42516] [PATCH] doc: Extend tlp-service-type example.

[bug#42516] [PATCH] doc: Extend tlp-service-type example.

[Tobias Geerinckx-Rice via Guix-patches via]

* doc/guix.texi (Power Management Services): Demonstrate
tlp-configuration usage.

Suggested by rovanion on #guix.
---
 doc/guix.texi | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index fb1c66dcf4..56085865fa 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -23490,17 +23490,17 @@ source is detected.  More information can be found at
 @uref{https://linrunner.de/en/tlp/tlp.html, TLP home page}.
 
 @deffn {Scheme Variable} tlp-service-type
-The service type for the TLP tool.  Its value should be a valid
-TLP configuration (see below).  To use the default settings, simply
-write:
+The service type for the TLP tool.  The default settings are optimised
+for battery life on most systems, but you can tweak them to your heart's
+content by passing a valid @code{tlp-configuration} as its value:
 @lisp
-(service tlp-service-type)
+(service tlp-service-type
+         (tlp-configuration
+          (cpu-scaling-governor-on-ac (list "performance"))
+          (sched-powersave-on-bat? #t)))
 @end lisp
 @end deffn
 
-By default TLP does not need much configuration but most TLP parameters
-can be tweaked using @code{tlp-configuration}.
-
 Each parameter definition is preceded by its type; for example,
 @samp{boolean foo} indicates that the @code{foo} parameter
 should be specified as a boolean.  Types starting with
-- 
2.27.0

[bug#42516] [PATCH] doc: Extend tlp-service-type example.

[Brett Gilio]

Tobias Geerinckx-Rice <me@tobias.gr> writes:

>  @deffn {Scheme Variable} tlp-service-type
> -The service type for the TLP tool.  Its value should be a valid
> -TLP configuration (see below).  To use the default settings, simply
> -write:
> +The service type for the TLP tool.  The default settings are optimised
> +for battery life on most systems, but you can tweak them to your heart's
> +content by passing a valid @code{tlp-configuration} as its value:
>  @lisp
> -(service tlp-service-type)
> +(service tlp-service-type
> +         (tlp-configuration
> +          (cpu-scaling-governor-on-ac (list "performance"))
> +          (sched-powersave-on-bat? #t)))
>  @end lisp
>  @end deffn
>  
> -By default TLP does not need much configuration but most TLP parameters
> -can be tweaked using @code{tlp-configuration}.
> -
>  Each parameter definition is preceded by its type; for example,
>  @samp{boolean foo} indicates that the @code{foo} parameter
>  should be specified as a boolean.  Types starting with

I would replace "as its value:" with "to the service type:", so it reads
"... but you can tweak them to your heart's content by passing a valid
tlp-configuration to the service type:"

Otherwise, it looks great to me!

Brett Gilio

[bug#42516] [PATCH] doc: Extend tlp-service-type example.

[Marius Bakke]

[-- Attachment #1: Type: text/plain, Size: 1557 bytes --]

Brett Gilio <brettg@gnu.org> writes:

> Tobias Geerinckx-Rice <me@tobias.gr> writes:
>
>>  @deffn {Scheme Variable} tlp-service-type
>> -The service type for the TLP tool.  Its value should be a valid
>> -TLP configuration (see below).  To use the default settings, simply
>> -write:
>> +The service type for the TLP tool.  The default settings are optimised
>> +for battery life on most systems, but you can tweak them to your heart's
>> +content by passing a valid @code{tlp-configuration} as its value:
>>  @lisp
>> -(service tlp-service-type)
>> +(service tlp-service-type
>> +         (tlp-configuration
>> +          (cpu-scaling-governor-on-ac (list "performance"))
>> +          (sched-powersave-on-bat? #t)))
>>  @end lisp
>>  @end deffn
>>  
>> -By default TLP does not need much configuration but most TLP parameters
>> -can be tweaked using @code{tlp-configuration}.
>> -
>>  Each parameter definition is preceded by its type; for example,
>>  @samp{boolean foo} indicates that the @code{foo} parameter
>>  should be specified as a boolean.  Types starting with
>
> I would replace "as its value:" with "to the service type:", so it reads
> "... but you can tweak them to your heart's content by passing a valid
> tlp-configuration to the service type:"

Something about "tweak to your heart's content" rubs me the wrong way,
though I can't really explain why.  It feels like the manual is
passive-aggressively mocking me for trying to understand how to
configure the thing.  But that's probably just me.  :-)

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

[bug#42516] [PATCH] doc: Extend tlp-service-type example.

[Tobias Geerinckx-Rice via Guix-patches via]

[-- Attachment #1: Type: text/plain, Size: 1368 bytes --]

Brett,

Brett Gilio 写道：
>> -The service type for the TLP tool.  Its value should be a 
>> valid
>> -TLP configuration (see below).  To use the default settings, 
>> simply
>> -write:
>> +The service type for the TLP tool.  The default settings are 
>> optimised
>> +for battery life on most systems, but you can tweak them to 
>> your heart's
>> +content by passing a valid @code{tlp-configuration} as its 
>> value:

[…]

> I would replace "as its value:" with "to the service type:", so 
> it reads
> "... but you can tweak them to your heart's content by passing a 
> valid
> tlp-configuration to the service type:"

Ding.  You picked up on the same niggle that bugged me — both in 
the original & here.  I thought I'd just stared at it for too 
long.

‘Value’ is a reference to the terminology used in (gnu services). 
‘To the service type’ sounds less accurate.  I find the sentence 
close to clunky is it is; what about a short and sweet:

+The service type for the TLP tool.  The default settings are 
optimised
+for battery life on most systems, but you can tweak them to your 
heart's
+content by adding a valid @code{tlp-configuration}:
            ^^^^^^

Now I've definitely stared at this for too long.  How typical for 
a prose patch :-)

> Otherwise, it looks great to me!

Thanks,

T G-R

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

[bug#42516] [PATCH] doc: Extend tlp-service-type example.

[Tobias Geerinckx-Rice via Guix-patches via]

[-- Attachment #1: Type: text/plain, Size: 93 bytes --]

Marius Bakke 写道：
> passive-aggressively mocking me

Wow.

Kind regards,

T G-R

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

[bug#42516] [PATCH] doc: Extend tlp-service-type example.

[Marius Bakke]

[-- Attachment #1: Type: text/plain, Size: 191 bytes --]

Tobias Geerinckx-Rice <me@tobias.gr> writes:

> Marius Bakke 写道：
>> passive-aggressively mocking me
>
> Wow.

I know, right.  It does not make any sense.  So LGTM rationally...

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

bug#42516: [PATCH] doc: Extend tlp-service-type example.

[Tobias Geerinckx-Rice via Guix-patches via]

[-- Attachment #1: Type: text/plain, Size: 274 bytes --]

Marius Bakke 写道：
> Tobias Geerinckx-Rice <me@tobias.gr> writes:
>> Wow.
>
> I know, right.  It does not make any sense.  So LGTM 
> rationally...

I was so #attacked.  Pushed as 
cdc2e2bba959ec3afa7de6f9a867c862982e079a.

Thank you Brett & Marius!

T G-R

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]