X-Git-Url: http://git.annexia.org/?p=whenjobs.git;a=blobdiff_plain;f=tools%2Fwhenjobs.pod;h=14ca14134a39e0880e50520aaeb37665a2b8c956;hp=25dff409786935c0d1730aed6daeca34b79374c1;hb=ff2670fcc7fe0b62a44dce15272b7cb362256e05;hpb=82c14058a0252e953cae3bd2f1fc3fe00746d173

diff --git a/tools/whenjobs.pod b/tools/whenjobs.pod
index 25dff40..14ca141 100644
--- a/tools/whenjobs.pod
+++ b/tools/whenjobs.pod
@@ -14,7 +14,7 @@ Editing the jobs script:
 Get and set variables:
 
  whenjobs --get variable
- whenjobs --set variable value [--type bool|int|float|string]
+ whenjobs --set variable=value [variable=value ...]
  whenjobs --variables
 
 Start and stop the per-user daemon:
@@ -29,6 +29,7 @@ Examine running jobs:
  whenjobs --jobs
  whenjobs --cancel serial
  whenjobs --start "name"
+ whenjobs --tail serial
 
 =head1 DESCRIPTION
 
@@ -42,7 +43,7 @@ Periodic jobs are written like this:
  <<
    # Get the current load average.
    load=`awk '{print $1}' /proc/loadavg`
-   whenjobs --set load $load --type float
+   whenjobs --set --type float load=$load
  >>
 
 When-statements let you create jobs that run based on variables set
@@ -78,12 +79,41 @@ Variables are stored (per-user) in the daemon.  You can use the
 command line tool to examine and set variables:
 
  $ whenjobs --variables
- load=0.9
- $ whenjobs --set cat sushi
+ JOBSERIAL=297
+ libguestfs_build_local=1.17.16
+ libguestfs_commit=7e32d892d76a31f55e2a4151902623b9949e3efa
+ libguestfs_dist=1.17.16
+ libguestfs_release=1.17.16
+ libguestfs_stable_build_local=1.16.10
+ libguestfs_stable_commit=27433a0a335301441b1eb6244ba425c2c44b2d99
+ libguestfs_stable_dist=1.16.10
+ libguestfs_stable_release=1.16.10
+ libguestfs_stable_version=1.16.10
+ libguestfs_version=1.17.16
+ $ whenjobs --set cat=sushi
  $ whenjobs --get cat
  sushi
 
-The act of setting a variable (using I<--set>) can trigger jobs to run.
+Note: The act of setting a variable (using I<--set>) can trigger jobs
+to run.
+
+You can also list out what jobs are running:
+
+ $ whenjobs --jobs
+ 287 libguestfs-stable: fedora 16
+    running in: /tmp/whenjobsa2afc44fd757465f95438309f1a51609
+    started at: 2012-03-13 10:59:37
+
+and you can 'tail' the output of running jobs which is useful for
+debugging:
+
+ $ whenjobs --tail 287
+ Uploading: 147496271972717053d46b82a07435ca  libguestfs-1.16.10.tar.gz
+
+You can start and cancel jobs manually:
+
+ $ whenjobs --start 'libguestfs: poll'
+ $ whenjobs --cancel 287
 
 =head1 OPTIONS
 
@@ -126,6 +156,17 @@ 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).
+Use I<--jobs> to list running jobs.
+
 =item B<--jobs>
 
 List all running jobs.
@@ -149,7 +190,7 @@ source, eg:
 
  whenjobs --lib $builddir/lib -e
 
-=item B<--set> variable value
+=item B<--set> variable=value [variable=value ...]
 
 =item B<--type> bool|int|float|string|unit
 
@@ -157,18 +198,35 @@ I<--set> sets the variable named C<variable> to the new C<value>.  The
 variable is created if it does not already exist.  Note that setting a
 variable can cause jobs to run immediately.
 
-To unset a variable, set it to the empty string:
+To unset a variable, set it to the empty string like this:
 
- whenjobs --set var ""
+ whenjobs --set var=
 
 By default variables are strings.  You can also set the type of a
-variable when setting it by adding the optional I<--type> parameter:
+variable when setting it by adding the optional I<--type> parameter.
+The I<--type> parameter should come I<before> the variable
+declaration, like this:
 
- whenjobs --set free_space 10000 --type int
+ whenjobs --set --type int free_space=10000
 
 See the discussion of variable types in the L</REFERENCE> section
 below.
 
+You can set multiple variables.  When setting multiple variables in a
+single command, the values are all changed in a single atomic
+operation.
+
+ whenjobs --set cat=sushi food=fish
+
+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
+
+(C<cat> and C<food> are strings, and C<weight> is a float).
+
 =item B<--start> "job name"
 
 Start the job immediately and unconditionally.
@@ -176,6 +234,22 @@ Start the job immediately and unconditionally.
 This runs the job even if its normal preconditions are not met.  This
 may cause unexpected results, so use with caution.
 
+=item B<--tail> serial
+
+Tail the output of the running job identified by its serial number.
+Use the I<--jobs> flag to get a list of running jobs.
+
+=item B<--test> variable=value [variable=value ...]
+
+This works the same way as the I<--set> option, but the difference is
+that the variables are not set.  Instead, it lists out the jobs that
+I<would> run, I<if> the variables were updated to these new values.
+
+The variables are not actually updated, and the jobs are not actually
+run.
+
+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.
@@ -193,12 +267,6 @@ 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<--help>
-
-Display brief usage and exit.
-
 =back
 
 =head1 REFERENCE