Merge branch 'master' of git://git.ikiwiki.info

36 files changed, 420 insertions, 97 deletions

diff --git a/doc/ikiwiki/directive/brokenlinks/discussion.mdwn b/doc/ikiwiki/directive/brokenlinks/discussion.mdwn
new file mode 100644
index 000000000..34760584d
--- /dev/null
+++ b/doc/ikiwiki/directive/brokenlinks/discussion.mdwn
@@ -0,0 +1,3 @@
+Would it be possible to have such a thing also checking for external links? -- [[user/emptty]]
+
+> I guess this is not very practical.  For internal wiki links, we only need to check if the linked source file exist or not.  But for external links, we have to ping every links, which will slow down the build process a lot.  --[[weakish]]
diff --git a/doc/ikiwiki/directive/calendar.mdwn b/doc/ikiwiki/directive/calendar.mdwn
index 8a257d6eb..cb40f884e 100644
--- a/doc/ikiwiki/directive/calendar.mdwn
+++ b/doc/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:
 
-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/doc/ikiwiki/directive/comment.mdwn b/doc/ikiwiki/directive/comment.mdwn
index 21386dfc3..398130e2e 100644
--- a/doc/ikiwiki/directive/comment.mdwn
+++ b/doc/ikiwiki/directive/comment.mdwn
@@ -29,10 +29,12 @@ metadata of the comment.
   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 anonmous commenters are allowed to enter their (unverified)
+  if anonymous commenters are allowed to enter their (unverified)
   name.
 
 [[!meta robots="noindex, follow"]]
