X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=tools%2Fwhenjobs.pod;h=1f38d2967fbe92613ef06798642e9a17c58b630f;hb=2c27f26c486961d1b7799d4f4274aa31d04df845;hp=0d1204a6ffa59cc8928a52f083320fb0fe33ed65;hpb=cfc76a6b38e225b96e5e53afbd511038c3e5bf05;p=whenjobs.git

diff --git a/tools/whenjobs.pod b/tools/whenjobs.pod
index 0d1204a..1f38d29 100644
--- a/tools/whenjobs.pod
+++ b/tools/whenjobs.pod
@@ -156,6 +156,12 @@ C<vi> is used.
 
 Print the value of a variable.
 
+=item B<-help>
+
+=item B<--help>
+
+Display brief usage and exit.
+
 =item B<--job-names>
 
 List the names of all loaded jobs (whether they are running or not).
@@ -215,7 +221,9 @@ operation.
 When using I<--type> and multiple variables, the type changes the
 remaining command line parameters until the next I<--type>, eg:
 
- whenjobs --set cat=sushi --type float weight=3.5 --type string food=fish
+ whenjobs --set cat=sushi \
+     --type float weight=3.5 \
+     --type string food=fish
 
 (C<cat> and C<food> are strings, and C<weight> is a float).
 
@@ -244,11 +252,13 @@ The output is a list of job names that would run.
 
 =item B<--upload>
 
-Compile the jobs script and upload it to the daemon, without editing.
+Compile the jobs file(s) and upload it to the daemon, without editing.
 Note that the I<--edit> option does this automatically.  Furthermore,
 when the daemon is started it checks for a jobs script and loads it if
 found.
 
+See also L</MULTIPLE JOBS FILES> below.
+
 =item B<--variables>
 
 Display all the variables and their values, in the format C<name=value>.
@@ -259,11 +269,24 @@ Display all the variables and their values, in the format C<name=value>.
 
 Display the name and version of the program and exit.
 
-=item B<-help>
+=item B<--whisper> variable=value [variable=value ...]
 
-=item B<--help>
+This works the same way as the I<--set> option, but with the
+difference that jobs' when clauses are not reevaluated.  In other
+words, the variables are set, but "quietly" so as not to trigger any
+jobs to run.
 
-Display brief usage and exit.
+Note that this can lead to some unexpected results: one case is a
+when job such as:
+
+ when changed a || changed b : << ... >>
+
+If C<a> is changed using I<--whisper>, then the job will not run.
+
+But later on, if C<b> is set but to the same value that it already has
+(ie. not changed), the job will run because the whole when-clause is
+reevaluated and C<a> is found to have changed since the last run of
+the job.
 
 =back
 
@@ -839,6 +862,57 @@ fields:
 
 =back
 
+=head1 MULTIPLE JOBS FILES
+
+The whenjobs I<-e> and I<-l> options edit and list a file called
+C<$HOME/.whenjobs/jobs.ml>.  This is an OCaml source file which is
+compiled behind the scenes into a bytecode file called
+C<$HOME/.whenjobs/jobs.cmo>.  C<jobs.cmo> is what the daemon normally
+loads.
+
+You can also edit C<$HOME/.whenjobs/jobs.ml> by other means (eg.  your
+own editor).  After editing, to recompile and upload it, use:
+
+ whenjobs --upload
+
+When you have lots of jobs, it is convenient to split the jobs across
+multiple files.  Any C<*.ml> files located in C<$HOME/.whenjobs> can
+be used (with some restrictions on filenames -- see below).  These are
+compiled to the corresponding C<*.cmo> files and loaded into the
+daemon using the I<--upload> command.
+
+To create multiple jobs files, you cannot use the I<-e> or I<-l>
+options.  Instead you have to create them yourself in
+C<$HOME/.whenjobs>, and when you have finished creating or editing
+them, upload them.
+
+=head2 FILENAME RESTRICTIONS ON JOBS FILES
+
+In OCaml, a file called C<jobs.ml> corresponds to an OCaml module
+called C<Jobs> (note the capitalization).  OCaml module names can only
+contain ASCII alphanumeric characters, underscore, and C<'> (single
+quote), and they must begin with an alphabetic character.  The same
+rules apply to jobs files.
+
+Furthermore, various OCaml module names are reserved (eg. C<Map>,
+C<List>).  It is therefore better to prefix any names with something
+specific to your application.
+
+Examples of legal filenames are:
+
+ foo.ml
+ app_foo.ml
+ app_123.ml
+ jobs.ml
+
+Examples of illegal filenames are:
+
+ ann.txt    # must end with .ml
+ 123.ml     # must begin with alphabetic
+ app!.ml    # must contain alphanumeric or underscore
+ app-foo.ml # must contain alphanumeric or underscore
+ map.ml     # reserved module name
+
 =head1 FILES