Sync with ikiwiki 3.20100704.

22 files changed, 338 insertions, 60 deletions

diff --git a/ikiwiki/directive/aggregate.mdwn b/ikiwiki/directive/aggregate.mdwn
index 70174f4..ddfcd40 100644
--- a/ikiwiki/directive/aggregate.mdwn
+++ b/ikiwiki/directive/aggregate.mdwn
@@ -19,6 +19,11 @@ more aggregated feeds. For example:
 
 	\[[!inline pages="internal(example/*)"]]
 
+Note the use of `internal()` in the [[ikiwiki/PageSpec]] to match
+aggregated pages. By default, aggregated pages are internal pages,
+which prevents them from showing up directly in the wiki, and so this
+special [[PageSpec]] is needed to match them.
+
 ## usage
 
 Here are descriptions of all the supported parameters to the `aggregate`
diff --git a/ikiwiki/directive/calendar.mdwn b/ikiwiki/directive/calendar.mdwn
index 8a257d6..e9216e1 100644
--- a/ikiwiki/directive/calendar.mdwn
+++ b/ikiwiki/directive/calendar.mdwn
@@ -1,5 +1,4 @@
 The `calendar` directive is supplied by the [[!iki plugins/calendar desc=calendar]] plugin.
-This plugin requires extra setup.  See the plugin documentation for details.
 
 This directive displays a calendar, similar to the typical calendars shown on
 some blogs.
@@ -12,16 +11,28 @@ some blogs.
 
 	\[[!calendar type="year" year="2005" pages="blog/* and !*/Discussion"]]
 
+## setup
+
 The calendar is essentially a fancy front end to archives of previous
 pages, usually used for blogs. It can produce a calendar for a given month,
-or a list of months for a given year.
+or a list of months for a given year. The month format calendar simply
+links to any page posted on each day of the month. The year format calendar
+links to archive pages, with names like `archives/2007` (for all of 2007)
+and `archives/2007/01` (for January, 2007).
+
+While you can insert calendar directives anywhere on your wiki, including
+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. An example crontab:
+
+An example crontab:
 
-The month format calendar simply links to any page posted on each
-day of the month. The year format calendar links to archive pages, with
-names like `archives/2007` (for all of 2007)  and `archives/2007/01`
-(for January, 2007). For this to work, you'll need to create these archive
-pages. They typically use [[inline]] to display or list pages created in
-the given time frame.
+	0 0 * * * ikiwiki-calendar ~/ikiwiki.setup "posts/* and !*/Discussion"
 
 ## usage
 
@@ -29,18 +40,21 @@ the given time frame.
   "month" or "year". The default is a month view calendar.
 * `pages` - Specifies the [[ikiwiki/PageSpec]] of pages to link to from the
   month calendar. Defaults to "*".
-* `archivebase` - Configures the base of the archives hierarchy. The
-  default is "archives". Note that this default can also be overridden
+* `archivebase` - Configures the base of the archives hierarchy. 
+  The default is "archives". Note that this default can also be overridden
   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. 
 * `year` - The year for which the calendar is requested. Defaults to the
-  current year.
+  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
   range 1..12. Used only for the month view calendar, and defaults to the
-  current month.
+  current month. Can also use -1 to refer to last month, and so on.
 * `week_start_day` - A number, in the range 0..6, which represents the day
   of the week that the month calendar starts with. 0 is Sunday, 1 is Monday,
   and so on. Defaults to 0, which is Sunday.
-* `months_per_row` - In the annual calendar, number of months to place in
+* `months_per_row` - In the year calendar, number of months to place in
   each row. Defaults to 3.
 
 [[!meta robots="noindex, follow"]]