diff --git a/doc/ikiwiki/directive/commentmoderation.mdwn b/doc/ikiwiki/directive/commentmoderation.mdwn
new file mode 100644
index 000000000..8553b5b17
--- /dev/null
+++ b/doc/ikiwiki/directive/commentmoderation.mdwn
@@ -0,0 +1,9 @@
+The `commentmoderation` directive is supplied by the
+[[!iki plugins/comments desc=comments]] plugin, and is used to link
+to the comment moderation queue.
+
+Example:
+
+	\[[!commentmoderation desc="here is the comment moderation queue"]]
+
+[[!meta robots="noindex, follow"]]
diff --git a/doc/ikiwiki/directive/date.mdwn b/doc/ikiwiki/directive/date.mdwn
new file mode 100644
index 000000000..b89241e4c
--- /dev/null
+++ b/doc/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/doc/ikiwiki/directive/edittemplate.mdwn b/doc/ikiwiki/directive/edittemplate.mdwn
index d731bdb47..c486e821b 100644
--- a/doc/ikiwiki/directive/edittemplate.mdwn
+++ b/doc/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/doc/ikiwiki/directive/flattr.mdwn b/doc/ikiwiki/directive/flattr.mdwn
new file mode 100644
index 000000000..5083005ce
--- /dev/null
+++ b/doc/ikiwiki/directive/flattr.mdwn
@@ -0,0 +1,45 @@
+The `flattr` directive is supplied by the [[!iki plugins/flattr desc=flattr]] plugin.
+
+This directive allows easily inserting Flattr buttons onto wiki pages.
+
+Flattr supports both static buttons and javascript buttons. This directive
+only creates dynamic javascript buttons. If you want to insert a static
+Flattr button, you can simply copy the html code for it from Flattr, instead.
+Note that this directive inserts javascript code into the page, that
+loads more javascript code from Flattr.com. So only use it if you feel
+comfortable with that.
+
+The directive can be used to display a button for a thing you have already
+manually submitted to Flattr. In this mode, the only parameter you need to
+include is the exact url to the thing that was submitted to Flattr.
+(If the button is for the current page, you can leave that out.) For
+example, this is the Flattr button for ikiwiki. Feel free to add it to all
+your pages. ;)
+
+	\[[!flattr url="http://ikiwiki.info/" button=compact]]
+
+The directive can also be used to create a button that automatically
+submits a page to Flattr when a user clicks on it. In this mode you
+need to include parameters to specify your uid, and a title, category, tags,
+and description for the page. For example, this is a Flattr button for
+a blog post:
+	
+	\[[!flattr uid=25634 title="my new blog post" category=text
+	tags="blog,example" description="This is a post on my blog."]]
+
+Here are all possible parameters you can pass to the Flattr directive.
+
+* `button` - Set to "compact" for a small button.
+* `url` - The url to the thing to be Flattr'd. If omitted, defaults
+  to the url of the current page.
+* `uid` - Your numeric Flattr userid. Not needed if the flattr plugin
+  has been configured with a global `flattr_userid`.
+* `title` - A short title for the thing, to show on its Flattr page.
+* `description` - A description of the thing, to show on its Flattr
+  page.
+* `category` - One of: text, images, video, audio, software, rest.
+* `tags` - A list of tags separated by a comma.
+* `language` - A language code.
+* `hidden` - Set to 1 to hide the button from listings on Flattr.com.
+
+[[!meta robots="noindex, follow"]]
diff --git a/doc/ikiwiki/directive/format.mdwn b/doc/ikiwiki/directive/format.mdwn
index 23830e9cd..7d11d225f 100644
--- a/doc/ikiwiki/directive/format.mdwn
+++ b/doc/ikiwiki/directive/format.mdwn
@@ -22,7 +22,7 @@ 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 """
+	\[[!format perl """
 	print "hello, world\n";
 	"""]]
 
diff --git a/doc/ikiwiki/directive/img.mdwn b/doc/ikiwiki/directive/img.mdwn
index 66efd008e..cda62b58f 100644
--- a/doc/ikiwiki/directive/img.mdwn
+++ b/doc/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`, `align` and `id` parameters.
+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/doc/ikiwiki/directive/inline.mdwn b/doc/ikiwiki/directive/inline.mdwn
index 9c55e07c2..c6a23ce3c 100644
--- a/doc/ikiwiki/directive/inline.mdwn
+++ b/doc/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.
 
@@ -86,19 +86,15 @@ Here are some less often needed parameters:
   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. If
-  [[!cpan Sort::Naturally]] is installed, `sort` can be set to "title_natural"
-  to sort by title with numbers treated as such ("1 2 9 10 20" instead of
-  "1 10 2 20 9").
+* `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
diff --git a/doc/ikiwiki/directive/inline/discussion.mdwn b/doc/ikiwiki/directive/inline/discussion.mdwn
index be0665d04..6a186cd93 100644
--- a/doc/ikiwiki/directive/inline/discussion.mdwn
+++ b/doc/ikiwiki/directive/inline/discussion.mdwn
@@ -1,3 +1,10 @@
+## Combine inline and toggle
+
+Is it possible to combine the behaviour of toggle and inline? ie, have it present of list of 'headlines' which are created from seperate subpages which can be clicked to expand to the body of the inlined page. Thanks.
+
+-- Thiana
+
+---
 ## How do you provide the per post discussion links in your own blog?
 
 > That's configured by the "actions" parameter to the inline directive. See
@@ -124,3 +131,23 @@ My index page has:
 Else can you please suggest a smarter way of getting certain data out from pages for a inline index?
 
 --[[hendry]]
+
+---
+
+## Interaction of `show` and `feedshow`
+
+Reading the documentation I would think that `feedshow` does not
+influence `show`.
+
+	\[[!inline pages="./blog/*" archive=yes quick=yes feedshow=10 sort=title reverse=yes]]
+
+Only ten pages are listed in this example although `archive` is set to
+yes. Removing `feedshow=10` all matching pages are shown.
+
+Is that behaviour intended?
+
+> Is something going wrong because `quick="yes"` [[»turns off generation of any feeds«|inline]]? --[[PaulePanter]]
+
+--[[PaulePanter]]
+
+>> Bug was that if feedshow was specified without show it limited to it incorrectly. Fixed. --[[Joey]] 
diff --git a/doc/ikiwiki/directive/linkmap.mdwn b/doc/ikiwiki/directive/linkmap.mdwn
index db79a1491..baa6fff61 100644
--- a/doc/ikiwiki/directive/linkmap.mdwn
+++ b/doc/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, unwieldy, 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/doc/ikiwiki/directive/map.mdwn b/doc/ikiwiki/directive/map.mdwn
index 09c95a0c9..4b6499547 100644
--- a/doc/ikiwiki/directive/map.mdwn
+++ b/doc/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/doc/ikiwiki/directive/map/discussion.mdwn b/doc/ikiwiki/directive/map/discussion.mdwn
index 062b4267a..b7ac17b1a 100644
--- a/doc/ikiwiki/directive/map/discussion.mdwn
+++ b/doc/ikiwiki/directive/map/discussion.mdwn
@@ -1,3 +1,14 @@
+### Sorting
+
+Is there a way to have the generated maps sorted by *title* instead of *filename* when show=title is used?
+Thanks 
+
+-- Thiana
+
+> [[bugs/map_sorts_by_pagename_and_not_title_when_show__61__title_is_used]] --[[Joey]] 
+
+----
+
 Question: Is there a way to generate a listing that shows *both* title and description meta information? Currently, a \[\[!map ...]] shows only one of the two, but I'd like to generate a navigation that looks like a description list. For example:
 
  * This is the title meta information.
@@ -72,3 +83,15 @@ Is there any way to do that?  I don't mind mucking around with `\[[!meta]]` on e
 >>> I think that the ideas and code in
 >>> [[todo/tracking_bugs_with_dependencies]] might also handle this case.
 >>> --[[Joey]]
+
+----
+
+I feel like this should be obvious, but I can't figure out how to sort numerically. 
+
+I have `map pages="./* and !*/Discussion and !*/sidebar"`  and a bunch of pages with names like 1, 2, 3, 11, 12, 1/1.1, 12/12.3 etc. I want to sort them numerically. I see lots of conversation implying there's a simple way to do it, but not how.
+
+> No, you can't: map can't currently use a non-default sort order. If it
+> could, then you could use [[plugins/sortnaturally]]. There's a
+> [[feature_request|todo/sort_parameter_for_map_plugin_and_directive]];
+> [[a_bug_references_it|bugs/map_sorts_by_pagename_and_not_title_when_show=title_is_used]].
+> --[[smcv]]
diff --git a/doc/ikiwiki/directive/meta.mdwn b/doc/ikiwiki/directive/meta.mdwn
index 000f461c9..1f5bde964 100644
--- a/doc/ikiwiki/directive/meta.mdwn
+++ b/doc/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
 
@@ -79,7 +91,7 @@ Supported fields:
 
   Example:
 
-	\\[[!meta openid="http://joeyh.myopenid.com/"
+	\[[!meta openid="http://joeyh.myopenid.com/"
 	server="http://www.myopenid.com/server"
 	xrds-location="http://www.myopenid.com/xrds?username=joeyh.myopenid.com""]]
 
diff --git a/doc/ikiwiki/directive/pagestats.mdwn b/doc/ikiwiki/directive/pagestats.mdwn
index 426f3e4af..d0e0e7be7 100644
--- a/doc/ikiwiki/directive/pagestats.mdwn
+++ b/doc/ikiwiki/directive/pagestats.mdwn
@@ -4,22 +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 counting to pages that match a
-[[ikiwiki/PageSpec]]. For instance, to display a cloud of tags used on blog
-entries, you could use:
+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:
+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/doc/ikiwiki/directive/pagestats/discussion.mdwn b/doc/ikiwiki/directive/pagestats/discussion.mdwn
index 3c9dc7104..99029e88e 100644
--- a/doc/ikiwiki/directive/pagestats/discussion.mdwn
+++ b/doc/ikiwiki/directive/pagestats/discussion.mdwn
@@ -7,4 +7,12 @@ I would rather not find and create a page for every tag I have created or will c
 
 Thanks
 
-----
+> Hello unknown person.
+
+> I think it would require a different approach to what "tags" are, and/or what "pagestats" are.  The pagestats plugin gives statistical information about *pages*, so it requires the pages in question to exist before it can get information about them.  The tags plugin creates links to tag *pages*, with the expectation that a human being will create said pages and put whatever content they want on them (such as describing what the tag is about, and a map linking back to the tagged pages).
+
+> The approach that [PmWiki](http://www.pmwiki.org) takes is that it enables the optional auto-creation of (empty) pages which match a particular "group" (set of sub-pages); thus one could set all the "tags/*" pages to be auto-created, creating a new tags/foo page the first time the \[[!tag foo]] directive is used. See [[todo/auto-create_tag_pages_according_to_a_template]] for more discussion on this idea.
+> -- [[KathrynAndersen]]
+
+> Update: Ikiwiki can auto-create tags now, though it only defaults to
+> doing so when tagbase is set. --[[Joey]] 
diff --git a/doc/ikiwiki/directive/pagetemplate.mdwn b/doc/ikiwiki/directive/pagetemplate.mdwn
index 0e4066f34..401b38099 100644
--- a/doc/ikiwiki/directive/pagetemplate.mdwn
+++ b/doc/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/doc/ikiwiki/directive/postsparkline.mdwn b/doc/ikiwiki/directive/postsparkline.mdwn
index a7cb6822a..318512eef 100644
--- a/doc/ikiwiki/directive/postsparkline.mdwn
+++ b/doc/ikiwiki/directive/postsparkline.mdwn
@@ -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/doc/ikiwiki/directive/sidebar.mdwn b/doc/ikiwiki/directive/sidebar.mdwn
new file mode 100644
index 000000000..599695d22
--- /dev/null
+++ b/doc/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/doc/ikiwiki/directive/sparkline.mdwn b/doc/ikiwiki/directive/sparkline.mdwn
index 1f691e14f..e5a03f84e 100644
--- a/doc/ikiwiki/directive/sparkline.mdwn
+++ b/doc/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/doc/ikiwiki/directive/table.mdwn b/doc/ikiwiki/directive/table.mdwn
index e27a94b7c..a6692f92c 100644
--- a/doc/ikiwiki/directive/table.mdwn
+++ b/doc/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/doc/ikiwiki/directive/tag.mdwn b/doc/ikiwiki/directive/tag.mdwn
index 64736f8cd..c8d9b9816 100644
--- a/doc/ikiwiki/directive/tag.mdwn
+++ b/doc/ikiwiki/directive/tag.mdwn
@@ -19,7 +19,8 @@ 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
@@ -28,7 +29,7 @@ into the `link()` [[ikiwiki/PageSpec]] you use: e.g., if your tagbase is
 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/doc/ikiwiki/directive/template.mdwn b/doc/ikiwiki/directive/template.mdwn
index d538b69b1..6c50fa32e 100644
--- a/doc/ikiwiki/directive/template.mdwn
+++ b/doc/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/doc/ikiwiki/directive/toc.mdwn b/doc/ikiwiki/directive/toc.mdwn
index bf504dafc..bb1afa1ac 100644
--- a/doc/ikiwiki/directive/toc.mdwn
+++ b/doc/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.
diff --git a/doc/ikiwiki/formatting.mdwn b/doc/ikiwiki/formatting.mdwn
index 2ed5cc26f..befbce9aa 100644
--- a/doc/ikiwiki/formatting.mdwn
+++ b/doc/ikiwiki/formatting.mdwn
@@ -7,7 +7,7 @@ called [[MarkDown]], and it works like this:
 
 Leave blank lines between paragraphs.
 
-You can \**emphasise*\* or \*\***strongly emphasise**\*\* text by placing it
+You can *\*emphasise\** or **\*\*strongly emphasise\*\*** text by placing it
 in single or double asterisks.
 
 To create a list, start each line with an asterisk:
diff --git a/doc/ikiwiki/openid.mdwn b/doc/ikiwiki/openid.mdwn
index a79655284..2fa972ede 100644
--- a/doc/ikiwiki/openid.mdwn
+++ b/doc/ikiwiki/openid.mdwn
@@ -9,16 +9,10 @@
 that allows you to have one login that you can use on a growing number of
 websites.
 
-To sign up for an OpenID, visit one of the following identity providers:
+If you have an account with some of the larger web service providers,
+you might already have an OpenID. 
+[Directory of OpenID providers](http://openiddirectory.com/openid-providers-c-1.html)
 
-* [MyOpenID](https://www.myopenid.com/)
-* [GetOpenID](https://getopenid.com/)
-* [Videntity](http://videntity.org/)
-* [LiveJournal](http://www.livejournal.com/openid/)
-* [TrustBearer](https://openid.trustbearer.com/)
-* or any of the [many others out there](http://openiddirectory.com/openid-providers-c-1.html)
-
-Your OpenID is the URL that you are given when you sign up.
 [[!if test="enabled(openid)" then="""
 To sign in to this wiki using OpenID, just enter it in the OpenID field in the
 signin form. You do not need to give this wiki a password or go through any
