=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>.
=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