From 4d2c5929f056e547b6bd138f69bd1e09e7cfc89f Mon Sep 17 00:00:00 2001
From: Maxim Cournoyer <address@hidden>
Date: Thu, 1 Aug 2019 07:34:17 +0900
Subject: [PATCH] doc: Document the use of `program-file' for mcron jobs.

* doc/guix.texi (Scheduled Job Execution): Explain why using `program-file'
for an mcron job can be necessary.  Add an example.
---
 doc/guix.texi | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index e6047a4909..418dbce16b 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -12444,6 +12444,41 @@ gexps to introduce job definitions that are passed to mcron
                   %base-services)))
 @end lisp
 
+For more complex jobs defined in Scheme, it is safer to pass the job as a
+script to mcron; otherwise, imported syntax definitions wouldn't work
+correctly, as these must be strictly imported at the top level of a Guile
+module.  This can be achieved using the @code{program-file} procedure from the
+@code{(guix gexp)} module, as shown in the example below.
+
+@lisp
+(define %battery-alert-job
+  ;; Beep the system when the battery reaches %MIN-LEVEL or less
+  ;; battery percent.
+  #~(job
+     '(next-minute (range 0 60 1))
+     #$(program-file
+	"battery-alert.scm"
+	(with-imported-modules (source-module-closure
+				'((guix build utils)))
+	  #~(begin
+	      (define %min-level 20)
+	      (use-modules (guix build utils)
+			   (ice-9 popen)
+			   (ice-9 regex)
+			   (ice-9 textual-ports)
+			   (srfi srfi-26))
+	      (setenv "LC_ALL" "C")
+	      (let* ((input-pipe (open-pipe* OPEN_READ
+					     #$(file-append acpi "/bin/acpi")))
+		     (output (get-string-all input-pipe))
+		     (m (string-match "Discharging, ([0-9]+)%" output))
+		     (level (and=> m (compose string->number
+					      (cut match:substring <> 1)))))
+		(when (and=> level (cut <= <> %min-level))
+		  (format #t "warning: Battery level is low (~a%)~%" level)
+		  (invoke #$(file-append beep "/bin/beep") "-r5"))))))))
+@end lisp
+
 @xref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron},
 for more information on mcron job specifications.  Below is the
 reference of the mcron service.
-- 
2.21.0