unofficial mirror of guix-devel@gnu.org 
 help / color / mirror / code / Atom feed
* [PATCH] doc: Clarify and consolidate modify-services documentation.
@ 2016-03-07 10:58 Chris Marusich
  2016-03-11 14:15 ` Ludovic Courtès
  0 siblings, 1 reply; 13+ messages in thread
From: Chris Marusich @ 2016-03-07 10:58 UTC (permalink / raw)
  To: guix-devel

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

Hi,

I recently wanted to modify a service in GuixSD. I found the manual
helpful but lacking, so I've drafted a patch to improve the situation. I
hope it helps.

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.

It's easy to modify a service if you just copy the example. I wanted to
do more than just that, though: I wanted to understand what I was
typing. The existing manual was unsatisfactory for that purpose. I had
to go to the source to actually understand why the examples
worked. Hopefully this patch will help others to more quickly understand
how 'modify-services' works.

Chris


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-Clarify-and-consolidate-modify-services-document.patch --]
[-- Type: text/x-patch, Size: 10442 bytes --]

From 10518b419c2f9322082c3f6d2a2c7535f7645f3d 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    | 93 +++++++++++++++++++++++++++++++++++---------------------
 gnu/services.scm | 78 ++++++++++++++++++++++++++++++++---------------
 2 files changed, 112 insertions(+), 59 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 082fe5a..8d2b006 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -6044,28 +6044,14 @@ 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}:
-
-@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!")))))
-@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.
+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}}.
 
 The configuration for a typical ``desktop'' usage, with the X11 display
 server, a desktop environment, network management, power management, and
@@ -9916,11 +9902,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 +9919,52 @@ 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.
+
+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.
+  (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
+
+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{%desktop-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.
+
+@xref{Using the Configuration System}, for more information about
+configuring the operating system.
 
-@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..f87819b 100644
--- a/gnu/services.scm
+++ b/gnu/services.scm
@@ -153,30 +153,60 @@
 
 (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)."
+    "The 'modify-services' form provides a handy way to change the
+parameters of some of the services of a list such as
+%BASE-SERVICES.  It evalutes to a list of services.  Of course, you
+could always use standard list combinators such as 'map' and 'fold' to
+do that; 'modify-services' simply provides a more concise form for
+this common pattern.
+
+modify-services SERVICES (TYPE VARIABLE => BODY) ...
+
+Modify the services listed in SERVICES according to the given clauses.
+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.  Because a service's service parameters
+are created using 'define-record-type*', you can write a succint BODY
+that evaluates to the new service parameters by using the 'inherit'
+feature that 'define-record-type*' provides.
+
+For the purpose of illustration, let us assume you want to modify the
+default %DESKTOP-SERVICES in your operating system configuration
+file.  To accomplish that, you could write something like the
+following:
+
+(operating-system
+  ;; Other configuration which precedes the \"services\" section
+  ;; has been omitted here for brevity.
+  (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!\"))))))
+
+This changes the configuration (i.e., the service parameters) of the
+'guix-service-type' instance, and that of all the
+'mingetty-service-type' instances in the %DESKTOP-SERVICES list.
+Observe how this is accomplished: first, we arrange for the original
+configuration to be bound to the identifier 'config' in the BODY, and
+then we write the BODY so that it evaluates to the desired
+configuration.  In particular, notice how we use 'inherit' to create a
+new configuration which has the same values as the old configuration,
+but with a few modifications."
     ((_ services clauses ...)
      (map (lambda (service)
             (%modify-service service clauses ...))
-- 
2.6.3


^ permalink raw reply related	[flat|nested] 13+ messages in thread

* Re: [PATCH] doc: Clarify and consolidate modify-services documentation.
  2016-03-07 10:58 [PATCH] doc: Clarify and consolidate modify-services documentation Chris Marusich
@ 2016-03-11 14:15 ` Ludovic Courtès
  2016-03-12 11:30   ` Chris Marusich
  0 siblings, 1 reply; 13+ messages in thread
From: Ludovic Courtès @ 2016-03-11 14:15 UTC (permalink / raw)
  To: Chris Marusich; +Cc: guix-devel

Chris Marusich <cmmarusich@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 <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.

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’.

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH] doc: Clarify and consolidate modify-services documentation.
  2016-03-11 14:15 ` Ludovic Courtès
