Re: [PATCH] doc: Clarify and consolidate modify-services documentation.

[Ludovic Courtès]

Chris Marusich <address@hidden> 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 <address@hidden>
> 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,
> address@hidden, for more on that.
> +customize them.  When working with a list of services such as
> address@hidden, 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,
> address@hidden

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
> address@hidden 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
> address@hidden that evaluates to the new service parameters by using the
> address@hidden 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:
> +
> address@hidden
> +(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!"))))))
> address@hidden 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’.