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

  • Done
  • quality assurance status badge
Details
3 participants
  • Brett Gilio
  • Marius Bakke
  • Tobias Geerinckx-Rice
Owner
unassigned
Submitted by
Tobias Geerinckx-Rice
Severity
normal
T
T
Tobias Geerinckx-Rice wrote on 24 Jul 2020 12:43
(address . guix-patches@gnu.org)
20200724104307.30992-1-me@tobias.gr
* 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(-)

Toggle diff (31 lines)
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
B
B
Brett Gilio wrote on 25 Jul 2020 00:55
(name . Tobias Geerinckx-Rice)(address . me@tobias.gr)(address . 42516@debbugs.gnu.org)
871rl0frpo.fsf@gnu.org
Tobias Geerinckx-Rice <me@tobias.gr> writes:

Toggle quote (23 lines)
> @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
M
M
Marius Bakke wrote on 25 Jul 2020 19:21
(address . 42516@debbugs.gnu.org)
877durse7t.fsf@gnu.org
Brett Gilio <brettg@gnu.org> writes:

Toggle quote (29 lines)
> 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. :-)
-----BEGIN PGP SIGNATURE-----

iQEzBAEBCgAdFiEEu7At3yzq9qgNHeZDoqBt8qM6VPoFAl8cagYACgkQoqBt8qM6
VPpoQwgA00InE2LcrkZ9rVV7vNxEUP0gucmixBhif84aTBIWaIfB9RdAyNsjpOBd
cSXH6BnEnk9VhqdVKDgltshKf5XIHYrxCdNb78IMoQ2LqCLm7SSrU5+u0beY1/91
3xjmipx8Xvus3AKDc8NzmidM56KKxSRseGolqPUZdH/0dxSg/ZMGJYHDs5lPBiup
FH0aLtv/IiUP2UBdmgKQG+SODJGT83WyAXEzMWlQBYDA3CgI2I14XL8sVHeOdP04
Y0B4tCTuJ3/SfByZf9O0NT9OwU9pAYy5EaZA4j7E1hfwuYv8upXOZ8gf97hiveQ1
a75yrhbovLKHacsoQ5G8AsXoTSTzOQ==
=5nqU
-----END PGP SIGNATURE-----

T
T
Tobias Geerinckx-Rice wrote on 25 Jul 2020 20:45
(name . Brett Gilio)(address . brettg@gnu.org)(address . 42516@debbugs.gnu.org)
87imebe8mg.fsf@nckx
Brett,

Brett Gilio ???
Toggle quote (12 lines)
>> -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:

[…]

Toggle quote (6 lines)
> 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 :-)

Toggle quote (2 lines)
> Otherwise, it looks great to me!

Thanks,

T G-R
-----BEGIN PGP SIGNATURE-----

iHUEARYKAB0WIQT12iAyS4c9C3o4dnINsP+IT1VteQUCXxx91wAKCRANsP+IT1Vt
ecFcAQDR3nj7G+cR0A6w/NWQs86Lx1N/BEAZiYnX0Txg5UdszwD9HdvbEXyq+rPc
+5FKrJWrGwWi2g1xcV7JwwLzNidiOAk=
=MM8l
-----END PGP SIGNATURE-----

T
T
Tobias Geerinckx-Rice wrote on 25 Jul 2020 21:54
(name . Marius Bakke)(address . marius@gnu.org)
87ft9fe5g0.fsf@nckx
Marius Bakke ???
Toggle quote (2 lines)
> passive-aggressively mocking me

Wow.

Kind regards,

T G-R
-----BEGIN PGP SIGNATURE-----

iHUEARYKAB0WIQT12iAyS4c9C3o4dnINsP+IT1VteQUCXxyN7wAKCRANsP+IT1Vt
eTIaAQDRDdFu9kYtJQle1etAXxHUP0EMtIu/CCHJ2N6fM6ZJEwEAtIpy67bQpU3l
/6K9eODHJCfJKQ+NV0XKbUOQ0Z5HTAs=
=d8Yi
-----END PGP SIGNATURE-----

M
M
Marius Bakke wrote on 25 Jul 2020 23:00
(name . Tobias Geerinckx-Rice)(address . me@tobias.gr)
87v9ibqpif.fsf@gnu.org
Tobias Geerinckx-Rice <me@tobias.gr> writes:

Toggle quote (5 lines)
> Marius Bakke ???
>> passive-aggressively mocking me
>
> Wow.

I know, right. It does not make any sense. So LGTM rationally...
-----BEGIN PGP SIGNATURE-----

iQEzBAEBCgAdFiEEu7At3yzq9qgNHeZDoqBt8qM6VPoFAl8cnVgACgkQoqBt8qM6
VPrVAQf/ds5im2t+8OwcsABcDxfEdwpVBDmL69AO6l+1j/7VWLMCGpmhY1WacnCv
ji8wvPyoG1byeunuyKFpDIq9i9eYoX2BylCAbMbgUw4zVfilMm1oti/71okk0uXr
xlYH1NLsZXBZVCBjFq7xAjkclProV7Hv8lqKKjspProqiBLNghluZRtTZYQn/Nro
DhQcvWt1dt0oU5JRhfh8VRvM7190/9ecfIfduskv3pMtofPmFqSCmJgDhPMgWxb+
ionC/ARc9msvJre+qEvACrndhOcbRUgZzORGmAerPV+GUJ8TuzCdYvoIne8wbRnF
HypWh4otR3wSpXB5x8ikz6ETXQetPA==
=YXlg
-----END PGP SIGNATURE-----

T
T
Tobias Geerinckx-Rice wrote on 29 Jul 2020 15:23
(name . Marius Bakke)(address . marius@gnu.org)
87v9i6xxne.fsf@nckx
Marius Bakke ???
Toggle quote (6 lines)
> 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
-----BEGIN PGP SIGNATURE-----

iHUEARYKAB0WIQT12iAyS4c9C3o4dnINsP+IT1VteQUCXyF4ZQAKCRANsP+IT1Vt
eVQZAQDNPHQ4t2nr3sapinkLu+tw/5eaJdLYyViirLfPyUFb4QEAsL0WCX27TIPk
5zCalXtSp2PSTxqpGEVuTOtHX575pw4=
=Exgn
-----END PGP SIGNATURE-----

Closed
?