@ 2016-03-12 11:30   ` Chris Marusich
  2016-03-12 11:38     ` Chris Marusich
  0 siblings, 1 reply; 13+ messages in thread
From: Chris Marusich @ 2016-03-12 11:30 UTC (permalink / raw)
  To: Ludovic Courtès; +Cc: guix-devel

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


^ permalink raw reply related	[flat|nested] 13+ messages in thread

* Re: [PATCH] doc: Clarify and consolidate modify-services documentation.
  2016-03-12 11:30   ` Chris Marusich
@ 2016-03-12 11:38     ` Chris Marusich
  2016-03-13  7:33       ` Chris Marusich
                         ` (2 more replies)
  0 siblings, 3 replies; 13+ messages in thread
From: Chris Marusich @ 2016-03-12 11:38 UTC (permalink / raw)
  To: Ludovic Courtès; +Cc: guix-devel

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

Whoops, there was a missing brace in my patch, so make couldn't build
the documentation. Here's a new patch which adds the missing brace.

Sorry for the double post!


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

From bf03c0a3fa35144342849cdf550219a185fbf10d 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 f7deafa..29e73bf 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
@@ -6087,28 +6088,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
@@ -9963,11 +9974,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{}
@@ -9979,16 +9991,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 cff6ed3..4fb5328 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


^ permalink raw reply related	[flat|nested] 13+ messages in thread

* Re: [PATCH] doc: Clarify and consolidate modify-services documentation.
  2016-03-12 11:38     ` Chris Marusich
@ 2016-03-13  7:33       ` Chris Marusich
  2016-03-15 14:56       ` Ludovic Courtès
  2016-03-17  8:12       ` Alex Kost
  2 siblings, 0 replies; 13+ messages in thread
From: Chris Marusich @ 2016-03-13  7:33 UTC (permalink / raw)
  To: Ludovic Courtès; +Cc: guix-devel

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

I finished installing texlive, but when I try to build the PDF document,
it fails. I'm not sure I can test this on my end using GuixSD out of the
box:

- --8<---------------cut here---------------start------------->8---
[0] marusich@carbuncle:~/guix/doc
$ guix environment texlive
[0] [env] marusich@carbuncle:~/guix/doc
$ texi2pdf guix.texi 
/home/marusich/.guix-profile/bin/texi2dvi: TeX neither supports -recorder nor outputs \openout lines in its log file
[1] [env] marusich@carbuncle:~/guix/doc
$
- --8<---------------cut here---------------end--------------->8---

- -- 
Chris
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQIcBAEBCAAGBQJW5RftAAoJEN1AmhXYIkadVSsQAIyq+YAPXW6Q7oDkCxfI2fI1
K1LwDFLVe4Sk60OF/btOSLEiXCuCsx8n5vFFO63F4cNpI8JCz4cROC9J5QLQ8t6e
3S0N5oZSaMDxkzMHMQDxtezjFLiUD5bPrnxDPK5XWoKdGEWkgF2hr7Mg5wq2beEO
aTCiIx0XFnaXUdo7SI6C7ATmdGWfW0z4wbDxb52M3YAv4aFrmZYDCJ2wzDSOnHBs
7jF19wbqNXBii/eLgCIqPLxwffbrPUH1b0D5OvjPmPlHg9pk5y1RBP0jUWn1Vfuf
4eLV6v6WrtFqaa1k5qBTcxPIPzMZv46r3QAmXt/C6NigFwwMGldDRSwvihuEzvPB
KOoLbXJU914r8mZhqHXoWdXtrUHU1IRFkr94WbRg1eWWop8N8Kc1O29YnLYELEfe
U0udUAU+FFD1V9rjxip+FKxizts3CmavF8nahei1XZLUa1czpxv0HoxVk+FNpPWy
9tKjDfyWNAdDUg1nX/Dvn1HypN5kTgukhhWTRwf74NcZackMcRXId2xQ+AVBoVkv
hQJPYt/+gsAlXDDEnjmn6mhoj8lITTqESpHTuW6Y5dvtpjr/8leZZ6ajxpOt+b1V
+C8dPGFbZzMmhrzHEui3IspYKyuhEL+GMrPchygLTySDd1M9P9+P3qoq8dSV21+x
P9nsjhrIVVosOTc2bwz4
=wxEh
-----END PGP SIGNATURE-----

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH] doc: Clarify and consolidate modify-services documentation.
  2016-03-12 11:38     ` Chris Marusich
  2016-03-13  7:33       ` Chris Marusich
