Minor rearrangements to whenjobs(1) manpage.

[whenjobs.git] / tools / whenjobs.pod

diff --git a/tools/whenjobs.pod b/tools/whenjobs.pod
index 25dff40..14ca141 100644 (file)
--- a/tools/whenjobs.pod
+++ b/tools/whenjobs.pod
@@ -14,7 +14,7 @@ Editing the jobs script:
 Get and set variables:
 
  whenjobs --get variable
 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:
  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 --jobs
  whenjobs --cancel serial
  whenjobs --start "name"

+ whenjobs --tail serial

 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 


@@ -42,7 +43,7 @@ Periodic jobs are written like this:
  <<
    # Get the current load average.
    load=`awk '{print $1}' /proc/loadavg`
  <<
    # 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
  >>
 
 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
 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
 
  $ 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
 
 
 =head1 OPTIONS
 


@@ -126,6 +156,17 @@ C<vi> is used.
 
 Print the value of a variable.
 
 
 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.
 =item B<--jobs>
 
 List all running jobs.


@@ -149,7 +190,7 @@ source, eg:
 
  whenjobs --lib $builddir/lib -e
 
 
  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
 
 
 =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.
 
 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
 
 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.
 
 
 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.
 =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.
 
 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.
 =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.
 
 
 Display the name and version of the program and exit.
 

-=item B<-help>
-
-=item B<--help>
-
-Display brief usage and exit.
-

 =back
 
 =head1 REFERENCE
 =back
 
 =head1 REFERENCE