diff --git a/doc/ikiwiki/pagespec.mdwn b/doc/ikiwiki/pagespec.mdwn
index 5f0f44e2e..c66395f84 100644
--- a/doc/ikiwiki/pagespec.mdwn
+++ b/doc/ikiwiki/pagespec.mdwn
@@ -24,31 +24,35 @@ match all pages except for Discussion pages and the SandBox:
 
 Some more elaborate limits can be added to what matches using these functions:
 
+* "`glob(someglob)`" - matches pages and other files that match the given glob.
+  Just writing the glob by itself is actually a shorthand for this function.
+* "`page(glob)`" - like `glob()`, but only matches pages, not other files
 * "`link(page)`" - matches only pages that link to a given page (or glob)
 * "`tagged(tag)`" - matches pages that are tagged or link to the given tag (or
   tags matched by a glob)
 * "`backlink(page)`" - matches only pages that a given page links to
-* "`creation_month(month)`" - matches only pages created on the given month
+* "`creation_month(month)`" - matches only files created on the given month
 * "`creation_day(mday)`" - or day of the month
 * "`creation_year(year)`" - or year
-* "`created_after(page)`" - matches only pages created after the given page
+* "`created_after(page)`" - matches only files created after the given page
   was created
-* "`created_before(page)`" - matches only pages created before the given page
+* "`created_before(page)`" - matches only files created before the given page
   was created
