Chris Marusich <cmmarus...@gmail.com> skribis:
> In particular, I found that the current recommended way to modify a
> service (i.e., using 'modify-services') relies on the 'inherit' feature
> of records that are created via the macros that 'define-record-type*'
> produces. This is documented just fine in the (guix records) module, but
> it is not documented in the manual. I wasn't sure where the right place
> would be to put an explanation of 'define-record-type*', so I mentioned
> it without providing a comprehensive explanation. I am content to supply
> a reasonable explanation of why the magic word "inherit" is used when
> invoking 'modify-services', even if it does not fully explain what
> 'define-record-type*' is.
Agreed, that’s good enough for now.
Eventually we could add a “Records” section under “Programming
Interface” that would explain the features of records created by
‘define-record-type*’, and optionally ‘define-record-type*’ itself.
> From 10518b419c2f9322082c3f6d2a2c7535f7645f3d Mon Sep 17 00:00:00 2001
> From: Chris Marusich <cmmarus...@gmail.com>
> Date: Mon, 7 Mar 2016 01:55:07 -0800
> Subject: [PATCH] doc: Clarify and consolidate modify-services documentation.
>
> * doc/guix.texi ("Using the Configuration System": Move the example...
> * doc/guix.texi ("Service Reference"): ...to here, and clarify more.
> * gnu/services.scm (modify-services): Update docstring to match.
One general remark: please always leave two spaces after an
end-of-sentence period (info "(texinfo) Ending a Sentence"). As Andy
put it, we’re part of that two-space tribe. ;-)
> -The effect here is to change the options passed to @command{guix-daemon}
> -when it is started, as well as the ``message of the day'' that appears
> -when logging in at the console. @xref{Service Reference,
> -@code{modify-services}}, for more on that.
> +customize them. When working with a list of services such as
> +@var{%desktop-services}, you can use any of the standard list
> +combinators such as @code{map} and @code{fold} to manipulate the list
> +(@pxref{SRFI-1, List Library,, guile, GNU Guile Reference
> +Manual}). However, there is an easier way: use @code{modify-services} to
> +modify the list. For detailed instructions on how to do that, including
> +a concrete example, see: @xref{Service Reference,
> +@code{modify-services}}.
This should be:
a concrete example, @pxref{Service Reference, @code{modify-services}}.
(The “see” is automatically added.)
> +where @var{type} is a service type (e.g., @code{guix-service-type}), and
> +@var{variable} is an identifier that is bound within the @var{body} to
> +the service parameters (e.g., a @code{guix-configuration} instance) of
> +the original service of that @var{type}.
I prefer to put “e.g.” things between em dashes instead of parentheses,
but have no reference supporting this choice, so… your call!
> -This is a shorthand for:
> +The @var{body} should evaluate to the new service parameters, which will
> +be used to configure the new service. This new service will replace the
> +original in the resulting list. Because a service's service parameters
> +are created using @code{define-record-type*}, you can write a succint
> +@var{body} that evaluates to the new service parameters by using the
> +@code{inherit} feature that @code{define-record-type*} provides.
> +
> +For the purpose of illustration, let us assume you want to modify the
> +default @var{%desktop-services} (@xref{Desktop Services}, for details)
> +in your operating system configuration file. To accomplish that, you
> +could write something like the following:
> +
> +@lisp
> +(operating-system
> + ;; Other configuration which precedes the "services" section
> + ;; has been omitted here for brevity.
I think this should be enough:
;; @dots{}
> + (services (modify-services %desktop-services
> + (guix-service-type config =>
> + (guix-configuration
> + (inherit config)
> + (use-substitutes? #f)
> + (extra-options
> '("--gc-keep-derivations"))))
> + (mingetty-service-type config =>
> + (mingetty-configuration
> + (inherit config)
> + (motd (plain-file "motd" "Hi
> there!"))))))
> +@end lisp
These lines may be too longer for the PDF output. What about making it:
@lisp
(define %my-services
(modify-services …))
(operating-system
;; @dots{}
(services %my-services))
@end lisp
?
Also I wonder if we should move this illustration (starting from “For
the purpose of illustration”) right above the @deffn, in part because it
deals with the general context rather than just ‘modify-services’, and
also because it everything within @deffn is indented.
WDYT?
> (define-syntax modify-services
> (syntax-rules ()
> - "Modify the services listed in SERVICES according to CLAUSES. Each
> clause
> -must have the form:
> -
> - (TYPE VARIABLE => BODY)
> -
> -where TYPE is a service type, such as 'guix-service-type', and VARIABLE is an
> -identifier that is bound within BODY to the value of the service of that
> -TYPE. Consider this example:
> -
> - (modify-services %base-services
> - (guix-service-type config =>
> - (guix-configuration
> - (inherit config)
> - (use-substitutes? #f)
> - (extra-options '(\"--gc-keep-derivations\"))))
> - (mingetty-service-type config =>
> - (mingetty-configuration
> - (inherit config)
> - (motd (plain-file \"motd\" \"Hi there!\")))))
> -
> -It changes the configuration of the GUIX-SERVICE-TYPE instance, and that of
> -all the MINGETTY-SERVICE-TYPE instances.
> -
> -This is a shorthand for (map (lambda (svc) ...) %base-services)."
I think I would keep the docstring unchanged because this one is more
concise, which I think is important for a docstring.
It’s OK to if the manual is more verbose on this topic (info
"(standards) Doc Strings and Manuals").
Could you send an updated patch?
Thanks a lot for your feedback! It’s good to have a fresh eye on this
and quality suggestions to improve it!
Ludo’.
