02/02: utils: Improve docstring of 'substitute*' & co.

[Ludovic Courtès]

civodul pushed a commit to branch core-updates
in repository guix.

commit 094b2efc3c672d60c2fbaca68ce632ba6ab54700
Author: Taylan Ulrich Bayırlı/Kammer <address@hidden>
Date:   Tue Nov 25 21:52:13 2014 +0100

    utils: Improve docstring of 'substitute*' & co.
    
    * guix/build/utils.scm (substitute): Clarify first sentence of
      docstring and add warning to the docstring about using '$' to match
      an end of line.
      (substitute*): Add warning to the docstring about using '$' to match
      an end of line.
    
    Signed-off-by: Ludovic Courtès <address@hidden>
---
 guix/build/utils.scm |   14 +++++++++-----
 1 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/guix/build/utils.scm b/guix/build/utils.scm
index c480dbf..737976e 100644
--- a/guix/build/utils.scm
+++ b/guix/build/utils.scm
@@ -413,10 +413,11 @@ PROC's result is returned."
         (false-if-exception (delete-file template))))))
 
 (define (substitute file pattern+procs)
-  "PATTERN+PROCS is a list of regexp/two-argument procedure.  For each line
-of FILE, and for each PATTERN that it matches, call the corresponding PROC
-as (PROC LINE MATCHES); PROC must return the line that will be written as a
-substitution of the original line."
+  "PATTERN+PROCS is a list of regexp/two-argument-procedure pairs.  For each
+line of FILE, and for each PATTERN that it matches, call the corresponding
+PROC as (PROC LINE MATCHES); PROC must return the line that will be written as
+a substitution of the original line.  Be careful about using '$' to match the
+end of a line; by itself it won't match the terminating newline of a line."
   (let ((rx+proc  (map (match-lambda
                         (((? regexp? pattern) . proc)
                          (cons pattern proc))
@@ -476,7 +477,10 @@ When one of the MATCH-VAR is `_', no variable is bound to 
the corresponding
 match substring.
 
 Alternatively, FILE may be a list of file names, in which case they are
-all subject to the substitutions."
+all subject to the substitutions.
+
+Be careful about using '$' to match the end of a line; by itself it won't
+match the terminating newline of a line."
     ((substitute* file ((regexp match-var ...) body ...) ...)
      (let ()
        (define (substitute-one-file file-name)