-* "`glob(someglob)`" - matches pages that match the given glob. Just writing
-  the glob by itself is actually a shorthand for this function.
 * "`internal(glob)`" - like `glob()`, but matches even internal-use 
   pages that globs do not usually match.
 * "`title(glob)`", "`author(glob)`", "`authorurl(glob)`",
-  "`license(glob)`", "`copyright(glob)`" - match pages that have the given
-  metadata, matching the specified glob.
+  "`license(glob)`", "`copyright(glob)`", "`guid(glob)`" 
+  - match pages that have the given metadata, matching the specified glob.
 * "`user(username)`" - tests whether a modification is being made by a
   user with the specified username. If openid is enabled, an openid can also
-  be put here.
+  be put here. Glob patterns can be used in the username. For example, 
+  to match all openid users, use `user(*://*)`
 * "`admin()`" - tests whether a modification is being made by one of the
   wiki admins.
 * "`ip(address)`" - tests whether a modification is being made from the
   specified IP address.
+* "`comment(glob)`" - matches comments to a page matching the glob.
+* "`comment_pending(glob)`" - matches unmoderated, pending comments.
 * "`postcomment(glob)`" - matches only when comments are being 
   posted to a page matching the specified glob
 
diff --git a/doc/ikiwiki/pagespec/attachment.mdwn b/doc/ikiwiki/pagespec/attachment.mdwn
index 419f00ee4..fa2bc5867 100644
--- a/doc/ikiwiki/pagespec/attachment.mdwn
+++ b/doc/ikiwiki/pagespec/attachment.mdwn
@@ -7,11 +7,12 @@ If attachments are enabled, the wiki admin can control what types of
 attachments will be accepted, via the `allowed_attachments`
 configuration setting.
 