@ 2016-03-15 14:56       ` Ludovic Courtès
  2016-03-17  8:12       ` Alex Kost
  2 siblings, 0 replies; 13+ messages in thread
From: Ludovic Courtès @ 2016-03-15 14:56 UTC (permalink / raw)
  To: Chris Marusich; +Cc: guix-devel

Chris Marusich <cmmarusich@gmail.com> skribis:

> From bf03c0a3fa35144342849cdf550219a185fbf10d 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.

Pushed with small tweaks: I kept the docstring almost unchanged, and
changed the example so that lines would fit in the PDF (not removing
anything from the example, just formatting things differently so it
appears correctly.)

Let me know if there’s anything wrong.

Thank you!

Ludo’.

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH] doc: Clarify and consolidate modify-services documentation.
  2016-03-12 11:38     ` Chris Marusich
  2016-03-13  7:33       ` Chris Marusich
  2016-03-15 14:56       ` Ludovic Courtès
@ 2016-03-17  8:12       ` Alex Kost
  2016-03-17  8:52         ` Ludovic Courtès
  2 siblings, 1 reply; 13+ messages in thread
From: Alex Kost @ 2016-03-17  8:12 UTC (permalink / raw)
  To: Chris Marusich; +Cc: guix-devel

Chris Marusich (2016-03-12 14:38 +0300) wrote:

> From bf03c0a3fa35144342849cdf550219a185fbf10d 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.

[...]
> -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.

Now there is a compilation warning, as makeinfo doesn't like this line:

  ./doc/guix.texi:10138: warning: `.' or `,' must follow @xref

-- 
Alex

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH] doc: Clarify and consolidate modify-services documentation.
  2016-03-17  8:12       ` Alex Kost
@ 2016-03-17  8:52         ` Ludovic Courtès
  2016-03-18  7:42           ` Alex Kost
  0 siblings, 1 reply; 13+ messages in thread
From: Ludovic Courtès @ 2016-03-17  8:52 UTC (permalink / raw)
  To: Alex Kost; +Cc: guix-devel

Alex Kost <alezost@gmail.com> skribis:

> Chris Marusich (2016-03-12 14:38 +0300) wrote:
>
>> From bf03c0a3fa35144342849cdf550219a185fbf10d 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.
>
> [...]
>> -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.
>
> Now there is a compilation warning, as makeinfo doesn't like this line:
>
>   ./doc/guix.texi:10138: warning: `.' or `,' must follow @xref

Pushed the obvious fix, thanks.

I guess most of us are using Texinfo 6.1 now and won’t notice.

