Merge remote-tracking branch 'spalax/calendar-autocreate'

3 files changed, 43 insertions, 7 deletions

diff --git a/doc/ikiwiki-calendar.mdwn b/doc/ikiwiki-calendar.mdwn
index d311a1859..fd3244694 100644
--- a/doc/ikiwiki-calendar.mdwn
+++ b/doc/ikiwiki-calendar.mdwn
@@ -46,6 +46,13 @@ An example crontab:
 This command uses two [[templates]] to generate
 the pages, `calendarmonth.tmpl` and `calendaryear.tmpl`.
 
+# [[plugins/calendar]] setup option
+
+Most of the goals of this command can be replaced by setting up
+`calendar_autocreate` setup option (of plugin [[plugins/calendar]]), and
+running `ikiwiki -setup you.setup`. The only thing that `ikiwiki-calendar` can
+do and that `ikiwiki` cannot is forcing page generation (using `-f` switch).
+
 # AUTHOR
 
 Joey Hess <joey@ikiwiki.info>
diff --git a/doc/ikiwiki/directive/calendar.mdwn b/doc/ikiwiki/directive/calendar.mdwn
index cb40f884e..412285c97 100644
--- a/doc/ikiwiki/directive/calendar.mdwn
+++ b/doc/ikiwiki/directive/calendar.mdwn
@@ -25,14 +25,22 @@ in the sidebar, you'll also need to create these archive pages. They
 typically use this directive to display a calendar, and also use [[inline]]
 to display or list pages created in the given time frame.
 
-The `ikiwiki-calendar` command can be used to automatically generate the
-archive pages. It also refreshes the wiki, updating the calendars to
-highlight the current day. This command is typically run at midnight from
-cron.
+## Generating archive pages
+
+If [[option|plugins/calendar]] `calendar_autocreate` is not set, the
+[[ikiwiki-calendar]] command can be used to automatically generate the archive
+pages. It also refreshes the wiki, updating the calendars to highlight the
+current day. This command is typically run at midnight from cron.
 
 An example crontab:
 
-	0 0 * * * ikiwiki-calendar ~/ikiwiki.setup "posts/* and !*/Discussion"
+    0 0 * * * ikiwiki-calendar ~/ikiwiki.setup "posts/* and !*/Discussion"
+
+
+With [[setup option|plugins/calendar]] `calendar_autocreate`, all this work is
+done by `ikiwiki` itself. Thus, the crontab command can be replaced by:
+
+    0 0 * * * ikiwiki --setup ~/ikiwiki.setup --refresh
 
 ## usage
 
@@ -45,7 +53,7 @@ An example crontab:
   for the whole wiki by setting `archivebase` in ikiwiki's setup file.
   Calendars link to pages under here, with names like "2010/04" and
   "2010". These pages can be automatically created using the
-  `ikiwiki-calendar` program. 
+  `calendar_autocreate` [[setup option|plugins/calendar]].
 * `year` - The year for which the calendar is requested. Defaults to the
   current year. Can also use -1 to refer to last year, and so on.
 * `month` - The numeric month for which the calendar is requested, in the
diff --git a/doc/plugins/calendar.mdwn b/doc/plugins/calendar.mdwn
index 76e718a3b..d55c21a62 100644
--- a/doc/plugins/calendar.mdwn
+++ b/doc/plugins/calendar.mdwn
@@ -5,7 +5,28 @@ This plugin provides a [[ikiwiki/directive/calendar]] [[ikiwiki/directive]].
 The directive displays a calendar, similar to the typical calendars shown on
 some blogs. 
 
-The [[ikiwiki-calendar]] command is used to keep the calendar up-to-date.
+The [[ikiwiki-calendar]] command is used to force generating year and month
+pages from templates (overriding the existing ones).
+
+## Setup options
+
+* `archivebase` - Default value for [[ikiwiki/directive/calendar]] directive
+  option of the same name.
+* `archive_pagespec` - [[ikiwiki/PageSpec]] of pages to include in the
+  archives, if option `calendar_autocreate` is on. It defaults to `*`.
+* `calendar_autocreate` - Control whether new archive pages are created as
+  needed. It defaults to being done only if option `archivebase` is set.
+* `calendar_fill_gaps` - If set (and `calendar_autocreate` is set as well),
+  build calendar pages of emty years and months (but does not build pages older
+  than the older page, and younger than the younger page of the pagespec). If
+  not, thoses empty calendar pages will be skipped. *Please note:*
+  * The archive pages will not be automatically updated if this option changes.
+    It is up to the user to delete relevant pages, and rebuild the wiki.
+  * When `calendar_fill_gaps` is set, and post is deleted, making the
+    corresponding year/month empty, the corresponding page is left, and shows
+    an empty calendar. This is on purpose, not to break any external link
+    pointing to this particular page. If you do not like it, delete the
+    relevant pages, and rebuild the wiki.
 
 ## CSS