-For example, to limit arbitrary files to 50 kilobytes, but allow
-larger mp3 files to be uploaded by joey into a specific directory, and
-check all attachments for viruses, something like this could be used:
+For example, to limit most users to uploading small images, and nothing else,
+while allowing larger mp3 files to be uploaded by joey into a specific
+directory, and check all attachments for viruses, something like this could be
+used:
   
-	virusfree() and ((user(joey) and podcast/*.mp3 and mimetype(audio/mpeg) and maxsize(15mb)) or (!ispage() and maxsize(50kb)))
+	virusfree() and ((user(joey) and podcast/*.mp3 and mimetype(audio/mpeg) and maxsize(15mb)) or (mimetype(image/*) and maxsize(50kb)))
 
 The regular [[ikiwiki/PageSpec]] syntax is expanded with the following
 additional tests:
diff --git a/doc/ikiwiki/pagespec/discussion.mdwn b/doc/ikiwiki/pagespec/discussion.mdwn
index 4eed3722c..4c553925a 100644
--- a/doc/ikiwiki/pagespec/discussion.mdwn
+++ b/doc/ikiwiki/pagespec/discussion.mdwn
@@ -92,3 +92,14 @@ does not seem suitable for this, as
 > \[[!map pages="./*"]]
 
 also lists the current page and all its siblings.
+
+---
+
+I am a little lost. I want to match the start page `/index.mdwn`. So I use
+
+    \[[!inline pages="/index"]]
+
+which does not work though. I also tried it in this Wiki. Just take a look at the end of the [[SandBox|sandbox]]. --[[PaulePanter]]
+
+> Unlike wikilinks, pagespecs match relative to the top of the wiki by
+> default. So lose the "/" and it will work. --[[Joey]]
diff --git a/doc/ikiwiki/pagespec/po.mdwn b/doc/ikiwiki/pagespec/po.mdwn
index e0264dd50..f9956404c 100644
--- a/doc/ikiwiki/pagespec/po.mdwn
+++ b/doc/ikiwiki/pagespec/po.mdwn
@@ -11,6 +11,13 @@ wiki:
   specified as a ISO639-1 (two-letter) language code.
 * "`currentlang()`" - tests whether a page is written in the same
   language as the current page.
+* "`needstranslation()`" - tests whether a page needs translation
+  work. Only slave pages match this PageSpec. A minimum target
+  translation percentage can optionally be passed as an integer
+  parameter: "`needstranslation(50)`" matches only pages less than 50%
+  translated.
 
 Note that every non-po page is considered to be written in
 `po_master_language`, as specified in `ikiwiki.setup`.
+
+[[!meta robots="noindex, follow"]]
diff --git a/doc/ikiwiki/pagespec/sorting.mdwn b/doc/ikiwiki/pagespec/sorting.mdwn
new file mode 100644
index 000000000..ccd7f7eaa
--- /dev/null
+++ b/doc/ikiwiki/pagespec/sorting.mdwn
@@ -0,0 +1,26 @@
+Some [[directives|ikiwiki/directive]] that use
+[[PageSpecs|ikiwiki/pagespec]] allow
+specifying the order that matching pages are shown in. The following sort
+orders can be specified.
+
+* `age` - List pages from the most recently created to the oldest.
+
+* `mtime` - List pages with the most recently modified first.
+
+* `title` - Order by title (page name).
+[[!if test="enabled(sortnaturally)" then="""
+* `title_natural` - Orders by title, but numbers in the title are treated
+  as such, ("1 2 9 10 20" instead of "1 10 2 20 9")
+"""]]
+[[!if test="enabled(meta)" then="""
+* `meta(title)` - Order according to the `\[[!meta title="foo" sortas="bar"]]`
+  or `\[[!meta title="foo"]]` [[ikiwiki/directive]], or the page name if no
+  full title was set. `meta(author)`, `meta(date)`, `meta(updated)`, etc.
+  also work.
+"""]]
+
+In addition, you can combine several sort orders and/or reverse the order of
+sorting, with a string like `age -title` (which would sort by age, then by
+title in reverse order if two pages have the same age).
+
+[[!meta robots="noindex, follow"]]
diff --git a/doc/ikiwiki/searching.mdwn b/doc/ikiwiki/searching.mdwn
index 539e7193d..4c1287933 100644
--- a/doc/ikiwiki/searching.mdwn
+++ b/doc/ikiwiki/searching.mdwn
@@ -5,7 +5,7 @@ then="This wiki has searching **enabled**."
 else="This wiki has searching **disabled**."]]
 
 If searching is enabled, you can enter search terms in the search field,
-as you'd expect. There are a few special things you can do to constuct
+as you'd expect. There are a few special things you can do to construct
 more powerful searches.
 
 * To match a phrase, enclose it in double quotes.
diff --git a/doc/ikiwiki/subpage.mdwn b/doc/ikiwiki/subpage.mdwn
index e047b860c..862f45ec1 100644
--- a/doc/ikiwiki/subpage.mdwn
+++ b/doc/ikiwiki/subpage.mdwn
@@ -5,8 +5,8 @@ this page, [[SubPage]] has some related pages placed under it, like
 wiki rather than just having a great big directory full of pages.
 
 To add a SubPage, just make a subdirectory and put pages in it. For
-example, this page is SubPage.mdwn in this wiki's source, and there is also
-a SubPage subdirectory, which contains SubPage/LinkingRules.mdwn. Subpages
+example, this page is subpage.mdwn in this wiki's source, and there is also
+a subpage subdirectory, which contains subpage/linkingrules.mdwn. Subpages
 can be nested as deeply as you'd like.
 
 Linking to and from a SubPage is explained in [[LinkingRules]].
diff --git a/doc/ikiwiki/wikilink.mdwn b/doc/ikiwiki/wikilink.mdwn
index f561d5850..cf3b89c76 100644
--- a/doc/ikiwiki/wikilink.mdwn
+++ b/doc/ikiwiki/wikilink.mdwn
@@ -9,9 +9,6 @@ wikilink, just prefix it with a `\`, like `\\[[WikiLink]]`.
 There are some special [[SubPage/LinkingRules]] that come into play when
 linking between [[SubPages|SubPage]].
 
-Also, if the file linked to by a WikiLink looks like an image, it will
-be displayed inline on the page.
-
 WikiLinks are matched with page names in a case-insensitive manner, so you
 don't need to worry about getting the case the same, and can capitalise
 links at the start of a sentence, and so on.
@@ -23,14 +20,10 @@ page, but the link will appear like this: [[foo_bar|SandBox]].
 To link to an anchor inside a page, you can use something like
 `\[[WikiLink#foo]]` .
 
-## Directives and WikiLinks
-
-ikiwiki has two syntaxes for
-[[directives|directive]].  The older syntax
-used spaces to distinguish between directives and
-wikilinks; as a result, with that syntax in use, you cannot use spaces
-in WikiLinks, and must replace spaces with underscores.  The newer
-syntax, enabled with the `prefix_directives` option in an ikiwiki
-setup file, prefixes directives with `!`, and thus does not prevent
-links with spaces.  Future versions of ikiwiki will turn this option
-on by default.
+If the file linked to by a WikiLink looks like an image, it will
+be displayed inline on the page.
+
+---
+
+You can also put an url in a WikiLink, to link to an external page.
+Email addresses can also be used to generate a mailto link.
diff --git a/doc/ikiwiki/wikilink/discussion.mdwn b/doc/ikiwiki/wikilink/discussion.mdwn
index b146c9447..89affc502 100644
--- a/doc/ikiwiki/wikilink/discussion.mdwn
+++ b/doc/ikiwiki/wikilink/discussion.mdwn
@@ -43,6 +43,11 @@ BTW, ikiwiki doesn't displays the #foo anchor in the example
 
 >> Fixed that --[[Joey]]
 
+The 'name' attribute of the 'a' element is a depracated way to create a named anchor. The right way to do that is using the 'id' attribute of any element. This is because an anchor may refer to a complete element rather than some point in the page.
+
+Standard purity aside, if you define an anchor (using either 'a name' or 'id') to a single point in the document but refer to a complete section, the browser may just show that specific point at the bottom of the page rather than trying to show all the section.
+--[[tzafrir]]
+
 ---
 
 Considering a hierarchy like `foo/bar/bar`, I had the need to link from the
@@ -79,3 +84,8 @@ Is it possible to refer to a page, say \[[foobar]], such that the link text is t
 > Not yet. :-) Any suggestion for a syntax for it? Maybe something like \[[|foobar]] ? --[[Joey]]
 
 I like your suggestion because it's short and conscise. However, it would be nice to be able to refer to more or less arbitrary meta tags in links, not just "title". To do that, the link needs two parameters: the page name and the tag name, i.e. \[[pagename!metatag]]. Any sufficiently weird separater can be used instead of '!', of course. I like \[[pagename->metatag]], too, because it reminds me of accessing a data member of a structure (which is what referencing a meta tag is, really). --Peter
+
+> I dislike \[[pagename->metatag]] because other wikis use that as their normal link/label syntax.
+> I'm not sure that it is a good idea to refer to arbitrary meta tags in links in the first place - what other meta tags would you really be interested in?  Description?  Author?  It makes sense to me to refer to the title, because that is a "label" for a page.
+> As for syntax, I do like the \[[|foobar]] idea, or perhaps something like what <a href="http://www.pmwiki.org">PmWiki</a> does - they have their links the other way around, so they go \[[page|label]] and for link-text-as-title, they have \[[page|+]].  So for IkiWiki, that would be \[[+|page]] I guess.
+> --[[KathrynAndersen]]