Ludo’.

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH] doc: Clarify and consolidate modify-services documentation.
  2016-03-17  8:52         ` Ludovic Courtès
@ 2016-03-18  7:42           ` Alex Kost
  2016-03-18 21:11             ` Ludovic Courtès
  0 siblings, 1 reply; 13+ messages in thread
From: Alex Kost @ 2016-03-18  7:42 UTC (permalink / raw)
  To: Ludovic Courtès; +Cc: guix-devel

Ludovic Courtès (2016-03-17 11:52 +0300) wrote:

> Alex Kost <alezost@gmail.com> skribis:
>
>> Chris Marusich (2016-03-12 14:38 +0300) wrote:
>>
>>> From bf03c0a3fa35144342849cdf550219a185fbf10d 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.
>>
>> [...]
>>> -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.
>>
>> Now there is a compilation warning, as makeinfo doesn't like this line:
>>
>>   ./doc/guix.texi:10138: warning: `.' or `,' must follow @xref
>
> Pushed the obvious fix, thanks.
>
> I guess most of us are using Texinfo 6.1 now and won’t notice.

Oh, I've never noticed that I use 6.0.  It's because I update my
profiles using "guix package --manifest" facility and:

  (@ (gnu packages texinfo) texinfo) gives Texinfo 6.0

Is there a reason why we keep so many versions of texinfo?  In
particular why there is ‘texinfo-6.1’ variable, while ‘texinfo’ is still
6.0?

-- 
Alex

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH] doc: Clarify and consolidate modify-services documentation.
  2016-03-18  7:42           ` Alex Kost
@ 2016-03-18 21:11             ` Ludovic Courtès
  2016-03-19  8:46               ` [PATCH] gnu: texinfo: Use version 6.1 by default Alex Kost
  0 siblings, 1 reply; 13+ messages in thread
From: Ludovic Courtès @ 2016-03-18 21:11 UTC (permalink / raw)
  To: Alex Kost; +Cc: guix-devel

Alex Kost <alezost@gmail.com> skribis:

> Ludovic Courtès (2016-03-17 11:52 +0300) wrote:
>
>> Alex Kost <alezost@gmail.com> skribis:
>>
>>> Chris Marusich (2016-03-12 14:38 +0300) wrote:
>>>
>>>> From bf03c0a3fa35144342849cdf550219a185fbf10d 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.
>>>
>>> [...]
>>>> -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.
>>>
>>> Now there is a compilation warning, as makeinfo doesn't like this line:
>>>
>>>   ./doc/guix.texi:10138: warning: `.' or `,' must follow @xref
>>
>> Pushed the obvious fix, thanks.
>>
>> I guess most of us are using Texinfo 6.1 now and won’t notice.
>
> Oh, I've never noticed that I use 6.0.  It's because I update my
> profiles using "guix package --manifest" facility and:
>
>   (@ (gnu packages texinfo) texinfo) gives Texinfo 6.0
>
> Is there a reason why we keep so many versions of texinfo?  In
> particular why there is ‘texinfo-6.1’ variable, while ‘texinfo’ is still
> 6.0?

It’s just that the upgrade wuold trigger a full rebuild.

We should replace 6.0 with 6.1 in ‘core-updates’.  Would you like to
take care of it?

(4.3 is kept in the installer because it has a smaller footprint.)

Ludo’.

^ permalink raw reply	[flat|nested] 13+ messages in thread

