guix: Improve docstring of wrap-program.series-3390

* guix/build/utils.scm (wrap-progran): Add an explanation for POSITION. Change
'DIRECTORIES' to 'VALUES' since an environment variable might not only be
paths.'

1 files changed, 12 insertions, 4 deletions

diff --git a/guix/build/utils.scm b/guix/build/utils.scm
index b8be73ead4..ba4d1d8657 100644
--- a/guix/build/utils.scm
+++ b/guix/build/utils.scm
@@ -5,6 +5,7 @@
 ;;; Copyright © 2015, 2018 Mark H Weaver <mhw@netris.org>
 ;;; Copyright © 2018 Arun Isaac <arunisaac@systemreboot.net>
 ;;; Copyright © 2018, 2019 Ricardo Wurmus <rekado@elephly.net>
+;;; Copyright © 2020 Brendan Tildesley <mail@brendan.scot>
 ;;;
 ;;; This file is part of GNU Guix.
 ;;;
@@ -1114,13 +1115,20 @@ known as `nuke-refs' in Nixpkgs."
               (string-suffix? "-real" base)))))
 
 (define* (wrap-program prog #:rest vars)
-  "Make a wrapper for PROG.  VARS should look like this:
+  "Make a wrapper for PROG.  VARS is a list of lists that should look like this:
 
-  '(VARIABLE DELIMITER POSITION LIST-OF-DIRECTORIES)
+  '(VARIABLE DELIMITER POSITION LIST-OF-VALUES)
 
 where DELIMITER is optional.  ':' will be used if DELIMITER is not given.
-
-For example, this command:
+POSITION is a Scheme symbol of either =, prefix, or suffix that selects how
+the export VARIABLE line is formatted.  prefix and suffix each result in
+including values from the users environment either after or before VALUE,
+whereas = overshadows any existing value, preventing the users environment
+from 'infecting' the wrapped programs environment.  It is important to
+understand how each variable is used by the program so that the correct choice
+can be made.  Otherwise, the program could malfunction in unexpected ways on a
+different persons computer due to a difference in the inherited environment
+variables.  For example, this command:
 
   (wrap-program \"foo\"
                 '(\"PATH\" \":\" = (\"/gnu/.../bar/bin\"))