diff --git a/ikiwiki/directive/comment.mdwn b/ikiwiki/directive/comment.mdwn
new file mode 100644
index 0000000..398130e
--- /dev/null
+++ b/ikiwiki/directive/comment.mdwn
@@ -0,0 +1,40 @@
+The `comment` directive is supplied by the
+[[!iki plugins/comments desc=comments]] plugin, and is used to add a comment
+to a page. Typically, the directive is the only thing on a comment page,
+and is filled out by the comment plugin when a user posts a comment.
+
+Example:
+
+	\[[!comment format=mdwn
+	username="foo"
+	subject="Bar"
+	date="2009-06-02T19:05:01Z"
+	content="""
+	Blah blah.
+	"""
+	]]
+
+## usage
+
+The only required parameter is `content`, the others just add or override
+metadata of the comment.
+
+* `content` - Text to display for the comment.
+  Note that [[directives|ikiwiki/directive]]
+  may not be allowed, depending on the configuration
+  of the comment plugin.
+* `format` - Specifies the markup used for the content.
+* `subject` - Subject for the comment.
+* `date` - Date the comment was posted. Can be entered in
+  nearly any format, since it's parsed by [[!cpan TimeDate]]
+* `username` - Used to record the username (or OpenID)
+  of a logged in commenter.
+* `nickname` - Name to display for a logged in commenter.
+  (Optional; used for OpenIDs.)
+* `ip` - Can be used to record the IP address of a commenter,
+  if they posted anonymously.
+* `claimedauthor` - Records the name that the user entered,
+  if anonymous commenters are allowed to enter their (unverified)
+  name.
+
+[[!meta robots="noindex, follow"]]
diff --git a/ikiwiki/directive/cutpaste.mdwn b/ikiwiki/directive/cutpaste.mdwn
index 012367b..ca580e5 100644
--- a/ikiwiki/directive/cutpaste.mdwn
+++ b/ikiwiki/directive/cutpaste.mdwn
@@ -17,11 +17,11 @@ follow the paste directive that uses its text.  In fact, this is quite useful
 to postpone big blocks of text like long annotations and have a more natural
 flow.  For example:
 
-	\[[!toggleable id="cut" text="\[[!paste id=cutlongdesc]]"]]
-	\[[!toggleable id="copy" text="\[[!paste id=copylongdesc]]"]]
-	\[[!toggleable id="paste" text="\[[!paste id=pastelongdesc]]"]]
+	\[[!toggleable id="cut" text="[[!paste id=cutlongdesc]]"]]
+	\[[!toggleable id="copy" text="[[!paste id=copylongdesc]]"]]
+	\[[!toggleable id="paste" text="[[!paste id=pastelongdesc]]"]]
 