* [PATCH] gnu: texinfo: Use version 6.1 by default.
  2016-03-18 21:11             ` Ludovic Courtès
@ 2016-03-19  8:46               ` Alex Kost
  2016-03-19 21:02                 ` Ludovic Courtès
  0 siblings, 1 reply; 13+ messages in thread
From: Alex Kost @ 2016-03-19  8:46 UTC (permalink / raw)
  To: Ludovic Courtès; +Cc: guix-devel

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

Ludovic Courtès (2016-03-19 00:11 +0300) wrote:

> Alex Kost <alezost@gmail.com> skribis:
>
>> Ludovic Courtès (2016-03-17 11:52 +0300) wrote:
[...]
>>> I guess most of us are using Texinfo 6.1 now and won’t notice.
>>
>> Oh, I've never noticed that I use 6.0.  It's because I update my
>> profiles using "guix package --manifest" facility and:
>>
>>   (@ (gnu packages texinfo) texinfo) gives Texinfo 6.0
>>
>> Is there a reason why we keep so many versions of texinfo?  In
>> particular why there is ‘texinfo-6.1’ variable, while ‘texinfo’ is still
>> 6.0?
>
> It’s just that the upgrade wuold trigger a full rebuild.
>
> We should replace 6.0 with 6.1 in ‘core-updates’.  Would you like to
> take care of it?

If you mean to make a patch for this update, then it is attached.  But
if you mean to rebuild the world, and to check if anything fails, then I
wouldn't like to give so much care to this, sorry.  So if it's OK to
commit this patch to core-updates without testing, then I will gladly do
this :-)


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-gnu-texinfo-Use-version-6.1-by-default.patch --]
[-- Type: text/x-patch, Size: 2885 bytes --]

From 6fc9bc8181a7be3dc2106f7ea6563b7536ff9fd7 Mon Sep 17 00:00:00 2001
From: Alex Kost <alezost@gmail.com>
Date: Sat, 19 Mar 2016 11:36:33 +0300
Subject: [PATCH] gnu: texinfo: Use version 6.1 by default.

* gnu/packages/texinfo.scm (texinfo): Update to 6.1.
(texinfo-6.1): Remove.
* gnu/packages/emacs.scm (emacs)[arguments]: Remove 'remove-info.info' phase.
---
 gnu/packages/emacs.scm   |  8 --------
 gnu/packages/texinfo.scm | 16 ++--------------
 2 files changed, 2 insertions(+), 22 deletions(-)

diff --git a/gnu/packages/emacs.scm b/gnu/packages/emacs.scm
index 7270fc4..321e489 100644
--- a/gnu/packages/emacs.scm
+++ b/gnu/packages/emacs.scm
@@ -88,14 +88,6 @@
              (substitute* (find-files "." "^Makefile\\.in$")
                (("/bin/pwd")
                 "pwd"))))
-         (add-after 'install 'remove-info.info
-           (lambda* (#:key outputs #:allow-other-keys)
-             ;; Remove 'info.info', which is provided by Texinfo <= 6.0.
-             ;; TODO: Remove this phase when we switch to Texinfo 6.1.
-             (let ((out (assoc-ref outputs "out")))
-               (delete-file
-                (string-append out "/share/info/info.info.gz"))
-               #t)))
          (add-after 'install 'install-site-start
            ;; Copy guix-emacs.el from Guix and add it to site-start.el.  This
            ;; way, Emacs packages provided by Guix and installed in
diff --git a/gnu/packages/texinfo.scm b/gnu/packages/texinfo.scm
index 5c1204e..8b9ed00 100644
--- a/gnu/packages/texinfo.scm
+++ b/gnu/packages/texinfo.scm
@@ -32,14 +32,14 @@
 (define-public texinfo
   (package
     (name "texinfo")
-    (version "6.0")
+    (version "6.1")
     (source (origin
               (method url-fetch)
               (uri (string-append "mirror://gnu/texinfo/texinfo-"
                                   version ".tar.xz"))
               (sha256
                (base32
-                "1r3i6jyynn6ab45fxw5bms8mflk9ry4qpj6gqyry72vfd5c47fhi"))))
+                "1ll3d0l8izygdxqz96wfr2631kxahifwdknpgsx2090vw963js5c"))))
     (build-system gnu-build-system)
     (native-inputs `(("procps" ,procps)))  ;one of the tests needs pgrep
     (inputs `(("ncurses" ,ncurses)
@@ -62,18 +62,6 @@ their source and the command-line Info reader.  The emphasis of the language
 is on expressing the content semantically, avoiding physical markup commands.")
     (license gpl3+)))
 
-(define-public texinfo-6.1
-  (package
-    (inherit texinfo)
-    (version "6.1")
-    (source (origin
-              (method url-fetch)
-              (uri (string-append "mirror://gnu/texinfo/texinfo-"
-                                  version ".tar.xz"))
-              (sha256
-               (base32
-                "1ll3d0l8izygdxqz96wfr2631kxahifwdknpgsx2090vw963js5c"))))))
-
 (define-public texinfo-5
   (package (inherit texinfo)
     (version "5.2")
-- 
2.6.3


^ permalink raw reply related	[flat|nested] 13+ messages in thread

* Re: [PATCH] gnu: texinfo: Use version 6.1 by default.
  2016-03-19  8:46               ` [PATCH] gnu: texinfo: Use version 6.1 by default Alex Kost
@ 2016-03-19 21:02                 ` Ludovic Courtès
  2016-03-23  8:41                   ` Alex Kost
  0 siblings, 1 reply; 13+ messages in thread
From: Ludovic Courtès @ 2016-03-19 21:02 UTC (permalink / raw)
  To: Alex Kost; +Cc: guix-devel

Alex Kost <alezost@gmail.com> skribis:

> From 6fc9bc8181a7be3dc2106f7ea6563b7536ff9fd7 Mon Sep 17 00:00:00 2001
> From: Alex Kost <alezost@gmail.com>
> Date: Sat, 19 Mar 2016 11:36:33 +0300
> Subject: [PATCH] gnu: texinfo: Use version 6.1 by default.
>
> * gnu/packages/texinfo.scm (texinfo): Update to 6.1.
> (texinfo-6.1): Remove.
> * gnu/packages/emacs.scm (emacs)[arguments]: Remove 'remove-info.info' phase.

OK!

This is a safe upgrade, so not worries if you didn’t check whether the
world rebuilds fine.

Thanks,
Ludo’.

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH] gnu: texinfo: Use version 6.1 by default.
  2016-03-19 21:02                 ` Ludovic Courtès
@ 2016-03-23  8:41                   ` Alex Kost
  0 siblings, 0 replies; 13+ messages in thread
