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

[Chris Marusich <cmmarusich@gmail.com>]

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


Here's an updated patch.  First off, I added my name to the copyright
list for each file I modified.  Please let me know if I should refrain
from doing this, since the contribution is small.

ludo@gnu.org (Ludovic Courtès) writes:

> 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.  ;-)

OK - I think I've used double spaces everywhere, this time.

> I prefer to put “e.g.” things between em dashes instead of parentheses,
> but have no reference supporting this choice, so…  your call!

I've changed this to match the style currently used in the manual.

> I think this should be enough:
>
>   ;; @dots{}

I agree.

> 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
>
> ?

I think that example with more context will better clarify how to use
the macro, so I'm inclined not to shorten that part.  To make sure, I
will check how the PDF looks once after texlive finishes downloading.
It seems I need that in order to run texi2pdf.  It'll take a little
time.

> 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?

I decided to move the example back into the operating system
configuration section, since that seems to be where the examples should
go.  New users will be looking there to learn how to write their
operating-system declarations, so it makes sense to put the example
there.  If they want more information, they can follow the link to the
detailed description of modify-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").

Thank you for pointing this out.  It makes sense.  I've shortened the
docstring accordingly.

> Thanks a lot for your feedback!  It’s good to have a fresh eye on this
> and quality suggestions to improve it!

I'm glad to help!

Chris


[-- Attachment #2: 0001-doc-Clarify-and-consolidate-modify-services-document.patch --]
[-- Type: text/x-patch, Size: 8679 bytes --]

From 891e944dc522cdc250058e92d9150d6a6a39242f Mon Sep 17 00:00:00 2001
From: Chris Marusich <cmmarusich@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.
---
 doc/guix.texi    | 79 ++++++++++++++++++++++++++++++++++----------------------
 gnu/services.scm | 39 +++++++++++-----------------
 2 files changed, 63 insertions(+), 55 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 082fe5a..701a946 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -18,6 +18,7 @@ Copyright @copyright{} 2014 Pierre-Antoine Rault@*
 Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
 Copyright @copyright{} 2015, 2016 Leo Famulari
 Copyright @copyright{} 2016 Ben Woodcroft
+Copyright @copyright{} 2016 Chris Marusich
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -6044,28 +6045,38 @@ generated as needed (@pxref{Defining Services}).
 @cindex customization, of services
 @findex modify-services
 Occasionally, instead of using the base services as is, you will want to
-customize them.  For instance, to change the configuration of
-@code{guix-daemon} and Mingetty (the console log-in), you may write the
-following instead of @var{%base-services}:
+customize them.  To do this, use @code{modify-services} (@pxref{Service
+Reference, @code{modify-services}}) to modify the list.
+
+For example, suppose you want to modify @code{guix-daemon} and Mingetty
+(the console log-in) in the @var{%base-services} list (@pxref{Base
+Services, @code{%base-services}).  To do that, you could write the
+following in your operating system declaration:
 
 @lisp
-(modify-services %base-services
-  (guix-service-type config =>
-                     (guix-configuration
-                      (inherit config)
-                      (use-substitutes? #f)
-                      (extra-options '("--gc-keep-outputs"))))
-  (mingetty-service-type config =>
-                         (mingetty-configuration
-                          (inherit config)
-                          (motd (plain-file "motd" "Hi there!")))))
+(operating-system
+  ;; @dots{}
+  (services (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!"))))))
 @end lisp
 
-@noindent
-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.
+This changes the configuration---i.e., the service parameters---of the
+@code{guix-service-type} instance, and that of all the
+@code{mingetty-service-type} instances in the @var{%base-services} list.
+Observe how this is accomplished: first, we arrange for the original
+configuration to be bound to the identifier @code{config} in the
+@var{body}, and then we write the @var{body} so that it evaluates to the
+desired configuration.  In particular, notice how we use @code{inherit}
+to create a new configuration which has the same values as the old
+configuration, but with a few modifications.
 
 The configuration for a typical ``desktop'' usage, with the X11 display
 server, a desktop environment, network management, power management, and
@@ -9916,11 +9927,12 @@ Here is an example of how a service is created and manipulated:
 
 The @code{modify-services} form provides a handy way to change the
 parameters of some of the services of a list such as
-@var{%base-services} (@pxref{Base Services, @code{%base-services}}).  Of
-course, you could always use standard list combinators such as
-@code{map} and @code{fold} to do that (@pxref{SRFI-1, List Library,,
-guile, GNU Guile Reference Manual}); @code{modify-services} simply
-provides a more concise form for this common pattern.
+@var{%base-services} (@pxref{Base Services, @code{%base-services}}).  It
+evalutes to a list of services.  Of course, you could always use
+standard list combinators such as @code{map} and @code{fold} to do that
+(@pxref{SRFI-1, List Library,, guile, GNU Guile Reference Manual});
+@code{modify-services} simply provides a more concise form for this
+common pattern.
 
 @deffn {Scheme Syntax} modify-services @var{services} @
   (@var{type} @var{variable} => @var{body}) @dots{}
@@ -9932,16 +9944,21 @@ clauses.  Each clause has the form:
 (@var{type} @var{variable} => @var{body})
 @end example
 
-where @var{type} is a service type, such as @var{guix-service-type}, and
-@var{variable} is an identifier that is bound within @var{body} to the
-value of the service of that @var{type}.  @xref{Using the Configuration
-System}, for an example.
+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}.
 
-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.
+
+@xref{Using the Configuration System} for example usage.
 
-@example
-(map (lambda (service) @dots{}) @var{services})
-@end example
 @end deffn
 
 Next comes the programming interface for service types.  This is
diff --git a/gnu/services.scm b/gnu/services.scm
index ffba418..59ce763 100644
--- a/gnu/services.scm
+++ b/gnu/services.scm
@@ -1,5 +1,6 @@
 ;;; GNU Guix --- Functional package management for GNU
 ;;; Copyright © 2015, 2016 Ludovic Courtès <ludo@gnu.org>
+;;; Copyright © 2016 Chris Marusich <cmmarusich@gmail.com>
 ;;;
 ;;; This file is part of GNU Guix.
 ;;;
@@ -153,30 +154,20 @@
 
 (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)."
+    "Modify the services in the SERVICES list according to the given
+clauses.  This form evaluates to a list of services.  Each clause has
+the form:
+
+(TYPE VARIABLE => BODY)
+
+where TYPE is a service type---e.g., 'guix-service-type'---and
+VARIABLE is an identifier that is bound within the BODY to the service
+parameters---e.g., a 'guix-configuration' instance---of the original
+service of that TYPE.
+
+The 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."
     ((_ services clauses ...)
      (map (lambda (service)
             (%modify-service service clauses ...))
-- 
2.6.3