-	\[...some time later...]
+	[...some time later...]
 
 	\[[!cut id=cutlongdesc text="""
 	   blah blah blah
@@ -40,7 +40,7 @@ Since you can paste without using double quotes, copy and paste can be used to
 nest directives that require multiline parameters inside each other:
 
 	\[[!toggleable id=foo text="""
-	  \[[!toggleable id=bar text="\[[!paste id=baz]]"]]
+	  [[!toggleable id=bar text="[[!paste id=baz]]"]]
 	"""]]
 
 	\[[!cut id=baz text="""
diff --git a/ikiwiki/directive/date.mdwn b/ikiwiki/directive/date.mdwn
new file mode 100644
index 0000000..b89241e
--- /dev/null
+++ b/ikiwiki/directive/date.mdwn
@@ -0,0 +1,16 @@
+The `date` directive is supplied by the [[!iki plugins/date desc=date]] plugin.
+
+This directive can be used to display a date on a page, using the same
+display method that is used to display the modification date in the page
+footer, and other dates in the wiki. This can be useful for consistency
+of display, or if you want to embed parseable dates into the page source.
+
+Like the dates used by the [[meta]] directive, the date can be entered in
+nearly any format, since it's parsed by [[!cpan TimeDate]].
+
+For example, an update to a page with an embedded date stamp could look
+like:
+
+	Updated \[[!date "Wed, 25 Nov 2009 01:11:55 -0500"]]: mumble mumble
+
+[[!meta robots="noindex, follow"]]
diff --git a/ikiwiki/directive/edittemplate.mdwn b/ikiwiki/directive/edittemplate.mdwn
index d731bdb..c486e82 100644
--- a/ikiwiki/directive/edittemplate.mdwn
+++ b/ikiwiki/directive/edittemplate.mdwn
@@ -21,7 +21,7 @@ something like:
 	Details:
 
 The template page can also contain [[!cpan HTML::Template]] directives,
-similar to other ikiwiki [[templates]]. Currently only one variable is
+like other ikiwiki [[templates]]. Currently only one variable is
 set: `<TMPL_VAR name>` is replaced with the name of the page being
 created.
 
diff --git a/ikiwiki/directive/format.mdwn b/ikiwiki/directive/format.mdwn
new file mode 100644
index 0000000..7d11d22
--- /dev/null
+++ b/ikiwiki/directive/format.mdwn
@@ -0,0 +1,29 @@
+The `format` directive is supplied by the [[!iki plugins/format desc=format]]
+plugin.
+
+The directive allows formatting a chunk of text using any available page
+format. It takes two parameters. First is the type of format to use,
+ie the extension that would be used for a standalone file of this type.
+Second is the text to format.
+
+For example, this will embed an otl outline inside a page using mdwn or
+some other format:
+
+	\[[!format otl """
+	foo
+		1
+		2
+	bar
+		3
+		4
+	"""]]
+
+Note that if the highlight plugin is enabled, this directive can also be
+used to display syntax highlighted code. Many languages and formats are
+supported. For example:
+
+	\[[!format perl """
+	print "hello, world\n";
+	"""]]
+
+[[!meta robots="noindex, follow"]]
diff --git a/ikiwiki/directive/img.mdwn b/ikiwiki/directive/img.mdwn
index 1d1f29b..cda62b5 100644
--- a/ikiwiki/directive/img.mdwn
+++ b/ikiwiki/directive/img.mdwn
@@ -18,11 +18,12 @@ making the image smaller than the specified size. You can also specify only
 the width or the height, and the other value will be calculated based on
 it: "200x", "x200"
 
-You can also pass `alt`, `title`, `class` and `id` parameters. These are
-passed through unchanged to the html img tag. If you include a `caption`
-parameter, the caption will be displayed centered beneath the image.
+You can also pass `alt`, `title`, `class`, `align`, `id`, `hspace`, and
+`vspace` parameters.
+These are passed through unchanged to the html img tag. If you include a
+`caption` parameter, the caption will be displayed centered beneath the image.
 
-The `link` parameter is used to control whether the scaled down image links
+The `link` parameter is used to control whether the scaled image links
 to the full size version. By default it does; set "link=somepage" to link
 to another page instead, or "link=no" to disable the link, or
 "link=http://url" to link to a given url.
diff --git a/ikiwiki/directive/inline.mdwn b/ikiwiki/directive/inline.mdwn
index 9889cda..c6a23ce 100644
--- a/ikiwiki/directive/inline.mdwn
+++ b/ikiwiki/directive/inline.mdwn
@@ -56,7 +56,7 @@ directive. These are the commonly used ones:
 * `postform` - Set to "yes" to enable a form to post new pages to a
   blog.
 * `postformtext` - Set to specify text that is displayed in a postform.
-* `rootpage` - Enable the postform, and allows controling where
+* `rootpage` - Enables the postform, and allows controling where
   newly posted pages should go, by specifiying the page that
   they should be a [[SubPage]] of.
 
@@ -73,35 +73,47 @@ Here are some less often needed parameters:
   configured to `allowatom`, set to "yes" to enable.
 * `feeds` - controls generation of all types of feeds. Set to "no" to
   disable generating any feeds.
+* `emptyfeeds` - Set to "no" to disable generation of empty feeds.
+  Has no effect if `rootpage` or `postform` is set.
 * `template` - Specifies the template to fill out to display each inlined
   page. By default the `inlinepage` template is used, while
   the `archivepage` template is used for archives. Set this parameter to
   use some other, custom template, such as the `titlepage` template that
-  only shows post titles. Note that you should still set `archive=yes` if
+  only shows post titles or the `microblog` template, optimised for
+  microblogging. Note that you should still set `archive=yes` if
   your custom template does not include the page content.
 * `raw` - Rather than the default behavior of creating a blog,
   if raw is set to "yes", the page will be included raw, without additional
   markup around it, as if it were a literal part of the source of the 
   inlining page.
-* `sort` - Controls how inlined pages are sorted. The default, "age" is to
-  sort newest created pages first. Setting it to "title" will sort pages by
-  title, and "mtime" sorts most recently modified pages first.
+* `sort` - Controls how inlined pages are [[sorted|pagespec/sorting]].
+  The default is to sort the newest created pages first.
 * `reverse` - If set to "yes", causes the sort order to be reversed.
 * `feedshow` - Specify the maximum number of matching pages to include in
   the rss/atom feeds. The default is the same as the `show` value above.
 * `feedonly` - Only generate the feed, do not display the pages inline on
   the page.
 * `quick` - Build archives in quick mode, without reading page contents for
-  metadata. By default, this also turns off generation of any feeds.
+  metadata. This also turns off generation of any feeds.
 * `timeformat` - Use this to specify how to display the time or date for pages
   in the blog. The format string is passed to the strftime(3) function.
 * `feedpages` - A [[PageSpec]] of inlined pages to include in the rss/atom
   feeds. The default is the same as the `pages` value above, and only pages
-  matches by that value are included, but some of those can be excluded by
+  matched by that value are included, but some of those can be excluded by
   specifying a tighter [[PageSpec]] here.
 * `guid` - If a URI is given here (perhaps a UUID prefixed with `urn:uuid:`),
   the Atom feed will have this as its `<id>`. The default is to use the URL
   of the page containing the `inline` directive.
+* `feedfile` - Can be used to change the name of the file generated for the
+  feed. This is particularly useful if a page contains multiple feeds.
+  For example, set "feedfile=feed" to cause it to generate `page/feed.atom`
+  and/or `page/feed.rss`. This option is not supported if the wiki is
+  configured not to use `usedirs`.
+* `pagenames` - If given instead of `pages`, this is interpreted as a
+  space-separated list of links to pages (with the same
+  [[SubPage/LinkingRules]] as in a [[ikiwiki/WikiLink]]), and they are inlined
+  in exactly the order given: the `sort` and `pages` parameters cannot be used
+  in conjunction with this one.
 
 [[!meta robots="noindex, follow"]]
 
diff --git a/ikiwiki/directive/linkmap.mdwn b/ikiwiki/directive/linkmap.mdwn
index 8fdf40c..baa6fff 100644
--- a/ikiwiki/directive/linkmap.mdwn
+++ b/ikiwiki/directive/linkmap.mdwn
@@ -7,11 +7,7 @@ graph showing the links between a set of pages in the wiki. Example usage:
 
 Only links between mapped pages will be shown; links pointing to or from
 unmapped pages will be omitted. If the pages to include are not specified,
-the links between all pages (and other files) in the wiki are mapped. For
-best results, only a small set of pages should be mapped, since otherwise
-the map can become very large, unweildy, and complicated. Also, the map is
-rebuilt whenever one of the mapped pages is changed, which can make the
-wiki a bit slow.
+the links between all pages (and other files) in the wiki are mapped. 
 
 Here are descriptions of all the supported parameters to the `linkmap`
 directive:
@@ -20,5 +16,14 @@ directive:
 * `height`, `width` - Limit the size of the map to a given height and width,
   in inches. Both must be specified for the limiting to take effect, otherwise
   the map's size is not limited.
+* `connected` - Controls whether to include pages on the map that link to
+  no other pages (connected=no, the default), or to only show pages that
+  link to others (connected=yes).
+
+For best results, only a small set of pages should be mapped, since
+otherwise the map can become very large, unwieldy, and complicated.
+If too many pages are included, the map may get so large that graphviz
+cannot render it. Using the `connected` parameter is a good way to prune
+out pages that clutter the map.
 
 [[!meta robots="noindex, follow"]]
diff --git a/ikiwiki/directive/map.mdwn b/ikiwiki/directive/map.mdwn
index 09c95a0..4b64995 100644
--- a/ikiwiki/directive/map.mdwn
+++ b/ikiwiki/directive/map.mdwn
@@ -13,6 +13,8 @@ the [[meta]] directive). For example:
 
 	\[[!map pages="* and !blog/* and !*/Discussion" show=title]]
 
+	\[[!map pages="* and !blog/* and !*/Discussion" show=description]]
+
 Hint: To limit the map to displaying pages less than a certain level deep,
 use a [[ikiwiki/PageSpec]] like this: `pages="* and !*/*/*"`
 
diff --git a/ikiwiki/directive/meta.mdwn b/ikiwiki/directive/meta.mdwn
index 74db319..5a3919d 100644
--- a/ikiwiki/directive/meta.mdwn
+++ b/ikiwiki/directive/meta.mdwn
@@ -23,6 +23,13 @@ Supported fields:
   be set to a true value in the template; this can be used to format things
   differently in this case.
 
+  An optional `sortas` parameter will be used preferentially when
+  [[ikiwiki/pagespec/sorting]] by `meta(title)`:
+
+	\[[!meta title="The Beatles" sortas="Beatles, The"]]
+
+	\[[!meta title="David Bowie" sortas="Bowie, David"]]
+
 * license
 
   Specifies a license for the page, for example, "GPL". Can contain
@@ -37,14 +44,19 @@ Supported fields:
 
   Specifies the author of a page.
 
+  An optional `sortas` parameter will be used preferentially when
+  [[ikiwiki/pagespec/sorting]] by `meta(author)`:
+
+	\[[!meta author="Joey Hess" sortas="Hess, Joey"]]
+
 * authorurl
 
   Specifies an url for the author of a page.
 
 * description
 
-  Specifies a "description" of the page. You could use this to provide
-  a summary, for example, to be picked up by the [[map]] directive.
+  Specifies a short description for the page. This will be put in
+  the html header, and can also be displayed by eg, the [[map]] directive.
 
 * permalink
 
@@ -68,11 +80,16 @@ Supported fields:
 * openid
 
   Adds html &lt;link&gt; tags to perform OpenID delegation to an external
-  OpenID server (for `openid` and `openid2`). An optional `xrds-location`
+  OpenID server. This lets you use an ikiwiki page as your OpenID.
+
+  By default this will delegate for both `openid` and `openid2`. To only
+  delegate for one, add a parameter such as `delegate=openid`.
+
+  An optional `xrds-location`
   parameter lets you specify the location of any [eXtensible Resource
   DescriptorS](http://www.windley.com/archives/2007/05/using_xrds.shtml).
 
-  This lets you use an ikiwiki page as your OpenID. Example:
+  Example:
 
 	\\[[!meta openid="http://joeyh.myopenid.com/"
 	server="http://www.myopenid.com/server"
@@ -139,6 +156,15 @@ Supported fields:
   pages unchanged and avoid_flooding_aggregators
   (see [[!iki tips/howto_avoid_flooding_aggregators]]).
 
+* updated
+
+  Specifies a fake modification time for a page, to be output into RSS and
+  Atom feeds. This is useful to avoid flooding aggregators that sort by
+  modification time, like Planet: for instance, when editing an old blog post
+  to add tags, you could set `updated` to be one second later than the original
+  value. The date/time can be given in any format that
+  [[!cpan TimeDate]] can understand, just like the `date` field.
+
 If the field is not one of the above predefined fields, the metadata will be
 written to the generated html page as a &lt;meta&gt; header. However, this
 won't be allowed if the [[!iki plugins/htmlscrubber desc=htmlscrubber]] plugin is enabled,
diff --git a/ikiwiki/directive/pagestats.mdwn b/ikiwiki/directive/pagestats.mdwn
index cfb5737..d0e0e7b 100644
--- a/ikiwiki/directive/pagestats.mdwn
+++ b/ikiwiki/directive/pagestats.mdwn
@@ -4,12 +4,37 @@ This directive can generate stats about how pages link to each other. It can
 produce either a tag cloud, or a table counting the number of links to each
 page.
 
-Here's how to use it to create a [[tag]] cloud:
+Here's how to use it to create a [[tag]] cloud, with tags sized based
+on frequency of use:
 
 	\[[!pagestats pages="tags/*"]]
 
+Here's how to create a list of tags, sized by use as they would be in a
+cloud.
+	
+	\[[!pagestats style="list" pages="tags/*"]]
+
 And here's how to create a table of all the pages on the wiki:
 
 	\[[!pagestats style="table"]]
 
+The optional `among` parameter limits the pages whose outgoing links are
+considered. For instance, to display a cloud of tags used on blog
+entries, while ignoring other pages that use those tags, you could use:
+
+	\[[!pagestats pages="tags/*" among="blog/posts/*"]]
+
+Or to display a cloud of tags related to Linux, you could use:
+
+	\[[!pagestats pages="tags/* and not tags/linux" among="tagged(linux)"]]
+
+The optional `show` parameter limits display to the specified number of
+pages. For instance, to show a table of the top ten pages with the most
+links:
+
+	\[[!pagestats style="table" show="10"]]
+
+The optional `class` parameter can be used to control the class
+of the generated tag cloud `div` or page stats `table`.
+
 [[!meta robots="noindex, follow"]]
diff --git a/ikiwiki/directive/pagetemplate.mdwn b/ikiwiki/directive/pagetemplate.mdwn
index 0e4066f..401b380 100644
--- a/ikiwiki/directive/pagetemplate.mdwn
+++ b/ikiwiki/directive/pagetemplate.mdwn
@@ -1,15 +1,13 @@
 The `pagetemplate` directive is supplied by the [[!iki plugins/pagetemplate desc=pagetemplate]] plugin.
 
-This directive allows a page to be created using a different wikitemplates.
+This directive allows a page to be displayed using a different
+[[template|templates]] than the default `page.tmpl` template.
+
 The page text is inserted into the template, so the template controls the
 overall look and feel of the wiki page. This is in contrast to the
 [[ikiwiki/directive/template]] directive, which allows inserting templates
 _into_ the body of a page.
 
-This directive can only reference templates that are already installed
-by the system administrator, typically into the
-`/usr/share/ikiwiki/templates` directory. Example:
-
 	\[[!pagetemplate template="my_fancy.tmpl"]]
 
 [[!meta robots="noindex, follow"]]
diff --git a/ikiwiki/directive/postsparkline.mdwn b/ikiwiki/directive/postsparkline.mdwn
index c17d329..318512e 100644
--- a/ikiwiki/directive/postsparkline.mdwn
+++ b/ikiwiki/directive/postsparkline.mdwn
@@ -15,7 +15,7 @@ This directive uses the [[!iki plugins/sparkline desc=sparkline]] plugin to crea
 
 # usage
 
-All options aside fron the `pages`, `max`, `formula`, `time`, and `color`
+All options aside from the `pages`, `max`, `formula`, `time`, and `color`
 options are the same as in [[sparkline]] directive.
 
 You don't need to specify any data points (though you can if you want to).
@@ -24,7 +24,7 @@ times of pages matched by the specified `pages` [[ikiwiki/PageSpec]]. A
 maximum of `max` data points will be generated.
 
 The `formula` parameter controls the formula used to generate data points.
-Available forumlae:
+Available formulae:
 
 * `interval` - The height of each point represents how long it has been
   since the previous post.
@@ -32,10 +32,10 @@ Available forumlae:
   many posts were made that day.
 * `permonth` - Each point represents a month; the height represents how
   many posts were made that month.
-* `peryear` - Each point represents a day; the height represents how
+* `peryear` - Each point represents a year; the height represents how
   many posts were made that year.
 
-The `time` parameter has a default value of "ctime", since forumae use
+The `time` parameter has a default value of "ctime", since formulae use
 the creation times of pages by default. If you instead want
 them to use the modification times of pages, set it to "mtime".
 
diff --git a/ikiwiki/directive/sidebar.mdwn b/ikiwiki/directive/sidebar.mdwn
new file mode 100644
index 0000000..599695d
--- /dev/null
+++ b/ikiwiki/directive/sidebar.mdwn
@@ -0,0 +1,20 @@
+The `sidebar` directive is supplied by the [[!iki plugins/sidebar desc=sidebar]] plugin.
+
+This directive can specify a custom sidebar to display on the page,
+overriding any sidebar that is displayed globally.
+
+If no custom sidebar content is specified, it forces the sidebar page to
+be used as the sidebar, even if the `global_sidebars` setting has been
+used to disable use of the sidebar page by default.
+
+## examples
+
+	\[[!sidebar content="""
+	This is my custom sidebar for this page.
+
+	\[[!calendar pages="posts/*"]]
+	"""]]
+
+	\[[!sidebar]]
+
+[[!meta robots="noindex, follow"]]
diff --git a/ikiwiki/directive/sparkline.mdwn b/ikiwiki/directive/sparkline.mdwn
index 1f691e1..e5a03f8 100644
--- a/ikiwiki/directive/sparkline.mdwn
+++ b/ikiwiki/directive/sparkline.mdwn
@@ -2,7 +2,7 @@ The `sparkline` directive is supplied by the [[!iki plugins/sparkline desc=spark
 
 This directive allows for embedding sparklines into wiki pages. A
 sparkline is a small word-size graphic chart, that is designed to be
-displayes alongside text.
+displayed alongside text.
 
 # examples
 
diff --git a/ikiwiki/directive/table.mdwn b/ikiwiki/directive/table.mdwn
index e27a94b..a6692f9 100644
--- a/ikiwiki/directive/table.mdwn
+++ b/ikiwiki/directive/table.mdwn
@@ -6,8 +6,8 @@ or DSV (delimiter-separated values) format.
 ## examples
 
 	\[[!table data="""
-	Customer|Amount
-	Fulanito|134,34
+	Customer |Amount
+	Fulanito |134,34
 	Menganito|234,56
 	Menganito|234,56
 	"""]]
@@ -42,4 +42,9 @@ cells. For example:
   as the table header. Set it to "no" to make a table without a header, or
   "column" to make the first column be the header.
 
+For tab-delimited tables (often obtained by copying and pasting from HTML
+or a spreadsheet), `delimiter` must be set to a literal tab character. These
+are difficult to type in most web browsers - copying and pasting one from
+the table data is likely to be the easiest way.
+
 [[!meta robots="noindex, follow"]]
diff --git a/ikiwiki/directive/tag.mdwn b/ikiwiki/directive/tag.mdwn
index 267aee6..c8d9b98 100644
--- a/ikiwiki/directive/tag.mdwn
+++ b/ikiwiki/directive/tag.mdwn
@@ -19,12 +19,17 @@ instead:
 Note that if the wiki is configured to use a tagbase, then the tags will be
 located under a base directory, such as "tags/". This is a useful way to
 avoid having to write the full path to tags, if you want to keep them
-grouped together out of the way.
+grouped together out of the way. Also, since ikiwiki then knows where to put
+tags, it will automatically create tag pages when new tags are used.
+
+Bear in mind that specifying a tagbase means you will need to incorporate it
+into the `link()` [[ikiwiki/PageSpec]] you use: e.g., if your tagbase is
+`tag`, you would match pages tagged "foo" with `link(tag/foo)`.
 
 If you want to override the tagbase for a particular tag, you can use
 something like this:
 
-	\[[!tag ./foo]]
+	\[[!tag /foo]]
 	\[[!taglink /foo]]
 
 [[!meta robots="noindex, follow"]]
diff --git a/ikiwiki/directive/template.mdwn b/ikiwiki/directive/template.mdwn
index d538b69..6c50fa3 100644
--- a/ikiwiki/directive/template.mdwn
+++ b/ikiwiki/directive/template.mdwn
@@ -1,18 +1,87 @@
 The `template` directive is supplied by the [[!iki plugins/template desc=template]] plugin.
 
-[[Templates]] are files that can be filled out and inserted into pages in the
-wiki, by using the template directive. The directive has an `id` parameter
+The template directive allows wiki pages to be used as templates.
+These templates can be filled out and inserted into other pages in the
+wiki using the directive. The [[templates]] page lists templates
+that can be used with this directive.
+
+The directive has an `id` parameter
 that identifies the template to use. The remaining parameters are used to
 fill out the template.
 
-Example:
+## Example
 
 	\[[!template id=note text="""Here is the text to insert into my note."""]]
 
 This fills out the `note` template, filling in the `text` field with
 the specified value, and inserts the result into the page.
 
-For a list of available templates, and details about how to create more,
-see the [[templates]] page.
+## Using a template
+
+Generally, a value can include any markup that would be allowed in the wiki
+page outside the template. Triple-quoting the value even allows quotes to
+be included in it. Combined with multi-line quoted values, this allows for
+large chunks of marked up text to be embedded into a template:
+
+        \[[!template id=foo name="Sally" color="green" age=8 notes="""
+        * \[[Charley]]'s sister.
+        * "I want to be an astronaut when I grow up."
+        * Really 8 and a half.
+        """]]
+
+## Creating a template
+
+The template is a regular wiki page, located in the `templates/`
+subdirectory inside the source directory of the wiki.
+
+(Alternatively, templates can be stored in a directory outside the wiki,
+as files with the extension ".tmpl".
+By default, these are searched for in `/usr/share/ikiwiki/templates`;
+the `templatedir` setting can be used to make another directory be searched
+first.)
+
+The template uses the syntax used by the [[!cpan HTML::Template]] perl
+module, which allows for some fairly complex things to be done. Consult its
+documentation for the full syntax, but all you really need to know are a
+few things:
+
+* Each parameter you pass to the template directive will generate a 
+  template variable. There are also some pre-defined variables like PAGE
+  and BASENAME.
+* To insert the value of a variable, use `<TMPL_VAR variable>`. Wiki markup
+  in the value will first be converted to html.
+* To insert the raw value of a variable, with wiki markup not yet converted
+  to html, use `<TMPL_VAR raw_variable>`.
+* To make a block of text conditional on a variable being set use
+  `<TMPL_IF variable>text</TMPL_IF>`.
+* To use one block of text if a variable is set and a second if it's not,
+  use `<TMPL_IF variable>text<TMPL_ELSE>other text</TMPL_IF>`
+
+Here's a sample template:
+
+        <span class="infobox">
+        Name: \[[<TMPL_VAR raw_name>]]<br />
+        Age: <TMPL_VAR age><br />
+        <TMPL_IF color>
+        Favorite color: <TMPL_VAR color><br />
+        <TMPL_ELSE>
+        No favorite color.<br />
+        </TMPL_IF>
+        <TMPL_IF notes>
+        <hr />
+        <TMPL_VAR notes>
+        </TMPL_IF>
+        </span>
+
+The filled out template will be formatted the same as the rest of the page
+that contains it, so you can include WikiLinks and all other forms of wiki
+markup in the template. Note though that such WikiLinks will not show up as
+backlinks to the page that uses the template.
+
+Note the use of "raw_name" inside the [[ikiwiki/WikiLink]] generator in the
+example above. This ensures that if the name contains something that might
+be mistaken for wiki markup, it's not converted to html before being
+processed as a [[ikiwiki/WikiLink]].
+
 
 [[!meta robots="noindex, follow"]]
diff --git a/ikiwiki/directive/teximg.mdwn b/ikiwiki/directive/teximg.mdwn
index e13d1ed..992a3f6 100644
--- a/ikiwiki/directive/teximg.mdwn
+++ b/ikiwiki/directive/teximg.mdwn
@@ -12,7 +12,7 @@ To scale the image, use height=x:
 	\[[!teximg code="\frac{1}{2}" height="17"]]
 	\[[!teximg code="\frac{1}{2}" height="8"]]
 
-If no height is choosen the default height 12 is used. Valid heights are: 8, 9,
+If no height is chosen the default height 12 is used. Valid heights are: 8, 9,
 10, 11, 12, 14, 17, 20. If another height is entered, the closest available
 height is used.
 
diff --git a/ikiwiki/directive/toc.mdwn b/ikiwiki/directive/toc.mdwn
index bf504da..bb1afa1 100644
--- a/ikiwiki/directive/toc.mdwn
+++ b/ikiwiki/directive/toc.mdwn
@@ -14,6 +14,12 @@ the `levels` parameter:
 The toc directive will take the level of the first header as the topmost
 level, even if there are higher levels seen later in the file.
 
+To create a table of contents that only shows headers starting with a given
+level, use the `startlevel` parameter. For example, to show only h2 and
+smaller headers:
+
+	\[[!toc startlevel=2]]
+
 The table of contents will be created as an ordered list. If you want
 an unordered list instead, you can change the list-style in your local
 style sheet.