[Bacula-users] Proposed documentation patch regarding Date-time-specific

For an obscure reason, I need a job to run in certain weeks of the year.
I found the documentation to be unclear, specifically the BNF.  I also
didn't see a response to another user's query [1] that was similar to mine.

So, I grabbed the code and read the parser myself.  Based on that
reading, I propose the attached documentation patch.  The description
text should be clarified as well, but I'll not put the time into that if
this patch is viewed as unlikely to be accepted.

Here's the result of the patch so one can understand it without having
to download the docs and patch it yourself:

\begin{verbatim}
<ignored-seperators> = , | " "
<on-keyword>      = on
<eol-keyword>     = # | ; | <end-of-line>
<at-keyword>      = at
<week-keyword>    = 1st | 2nd | 3rd | 4th | 5th | first |
                    second | third | fourth | fifth
<wday-keyword>    = sun | mon | tue | wed | thu | fri | sat |
                    sunday | monday | tuesday | wednesday |
                    thursday | friday | saturday
<week-of-year-keyword> = w00 | w01 | ... w52 | w53
<month-keyword>   = jan | feb | mar | apr | may | jun | jul |
                    aug | sep | oct | nov | dec | january |
                    february | ... | december
<daily-keyword>   = daily
<weekly-keyword>  = weekly
<monthly-keyword> = monthly
<hourly-keyword>  = hourly
<12hour>          = 0 | 1 | 2 | ... 12
<hour>            = 0 | 1 | 2 | ... 23
<minute>          = 0 | 1 | 2 | ... 59
<day>             = 1 | 2 | ... 31
<time>            = <hour>:<minute> |
                    <12hour>:<minute>am |
                    <12hour>:<minute>pm
<time-spec>       = <at-keyword> <time> |
                    <hourly-keyword> | ""
<day-range>       = <day>-<day>
<day-list>        = <day> | <day> <day-list>
<day-spec>        = <daily-keyword> | <day-range> | <day-list>
<month-range>     = <month-keyword>-<month-keyword>
<month-list>      = <month-keyword> | <month-keyword> <month-list>
<month-spec>      = <monthly-keyword> | <month-range> |
                    <month-list>
<wday-range>      = <wday-keyword>-<wday-keyword>
<wday-list>       = <wday-keyword> | <wday-keyword> <wday-list>
<wday-spec>       = <weekly-keyword> | <wday-range> | <wday-list>
<woy-range>       = <week-of-year-keyword>-<week-of-year-keyword>
<woy-list>        = <week-of-year-keyword> |
                          <week-of-year-keyword> <woy-list>
<woy-spec>        = <woy-range> | <woy-list>
<date>            = <day-spec> | <month-spec> | <wday-spec> | <woy-spec>
<date-list>       = <date> | <date> <date-list> | ""
<date-time-spec>  = <date-list> <time-spec>

Note: "on" must preceed <date-list> only if the first token is a <day>
\end{verbatim}
[...]
The parser is liberal so complicated schedules are possible:

\footnotesize
\begin{verbatim}
Schedule {
  Name = "Complicated"
  Run = Level=Full Monday Friday w26 w18 at 2:05
  Run = Level=Incremental on 1-15 April hourly
  Run = Level=Incremental daily December-February at 11:00pm
}
\end{verbatim}
\normalsize

Note that the parser is very liberal.  Each of the specifications below
is valid, though in many cases non-sensical.  I'm not suggesting that the
parser should be more strict.  Rather, I think the documentation needs
to be expanded to explicitly show some of the flexibility available
(e.g. w04 w08 w12 w16 in a spec.)

Schedule {
Name = "Test"
# Time spec only  
Run = hourly     
Run = at 00:00  
Run = at 11:00am 
Run = at 11:00pm
# Date spec only
Run = daily monthly weekly w01
Run = on 1 monthly weekly w01
Run = 1-3 monthly weekly w01
Run = 30-5 monthly weekly w01
Run = on 1 5 7 monthly weekly w01
Run = daily Jan weekly w01      
Run = daily Jan-Feb weekly w01 
Run = daily Dec-Jan weekly w01
Run = daily Jan Dec Mar weekly w01
Run = daily monthly Monday w01
Run = daily monthly Monday-Wednesday w01
Run = daily monthly Wednesday-Sunday w01
Run = daily monthly Wednesday Thursday Friday w01
Run = daily monthly weekly w01-w04
Run = daily monthly weekly w50-w03
Run = daily monthly weekly w01 w04 w06
# Date and time spec 
Run = daily monthly weekly w01 hourly
Run = daily monthly weekly w01 at 11:00
# Let's go crazy!
Run = daily 1 Jan w01 weekly 3 w04 Feb Monday hourly 5-7 Mar-Apr w05-w09 
Tuesday-Friday
}

[1] http://www.mail-archive.com/bacula-users AT lists.sourceforge DOT 
net/msg35440.html

bacula.documentation.patch.txt
Description: Text document

------------------------------------------------------------------------------
The ultimate all-in-one performance toolkit: Intel(R) Parallel Studio XE:
Pinpoint memory and threading errors before they happen.
Find and fix more than 250 security defects in the development cycle.
Locate bottlenecks in serial and parallel code that limit performance.
http://p.sf.net/sfu/intel-dev2devfeb

_______________________________________________
Bacula-users mailing list
Bacula-users AT lists.sourceforge DOT net
https://lists.sourceforge.net/lists/listinfo/bacula-users

[Bacula-users] Proposed documentation patch regarding Date-time-specification