Allow job names to be arbitrary OCaml expressions.

[whenjobs.git] / tools / whenjobs.pod

diff --git a/tools/whenjobs.pod b/tools/whenjobs.pod
index 2acec9f..43fe847 100644 (file)
--- a/tools/whenjobs.pod
+++ b/tools/whenjobs.pod
@@ -513,6 +513,37 @@ with C<job "name">:
 The job name is passed to the shell script in the C<$JOBNAME>
 environment variable.
 
 The job name is passed to the shell script in the C<$JOBNAME>
 environment variable.
 

+=head2 OCAML EXPRESSIONS
+
+As well as simple "every" and "when" expressions, advanced users may
+want to use arbitrary OCaml expressions, functions, etc in the jobs
+script.  These are useful for factoring common code or strings, for
+setting the initial values of variables, or for defining cleanup
+functions.
+
+A simple example of an OCaml expression is:
+
+ let prefix = "daily_"
+ 
+ job (prefix ^ "virus_scan")
+ every day :
+ <<
+   # ...
+ >>
+ 
+ job (prefix ^ "disk_check")
+ every day :
+ <<
+   # ...
+ >>
+
+which creates two jobs called C<"daily_virus_scan"> and
+C<"daily_disk_check"> (C<^> is the OCaml string concatenation
+operator).
+
+The OCaml expressions run once, when the jobs file is being loaded or
+reloaded.
+