From 94e0fe46bf5b4c112615a543d7bf4d3a19d06322 Mon Sep 17 00:00:00 2001
From: Markus Armbruster <armbru@pond.sub.org>
Date: Wed, 11 Jul 2007 22:34:21 +0000
Subject: [PATCH] Document the new update scheduler.

---
 doc/econfig  |  3 +++
 doc/schedule | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+)
 create mode 100644 doc/schedule

diff --git a/doc/econfig b/doc/econfig
index fbae49ed..0aa89f62 100644
--- a/doc/econfig
+++ b/doc/econfig
@@ -69,6 +69,9 @@ pconfig econfig2 > e2 && mv e2 econfig2
 
 which will fill in all the missing keys and values with their defaults.
 
+You define your update schedule in the schedule file, in the same
+directory as your econfig.  See doc/schedule for details.
+
 Additional customization is possible through key custom_tables, which
 is a list of files containing tables in xdump format (see doc/xdump
 for technical information on xdump).  To customize a table, copy the
diff --git a/doc/schedule b/doc/schedule
new file mode 100644
index 00000000..c3d70056
--- /dev/null
+++ b/doc/schedule
@@ -0,0 +1,51 @@
+This file documents how to configure update schedules.  The server
+reads its update schedule from the file schedule in the same directory
+as its econfig.
+
+Comments start with # and extend to the end of the line.
+
+Each non-blank line contains a directive.  Directives are:
+
+* Single update: a time.
+
+  Time can be specified in a number of formats:
+
+  - ISO 8601: 2007-05-28 16:13
+
+  - Like ctime: Dec 22 15:35 2006
+
+  - Like RFC 2822: 22 Dec 2006 15:35
+
+  - Relative to anchor: next Fri 15:35
+
+    The time of day is optional.  The anchor is the last update
+    defined by single update directives.  It defaults to the current
+    time rounded up to the next minute.
+
+* Repeating updates after anchor: every 24 hours, every 10 minutes
+
+  Does not change the anchor.
+
+  Optionally followed by a limit: until T, where T specifies a time.
+  An update precisely at T is within the limit.
+
+* Skip update: skip T, where T specifies a time.
+
+A blitz schedule can be defined with a single line:
+
+    every 10 minutes
+
+Here's how to schedule updates Monday, Wednesday and Friday at 20:00,
+starting June 1st 2007, skipping July 4th:
+
+    2007-06-01 20:00    # a Friday
+    every 168 hours
+    next mon
+    every 168 hours
+    next wed
+    every 168 hours
+    skip 2007-07-04 20:00
+
+The server reads the schedule file on startup, after an update, and on
+catching SIGHUP.  You can use the utility program prsched to test a
+schedule before you install it.