From mboxrd@z Thu Jan 1 00:00:00 1970 From: Chris Marusich Subject: Re: [PATCH] doc: Clarify and consolidate modify-services documentation. Date: Sat, 12 Mar 2016 03:30:16 -0800 Message-ID: <87lh5ohr1z.fsf@gmail.com> References: <87vb4ypn9s.fsf@gmail.com> <87io0t14pi.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:56489) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aehkT-00074s-5Y for guix-devel@gnu.org; Sat, 12 Mar 2016 06:30:22 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aehkR-0003V2-G9 for guix-devel@gnu.org; Sat, 12 Mar 2016 06:30:21 -0500 In-Reply-To: <87io0t14pi.fsf@gnu.org> ("Ludovic \=\?utf-8\?Q\?Court\=C3\=A8s\=22'\?\= \=\?utf-8\?Q\?s\?\= message of "Fri, 11 Mar 2016 15:15:05 +0100") List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org To: Ludovic =?utf-8?Q?Court=C3=A8s?= Cc: guix-devel@gnu.org --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable 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=C3=A8s) 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=E2=80=99re part of that two-space tribe. ;-) OK - I think I've used double spaces everywhere, this time. > I prefer to put =E2=80=9Ce.g.=E2=80=9D things between em dashes instead o= f parentheses, > but have no reference supporting this choice, so=E2=80=A6 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 =E2=80=A6)) > > (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 =E2=80= =9CFor > the purpose of illustration=E2=80=9D) right above the @deffn, in part bec= ause it > deals with the general context rather than just =E2=80=98modify-services= =E2=80=99, 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=E2=80=99s 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=E2=80=99s good to have a fresh eye on= this > and quality suggestions to improve it! I'm glad to help! Chris --=-=-= Content-Type: text/x-patch; charset=utf-8 Content-Disposition: attachment; filename=0001-doc-Clarify-and-consolidate-modify-services-document.patch Content-Transfer-Encoding: quoted-printable >From 891e944dc522cdc250058e92d9150d6a6a39242f Mon Sep 17 00:00:00 2001 From: Chris Marusich 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=C4=B1rl=C4=B1/Kammer@* Copyright @copyright{} 2015, 2016 Leo Famulari Copyright @copyright{} 2016 Ben Woodcroft +Copyright @copyright{} 2016 Chris Marusich =20 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: =20 @lisp -(modify-services %base-services - (guix-service-type config =3D> - (guix-configuration - (inherit config) - (use-substitutes? #f) - (extra-options '("--gc-keep-outputs")))) - (mingetty-service-type config =3D> - (mingetty-configuration - (inherit config) - (motd (plain-file "motd" "Hi there!"))))) +(operating-system + ;; @dots{} + (services (modify-services %base-services + (guix-service-type config =3D> + (guix-configuration + (inherit config) + (use-substitutes? #f) + (extra-options '("--gc-keep-derivations"= )))) + (mingetty-service-type config =3D> + (mingetty-configuration + (inherit config) + (motd (plain-file "motd" "Hi there!"= )))))) @end lisp =20 -@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. =20 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: =20 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. =20 @deffn {Scheme Syntax} modify-services @var{services} @ (@var{type} @var{variable} =3D> @var{body}) @dots{} @@ -9932,16 +9944,21 @@ clauses. Each clause has the form: (@var{type} @var{variable} =3D> @var{body}) @end example =20 -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}. =20 -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. =20 -@example -(map (lambda (service) @dots{}) @var{services}) -@end example @end deffn =20 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 =C2=A9 2015, 2016 Ludovic Court=C3=A8s +;;; Copyright =C2=A9 2016 Chris Marusich ;;; ;;; This file is part of GNU Guix. ;;; @@ -153,30 +154,20 @@ =20 (define-syntax modify-services (syntax-rules () - "Modify the services listed in SERVICES according to CLAUSES. Each cl= ause -must have the form: - - (TYPE VARIABLE =3D> 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 =3D> - (guix-configuration - (inherit config) - (use-substitutes? #f) - (extra-options '(\"--gc-keep-derivations\")))) - (mingetty-service-type config =3D> - (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 =3D> 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 ...)) --=20 2.6.3 --=-=-=--