From: Alex Kost @ 2016-03-23  8:41 UTC (permalink / raw)
  To: Ludovic Courtès; +Cc: guix-devel

Ludovic Courtès (2016-03-20 00:02 +0300) wrote:

> Alex Kost <alezost@gmail.com> skribis:
>
>> From 6fc9bc8181a7be3dc2106f7ea6563b7536ff9fd7 Mon Sep 17 00:00:00 2001
>> From: Alex Kost <alezost@gmail.com>
>> Date: Sat, 19 Mar 2016 11:36:33 +0300
>> Subject: [PATCH] gnu: texinfo: Use version 6.1 by default.
>>
>> * gnu/packages/texinfo.scm (texinfo): Update to 6.1.
>> (texinfo-6.1): Remove.
>> * gnu/packages/emacs.scm (emacs)[arguments]: Remove 'remove-info.info' phase.
>
> OK!
>
> This is a safe upgrade, so not worries if you didn’t check whether the
> world rebuilds fine.

Thanks, pushed to core-updates.

-- 
Alex

^ permalink raw reply	[flat|nested] 13+ messages in thread

end of thread, other threads:[~2016-03-23  8:41 UTC | newest]

Thread overview: 13+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2016-03-07 10:58 [PATCH] doc: Clarify and consolidate modify-services documentation Chris Marusich
2016-03-11 14:15 ` Ludovic Courtès
2016-03-12 11:30   ` Chris Marusich
2016-03-12 11:38     ` Chris Marusich
2016-03-13  7:33       ` Chris Marusich
2016-03-15 14:56       ` Ludovic Courtès
2016-03-17  8:12       ` Alex Kost
2016-03-17  8:52         ` Ludovic Courtès
2016-03-18  7:42           ` Alex Kost
2016-03-18 21:11             ` Ludovic Courtès
2016-03-19  8:46               ` [PATCH] gnu: texinfo: Use version 6.1 by default Alex Kost
2016-03-19 21:02                 ` Ludovic Courtès
2016-03-23  8:41                   ` Alex Kost

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/guix.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).