Merge branch 'master' into cvs

41 files changed, 749 insertions, 303 deletions

diff --git a/doc/plugins/anonok.mdwn b/doc/plugins/anonok.mdwn
index 506657a1c..407012b54 100644
--- a/doc/plugins/anonok.mdwn
+++ b/doc/plugins/anonok.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=anonok author="[[Joey]]"]]
-[[!tag type/auth]]
+[[!tag type/auth type/comments]]
 
 By default, anonymous users cannot edit the wiki. This plugin allows
 anonymous web users, who have not signed in, to edit any page in the wiki
diff --git a/doc/plugins/blogspam.mdwn b/doc/plugins/blogspam.mdwn
index c158316d4..3dd017f61 100644
--- a/doc/plugins/blogspam.mdwn
+++ b/doc/plugins/blogspam.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=blogspam author="[[Joey]]"]]
-[[!tag type/auth]]
+[[!tag type/auth type/comments]]
 
 This plugin adds antispam support to ikiwiki, using the
 [blogspam.net](http://blogspam.net/) API. Both page edits and
diff --git a/doc/plugins/camelcase.mdwn b/doc/plugins/camelcase.mdwn
index 1764b31b2..d9b7172d5 100644
--- a/doc/plugins/camelcase.mdwn
+++ b/doc/plugins/camelcase.mdwn
@@ -7,4 +7,7 @@ link.
 
 If this plugin is enabled, this will be a link: SandBox
 
+Use of this plugin is not recommended, particularly on complex wikis with
+things like [[aggregate]] in use.
+
 [[!tag type/link]]
diff --git a/doc/plugins/comments.mdwn b/doc/plugins/comments.mdwn
index 48b6c6ae7..50a99415f 100644
--- a/doc/plugins/comments.mdwn
+++ b/doc/plugins/comments.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=comments author="[[Simon_McVittie|smcv]]"]]
-[[!tag type/web]]
+[[!tag type/web type/comments]]
 
 This plugin adds "blog-style" comments. Unlike the wiki-style freeform 
 Discussion pages, these comments are posted by a simple form, cannot later
diff --git a/doc/plugins/contrib/album.mdwn b/doc/plugins/contrib/album.mdwn
index 836a98f33..745a44e8b 100644
--- a/doc/plugins/contrib/album.mdwn
+++ b/doc/plugins/contrib/album.mdwn
@@ -46,9 +46,9 @@ template:
 
 ----
 
-[[!template id=gitbranch branch=smcv/album3 author="[[Simon_McVittie|smcv]]"]]
+[[!template id=gitbranch branch=smcv/album4 author="[[Simon_McVittie|smcv]]"]]
 
-Available from [[smcv]]'s git repository, in the `album3` branch.
+Available from [[smcv]]'s git repository, in the `album4` branch.
 I've called it `album` to distinguish it from
 [[contrib/gallery|plugins/contrib/gallery]], although `gallery` might well be
 a better name for this functionality.
@@ -59,23 +59,25 @@ individual photos can't be bookmarked in a meaningful way, and
 the best it can do as a fallback for non-Javascript browsers
 is to provide a direct link to the image.)
 
-Updated, November 2011: rebased onto [[trail]] v3, CSS adjusted.
+Updated, April 2012: rebased onto the version of [[trail]] that got merged
 
 ## Manual installation
 
-If you don't want to use a branch of ikiwiki, manual installation requires
-these files (use the "raw" link in gitweb to download), in addition to the
-ones needed by [[trail]]:
+First, you need a version of ikiwiki with the [[trail]] plugin merged in
+(version 3.20120203 or later).
 
-* [album.pm](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/IkiWiki/Plugin/album.pm)
+Manual installation requires these files (use the "raw" link in gitweb
+to download):
+
+* [album.pm](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/IkiWiki/Plugin/album.pm)
   in an `IkiWiki/Plugin` subdirectory of your configured `plugindir`
-* [albumviewer.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/templates/albumviewer.tmpl),
-  [albumitem.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/templates/albumitem.tmpl),
-  [albumnext.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/templates/albumnext.tmpl) and
-  [albumprev.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/templates/albumprev.tmpl),
+* [albumviewer.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumviewer.tmpl),
+  [albumitem.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumitem.tmpl),
+  [albumnext.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumnext.tmpl) and
+  [albumprev.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/templates/albumprev.tmpl),
    in your configured `templatedir`, or a `templates` subdirectory of your wiki repository
 * the album-related bits from the end of the
-  [stylesheet](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/doc/style.css)
+  [stylesheet](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album4:/doc/style.css)
   (put them in your local.css)
 
 ## Demo
diff --git a/doc/plugins/contrib/asymptote.mdwn b/doc/plugins/contrib/asymptote.mdwn
new file mode 100644
index 000000000..31bf0b1fe
--- /dev/null
+++ b/doc/plugins/contrib/asymptote.mdwn
@@ -0,0 +1,141 @@
+[[!template id=plugin name=asymptote author="[[PeterSimons]]"]]
+[[!tag type/widget]]
+
+This plugin provides the [[ikiwiki/directive/asymptote]]
+[[ikiwiki/directive]] which allows embedding
+[asymptote](http://asymptote.sourceforge.net/) diagrams in a page.
+
+Security implications: asymptote has functions for reading files and
+other dangerous stuff, so enabling this plugin means that everyone who
+can edit your Wiki can also read any file from your hard drive thats
+accessible to the user running Ikiwiki. 
+
+[[!if test="enabled(asymptote)" then="""
+An example diagram:
+
+[[!asymptote src="""
+import geometry;
+unitsize(1cm);
+triangle t = triangle((0,0), (4,0), (0.5,2));
+show(La="$D$", Lb="$E$", Lc="", t);
+dot(t.A^^t.B^^t.C);
+point pD = midpoint(t.BC); dot(pD);
+point pE = midpoint(t.AC); dot(pE);
+draw(pD--pE);
+
+point A_ = (pD-t.A)*2+t.A; dot("$A'$", A_, NE);
+draw(t.B--A_--t.C, dashed);
+draw(t.A--A_, dashed);
+
+point E_ = midpoint(line(t.B,A_)); dot(Label("$E'$", E_, E));
+draw(E_--pD, dashed);
+"""]]
+"""]]
+
+This plugin uses the [[!cpan Digest::SHA]] perl module.
+
+The full source code is:
+
+        #! /usr/bin/perl
+
+        package IkiWiki::Plugin::asymptote;
+        use warnings;
+        use strict;
+        use Digest::MD5 qw(md5_hex);
+        use File::Temp qw(tempdir);
+        use HTML::Entities;
+        use Encode;
+        use IkiWiki 3.00;
+
+        sub import {
+                hook(type => "getsetup", id => "asymptote", call => \&getsetup);
+                hook(type => "preprocess", id => "asymptote", call => \&preprocess);
+        }
+
+        sub getsetup () {
+                return
+                        plugin => {
+                                safe => 1,
+                                rebuild => undef,
+                                section => "widget",
+                        },
+        }
+
+        sub preprocess (@) {
+                my %params = @_;
+
+                my $code = $params{src};
+                if (! defined $code && ! length $code) {
+                        error gettext("missing src attribute");
+                }
+                return create($code, \%params);
+        }
+
+        sub create ($$$) {
+                # This function calls the image generating function and returns
+                # the <img .. /> for the generated image.
+                my $code = shift;
+                my $params = shift;
+
+                my $digest = md5_hex(Encode::encode_utf8($code));
+
+                my $imglink= $params->{page} . "/$digest.png";
+                my $imglog =  $params->{page} .  "/$digest.log";
+                will_render($params->{page}, $imglink);
+                will_render($params->{page}, $imglog);
+
+                my $imgurl=urlto($imglink, $params->{destpage});
+                my $logurl=urlto($imglog, $params->{destpage});
+
+                if (-e "$config{destdir}/$imglink" ||
+                    gen_image($code, $digest, $params->{page})) {
+                        return qq{<img src="$imgurl}
+                                .(exists $params->{alt} ? qq{" alt="} . $params->{alt} : qq{})
+                                .qq{" class="asymptote" />};
+                }
+                else {
+                        error qq{<a href="$logurl">}.gettext("failed to generate image from code")."</a>";
+                }
+        }
+
+        sub gen_image ($$$$) {
+                # Actually creates the image.
+                my $code = shift;
+                my $digest = shift;
+                my $imagedir = shift;
+
+                my $tmp = eval { create_tmp_dir($digest) };
+                if (! $@ &&
+                    writefile("$digest.asy", $tmp, $code) &&
+                    writefile("$imagedir/$digest.png", $config{destdir}, "") &&
+                    system("asy -render=2 -offscreen -f png -o $config{destdir}/$imagedir/$digest.png $tmp/$digest.asy &>$tmp/$digest.log") == 0
+                   ) {
+                        return 1;
+                }
+                else {
+                        # store failure log
+                        my $log="";
+                        {
+                                if (open(my $f, '<', "$tmp/$digest.log")) {
+                                        local $/=undef;
+                                        $log = <$f>;
+                                        close($f);
+                                }
+                        }
+                        writefile("$digest.log", "$config{destdir}/$imagedir", $log);
+
+                        return 0;
+                }
+        }
+
+        sub create_tmp_dir ($) {
+                # Create a temp directory, it will be removed when ikiwiki exits.
+                my $base = shift;
+
+                my $template = $base.".XXXXXXXXXX";
+                my $tmpdir = tempdir($template, TMPDIR => 1, CLEANUP => 1);
+                return $tmpdir;
+        }
+
+        1
+
diff --git a/doc/plugins/contrib/asymptote/ikiwiki/directive/asymptote.mdwn b/doc/plugins/contrib/asymptote/ikiwiki/directive/asymptote.mdwn
new file mode 100644
index 000000000..c6bdb1a99
--- /dev/null
+++ b/doc/plugins/contrib/asymptote/ikiwiki/directive/asymptote.mdwn
@@ -0,0 +1,27 @@
+The `asymptote` directive is supplied by the [[!iki plugins/contrib/asymptote
+desc=asymptote]] plugin.
+
+This directive allows embedding [asymptote](http://asymptote.sourceforge.net/)
+diagrams in a page. Example usage:
+
+	\[[!asymptote src="""
+        import geometry;
+        unitsize(1cm);
+        triangle t = triangle((0,0), (4,0), (0.5,2));
+        show(La="$D$", Lb="$E$", Lc="", t);
+        dot(t.A^^t.B^^t.C);
+        point pD = midpoint(t.BC); dot(pD);
+        point pE = midpoint(t.AC); dot(pE);
+        draw(pD--pE);
+        point A_ = (pD-t.A)*2+t.A; dot("$A'$", A_, NE);
+        draw(t.B--A_--t.C, dashed);
+        draw(t.A--A_, dashed);
+        point E_ = midpoint(line(t.B,A_)); dot(Label("$E'$", E_, E));
+        draw(E_--pD, dashed);
+        """]]
+
+The `asymptote` directive supports the following parameters:
+
+- `src` - The asymptote source code to render.
+
+[[!meta robots="noindex, follow"]]
diff --git a/doc/plugins/contrib/created_in_future.mdwn b/doc/plugins/contrib/created_in_future.mdwn
new file mode 100644
index 000000000..5768057aa
--- /dev/null
+++ b/doc/plugins/contrib/created_in_future.mdwn
@@ -0,0 +1,18 @@
+# Created_in_future
+
+This plugin provides a `created_in_future()` [[PageSpec|ikiwiki/pagespec/]]
+function. It matches pages which have a creation date in the future.
+
+It also sets the date of the next modification of the page on its creation
+date, so that the corresponding page (and the pages referring to it) will be
+rebuilt on the relevant call of `ikiwiki`.
+
+## Usage
+
+It can be used to display a list of upcoming events.
+
+	\[[!inline pages="events/* and created_in_future()" reverse=yes sorted=meta(date)]]
+
+## Code
+
+Code and documentation this way: [[https://atelier.gresille.org/projects/gresille-ikiwiki/wiki/Created_in_future]].
diff --git a/doc/plugins/contrib/getfield/discussion.mdwn b/doc/plugins/contrib/getfield/discussion.mdwn
index 5f7fffead..13ea8b1b3 100644
--- a/doc/plugins/contrib/getfield/discussion.mdwn
+++ b/doc/plugins/contrib/getfield/discussion.mdwn
@@ -1,3 +1,50 @@
+## Multiple values arrays
+
+This breaks if there are multiple values for a single key. It works fine in the report plugin, but inline display shows the ARRAY reference, e.g. 
+
+    IPv6:
+    - fd64:2c08:9fa7:4::1
+    - 2001:470:1d:4a6::1
+
+and:
+
+    {{$IPv6}}
+
+yields:
+
+    ARRAY(0x266db10)
+
+Seems to me this could be checked and `join(" ")`'d. :) -- [[anarcat]]
+
+> I wrote a stupid fix for this, which works for getfield, but isn't as good for report. It simply does that `join()`. Here's the patch:
+> 
+> [[!format diff """
+--- a/IkiWiki/Plugin/field.pm
++++ b/IkiWiki/Plugin/field.pm
+@@ -322,6 +322,9 @@ sub field_get_value ($$;@) {
+     {
+        $basevalue = calculated_values($lc_field_name, $page);
+     }
++    if (ref($basevalue) eq "ARRAY") {
++        $basevalue = join(" ", @{$basevalue}); # hack
++    }
+     if (defined $basevalue)
+     {
+        $Cache{$page}{$basename} = $basevalue;
+@@ -360,6 +363,9 @@ sub field_get_value ($$;@) {
+     {
+        $value = $basevalue;
+     }
++    if (ref($value) eq "ARRAY") {
++        $value = join(" ", @{$value}); # hack
++    }
+     if (defined $value)
+     {
+        $Cache{$page}{$lc_field_name} = $value;
+"""]]
+>
+> Seems to me this should be the default, at the very least in getfield. But at least, with the above patch we don't see expanded Perl ref's. ;) --[[anarcat]]
+
 ## Templating, and other uses
 
 Like you mentioned in [[ftemplate]] IIRC, it'll only work on the same page. If it can be made to work anywhere, or from a specific place in the wiki - configurable, possibly - you'll have something very similar to mediawiki's templates. I can already think of a few uses for this combined with [[template]] ;) . --[[SR|users/simonraven]]
diff --git a/doc/plugins/contrib/googlemaps.mdwn b/doc/plugins/contrib/googlemaps.mdwn
index 9d21a6b7a..c43490b13 100644
--- a/doc/plugins/contrib/googlemaps.mdwn
+++ b/doc/plugins/contrib/googlemaps.mdwn
@@ -18,4 +18,4 @@ It can be [found here][3].
 
 [3]: http://www.tahina.priv.at/hacks/googlemaps.html
 
-See also [[plugins/contrib/osm]].
+See also [[plugins/osm]].
diff --git a/doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn
deleted file mode 100644
index 91d8a4edf..000000000
--- a/doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn
+++ /dev/null
@@ -1,11 +0,0 @@
-The `trailinline` directive is provided by the
-[[!iki plugins/contrib/trail desc=trail]]
-plugin. It is equivalent to combining [[ikiwiki/directive/trailitems]] and
-[[ikiwiki/directive/inline]] directives with the same options.
-
-A typical use is to navigate through all posts in a blog:
-
-      \[[!trailinline pages="page(./posts/*) and !*/Discussion" archive=yes
-        feedshow=10 quick=yes]]
-
-[[!meta robots="noindex, follow"]]
diff --git a/doc/plugins/contrib/ikiwiki/directive/trailitem.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailitem.mdwn
deleted file mode 100644
index 73b1985a5..000000000
--- a/doc/plugins/contrib/ikiwiki/directive/trailitem.mdwn
+++ /dev/null
@@ -1,9 +0,0 @@
-The `trailitem` directive is supplied by the
-[[!iki plugins/contrib/trail desc=trail]] plugin. It is used like this:
-
-    \[[!trailitem some_other_page]]
-
-to add `some_other_page` to the trail represented by this page, without
-generating a visible hyperlink.
-
-[[!meta robots="noindex, follow"]]
diff --git a/doc/plugins/contrib/ikiwiki/directive/trailitems.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailitems.mdwn
deleted file mode 100644
index 4106ed33b..000000000
--- a/doc/plugins/contrib/ikiwiki/directive/trailitems.mdwn
+++ /dev/null
@@ -1,24 +0,0 @@
-The `trailitems` directive is supplied by the
-[[!iki plugins/contrib/trail desc=trail]] plugin. It adds pages
-to the trail represented by the current page, without producing any output
-on that page.
-
-    \[[!trailitems pages="posts/*" sort="age"]]
-
-    \[[!trailitems pagenames="a b c"]]
-
-Options are similar to [[!iki ikiwiki/directive/inline desc=inline]]:
-
-* `pages`: adds pages that match a [[ikiwiki/PageSpec]] to the trail
-  (cannot be used with `pagenames`)
-
-* `pagenames`: adds a space-separated list of pages to the trail,
-  with the same [[ikiwiki/SubPage/LinkingRules]] as for a [[ikiwiki/WikiLink]]
-  (cannot be used with `pages`)
-
-* `sort`: add the pages matched by `pages` to the trail in this
-  [[ikiwiki/pagespec/sorting]] order (cannot be used with `pagenames`)
-
-* `reverse`: reverse the order of `sort` (cannot be used with `pagenames`)
-
-[[!meta robots="noindex, follow"]]
diff --git a/doc/plugins/contrib/ikiwiki/directive/traillink.mdwn b/doc/plugins/contrib/ikiwiki/directive/traillink.mdwn
deleted file mode 100644
index 0e40e2411..000000000
--- a/doc/plugins/contrib/ikiwiki/directive/traillink.mdwn
+++ /dev/null
@@ -1,16 +0,0 @@
-The `traillink` directive is supplied by the
-[[!iki plugins/contrib/trail desc=trail]]
-plugin. It generates a visible [[ikiwiki/WikiLink]], and also adds the
-linked page to the trail represented by the page containing the directive.
-
-In its simplest form, the first parameter is like the content of a WikiLink:
-
-    \[[!traillink some_other_page]]
-
-The displayed text can also be overridden, either with a `|` symbol or with
-a `text` parameter:
-
-    \[[!traillink Click_here_to_start_the_trail|some_other_page]]
-    \[[!traillink some_other_page text="Click here to start the trail"]]
-
-[[!meta robots="noindex, follow"]]
diff --git a/doc/plugins/contrib/ikiwiki/directive/trailoptions.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailoptions.mdwn
deleted file mode 100644
index e1603f11b..000000000
--- a/doc/plugins/contrib/ikiwiki/directive/trailoptions.mdwn
+++ /dev/null
@@ -1,18 +0,0 @@
-The `trailoptions` directive is supplied by the
-[[!iki plugins/contrib/trail desc=trail]] plugin. It sets options for the
-trail represented by this page.
-
-    \[[!trailoptions sort="meta(title)" circular="no"]]
-
-Options available:
-
-* `sort`: sets a [[ikiwiki/pagespec/sorting]] order for the entire trail,
-  overriding the order in which they were added
-
-* `reverse`: reverses the order of the trail
-
-* `circular`: if set to `yes` or `1`, the trail is made into a loop by
-  making the last page's "next" link point to the first page, and the first
-  page's "previous" link point to the last page
-
-[[!meta robots="noindex, follow"]]
diff --git a/doc/plugins/contrib/ikiwiki/directive/ymlfront/discussion.mdwn b/doc/plugins/contrib/ikiwiki/directive/ymlfront/discussion.mdwn
new file mode 100644
index 000000000..f49c85079
--- /dev/null
+++ b/doc/plugins/contrib/ikiwiki/directive/ymlfront/discussion.mdwn
@@ -0,0 +1,37 @@
+I can't seem to make this work. I have tried, in this [sandbox](http://mesh.openisp.ca/sandbox), to set values for fields and then display them with the getfield meta syntax, but it doesn't seem to be working.
+
+The getfield, field and ymlfront plugins are enabled. I have tried with and without the following field registration:
+
+    # field plugin
+    # define the fields for the meshmtl project
+    field_register:
+    - meta
+    - hostname
+    - MAC
+    - IP
+
+I have tried both the ymlfront directive and the YAML markup (with the
+`---` delimiter), no luck. Any idea what I am doing wrong? --
+[[anarcat]]
+
+> I'm afraid I can't tell from here what the problem could be.  It's clear that ymlfront is turned on, or the ymlfront directive in your sandbox page wouldn't be processed.  The only thing I can suggest, in order to get more information about what could be going wrong, would be to do a dump of your indexdb file (see [[tips/inside dot ikiwiki]]) and see what the data for your sandbox page is.  If there is field data there, that would indicate a problem with getfield; if there isn't field data there, that would indicate a problem with field or ymlfront.
+
+> Oh, and you only need to register "meta" with field_register; that will enable the data defined by the "meta" plugin to be read by field.  Unless "hostname", "MAC" and "IP" are plugins, you don't need to add them to field_register.  They can be taken care of by the ymlfront plugin.  Perhaps that is the problem?
+
+> --[[KathrynAndersen]]
+
+> > I have tried removing the other fields from the declaration, no luck. I did, however, notice the following error in the `--rebuild` output:
+> > 
+> >     ymlfront parse: Load of sandbox data failed: YAML Error: Stream does not end with newline character
+> >        Code: YAML_PARSE_ERR_NO_FINAL_NEWLINE
+> >        Line: 0
+> >        Document: 0
+> >      at /usr/share/perl5/YAML/Loader.pm line 38
+> > 
+> > Now *that* has to be related... ;) In the index.db, there is no ymlfront metadata for the sandbox page... Note that the `---` delimiter approach doesn't trigger the warning but doesn't populate the DB either...
+> > 
+> > Finally note that after adding debugging code, I was able to figure out that this seems to be using the `YAML::XS` library. I have also traced the data and confirmed that `$yml_str` does get properly initialized in `parse_yml`, and it is where the error is generated. So maybe there's something wrong with the YAML library?
+> > 
+> > Update: well, look here: using `YAML::Syck` doesn't yield the same error *and* the metadata actually works! So this is a problem specific to `YAML::Any`. Hardcoding `use YAML::XS` or *even* `use YAML::Any` fixed the problem for me.
+> > 
+> > Now delimiters also work, but the output is kind of ugly: it gets parsed as regular markdown makup so the `---` makes horizontal lines in the beginning and headings in the end... --[[anarcat]]
diff --git a/doc/plugins/contrib/jscalendar.mdwn b/doc/plugins/contrib/jscalendar.mdwn
new file mode 100644
index 000000000..a320a0542
--- /dev/null
+++ b/doc/plugins/contrib/jscalendar.mdwn
@@ -0,0 +1,45 @@
+[[!meta title="Javascript equivalent of plugin 'calendar'"]]
+
+# Jscalendar
+
+Jscalendar is a javascript equivalent to the [[calendar|plugins/calendar]] plugin.
+
+## Description
+
+Here are some differences compared to this latter plugin.
+
+* Pros
+  * No need to rebuild the page containing the calendar each time day changes, or
+    a page (indexed by the calendar) is added, changed or deleted. This is
+    particularly useful if you want to have this calendar in the sidebar.
+  * Handles the case where several pages appear the same day: a popup appear to let user choose the day he wants.
+  * Smooth navigation among months.
+* Neutral
+  * Most of options are defined in Ikiwiki's setup files instead of the options
+    of the directive.
+* Cons
+  * As a consequence, every calendar of the wiki must index the same set of pages.
+  * Javascript :( .
+
+## Usage
+
+### Directive
+
+    \[[!jscalendar type="month" ]]
+
+### Setup file
+
+It being javascript rather than markdown, most of the configuration must be done in the IkiWiki configuration file rather than in the directive
+
+    'archivebase' => "evenements/calendrier",
+    'archive_pagespec' => "evenements/liste/* and ! evenements/liste/*/*",
+    'week_start_day' => 1,
+    'month_link' => 1,
+
+## Example
+
+You can see this plugin in action on [[our website|http://www.gresille.org]]. To see what happens when several pages happens on the same day, check the 15th of March 2012.
+
+Code and documentation can be found here : [[https://atelier.gresille.org/projects/gresille-ikiwiki/wiki/Jscalendar]]
+
+-- Louis
diff --git a/doc/plugins/contrib/localfavicon.mdwn b/doc/plugins/contrib/localfavicon.mdwn
new file mode 100644
index 000000000..66c9fdf5c
--- /dev/null
+++ b/doc/plugins/contrib/localfavicon.mdwn
@@ -0,0 +1,7 @@
+[[!template id=plugin name=localfavicon author="Franek"]]
+
+This is a trivial modification of the [[plugins/favicon]] plugin to allow different favicons for different parts of the site. For this, the option "localfavicon" has to be set to 1 in the setup file, otherwise the plugin behaves just like the favicon plugin.
+
+For now, it can be downloaded here: [[http://perm.lemtank.de/localfavicon.pm]]
+
+See the [[this forum thread|forum/Can_I_have_different_favicons_for_each_folder__63__]] for discussion.
diff --git a/doc/plugins/contrib/monthcalendar.mdwn b/doc/plugins/contrib/monthcalendar.mdwn
new file mode 100644
index 000000000..d48e4d6b7
--- /dev/null
+++ b/doc/plugins/contrib/monthcalendar.mdwn
@@ -0,0 +1,23 @@
+# Monthcalendar
+
+This plugin displays a calendar, containing in each of its day the list of links of pages published on this day. It can be used, for example, to display archives of blog posts, or to announce events.
+
+## Usage
+
+### Directive
+
+    \[[!monthcalendar type="month" year="2012" month="06" pages="events/*"]]
+
+### Automation
+
+By using the following line in template `calendarmonth.tmpl`, you can have `ikiwiki-calendar` using this plugin to display monthly archives.
+
+    \[[!monthcalendar type="month" year="<TMPL_VAR YEAR>" month="<TMPL_VAR MONTH>" pages="<TMPL_VAR PAGESPEC>"]]
+
+## Code
+
+Code and documentation can be found here : [[https://atelier.gresille.org/projects/gresille-ikiwiki/wiki/Monthcalendar]].
+
+## Example
+
+This plugin is used in [our website](http://www.gresille.org/evenements/calendrier/2012/03)
diff --git a/doc/plugins/contrib/report/discussion.mdwn b/doc/plugins/contrib/report/discussion.mdwn
index e23a4ced4..419c4bca6 100644
--- a/doc/plugins/contrib/report/discussion.mdwn
+++ b/doc/plugins/contrib/report/discussion.mdwn
@@ -73,3 +73,8 @@ to select pages? How does it relate to [[todo/wikitrails]] or
 >>>>> It might be that adding arrays to the `field` plugin is a good way to go: after all, even though field=value is the most common, with the flexibility of things like YAML, one could define all sorts of things.  What I'm not so sure about is how to return the values when queried, since some things would be expecting scalars all the time.  Ah, perhaps I could use wantarray?
 >>>>> Is there a way of checking a HTML::Template template to see if it expecting an array for a particular value?
 >>>>> --[[KathrynAndersen]]
+
+How about arrays?
+-----------------
+
+In [[plugins/contrib/getfield/discussion]], I outline how there's a problem in getfield displaying array refs when the data is a YAML array. I also propose a patch there so that arrays are join'd with a space separator, which is less than ideal, but at least works for getfield. However, for report, I am not sure it's as good. Should it make two rows for those? How should we parse this? Thanks. -- [[anarcat]]
diff --git a/doc/plugins/contrib/syntax.mdwn b/doc/plugins/contrib/syntax.mdwn
index 5ca6311f9..da4213000 100644
--- a/doc/plugins/contrib/syntax.mdwn
+++ b/doc/plugins/contrib/syntax.mdwn
@@ -44,6 +44,8 @@ This plugin create the following CSS styles:
 
 It can be downloaded from [here](http://taquiones.net/files/misc/) or through my personal debian repository at <http://taquiones.net/files/debian/>. There is a page with examples: <http://taquiones.net/software/syntax-examples.html>
 
+_**NOTE:** all the above links are broken_
+
 Any help, comments or critics are welcome at <victor@taquiones.net>.
 
 ## version 0.9
diff --git a/doc/plugins/contrib/trail.mdwn b/doc/plugins/contrib/trail.mdwn
deleted file mode 100644
index bfd4d3d0b..000000000
--- a/doc/plugins/contrib/trail.mdwn
+++ /dev/null
@@ -1,133 +0,0 @@
-[[!tag patch]]
-[[!template id=gitbranch branch=smcv/trail3 author="[[smcv]]"]]
-
-Available from [[smcv]]'s git repository, in the `trail3` branch. This
-plugin aims to solve [[todo/wikitrails]] in a simpler way; it can also be
-used for [[navigation through blog posts|todo/Pagination_next_prev_links]].
-
-If you don't want to use a branch of ikiwiki, manual installation requires
-these files (use the "raw" link in gitweb to download):
-
-* [trail.pm](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/trail3:/IkiWiki/Plugin/trail.pm)
-  in an `IkiWiki/Plugin` subdirectory of your configured `plugindir`
-* [page.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/trail3:/templates/page.tmpl)
-  and
-  [trails.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/trail3:/templates/trails.tmpl)
-  in your configured `templatedir`, or a `templates` subdirectory of your wiki repository
-* the trail-related bits from the end of the
-  [stylesheet](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/trail3:/doc/style.css)
-  (put them in your local.css)
-* the trail-related bits at the end of the
-  [actiontabs](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/trail3:/themes/actiontabs/style.css)
-  or [blueview/goldtype](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/trail3:/themes/blueview/style.css)
-  stylesheets, if you use one of those themes (again, put them in your local.css)
-
-The branch also includes [[todo/test_coverage]] machinery.
-
-Demo:
-
-* [in use on entries in my blog](http://smcv.pseudorandom.co.uk/)
-* [a demo trail based on links](http://demo.hosted.pseudorandom.co.uk/trail/)
-* [a demo hybrid trail/inline](http://demo.hosted.pseudorandom.co.uk/trail2/)
-
-The page `e` is in both demo trails, to demonstrate how a page in more than
-one trail looks.
-
-The `smcv/trail2` branch is an older version of `trail3` which used typed links
-as its data structure, resulting in timing-related limitations (it couldn't
-select pages for the trail by using pagespecs, because pagespecs can't be
-evaluated correctly until the scan stage has finished).
-
-Updated, November 2011:
-
-* reinstated `inline` integration ([[report]] integration would probably be
-  pretty easy too, if this gets merged)
-* switched from typed links back to a custom data structure to avoid
-  chicken/egg problems with ordering
-* create typed links too, as a side-effect, but not when using an inline
-* regression test with nearly full coverage
-* CSS for the default anti-theme and all built-in themes (it looks nicest
-  in the default anti-theme and in actiontabs - the demo uses actiontabs)
-
-Known bugs:
-
-* the blueview and goldtype CSS nearly work, but the alignment is a bit off
-
-----
-
-[[!template id=plugin name=trail author="[[Simon_McVittie|smcv]]"]]
-[[!tag type/chrome]]
-
-This plugin provides the [[ikiwiki/directive/trailoptions]],
-[[ikiwiki/directive/traillink]], [[ikiwiki/directive/trailitem]],
-[[ikiwiki/directive/trailitems]]
-and [[ikiwiki/directive/trailinline]] [[directives|ikiwiki/directive]].
-
-It's sometimes useful to have "trails" of pages in a wiki where each
-page links to the next and/or previous page. For instance, you could use
-this for a guided tour, sequence of chapters, or sequence of blog posts.
-
-In this plugin, a trail is represented by a page, and the pages in the
-trail are indicated by specially marked links within that page, or by
-including groups of pages with a [[ikiwiki/directive]].
-
-If using the default `page.tmpl`, each page automatically displays the
-trails that it's a member of (if any), with links to the trail and to
-the next and previous members. HTML `<link>` tags with the `prev`,
-`next` and `up` relations are also generated.
-
-The [[ikiwiki/directive/trailoptions]] directive sets options for the
-entire trail.
-
-Pages can be included in a trail in various ways:
-
-* The [[ikiwiki/directive/trailinline]] directive sets up an [[inline]],
-  and at the same time adds the matching pages (from `pages` or `pagenames`)
-  to the trail. One use is to navigate through all posts in a blog:
-
-        \[[!trailinline pages="page(./posts/*) and !*/Discussion" archive=yes
-          feedshow=10 quick=yes]]
-
-  This directive only works if the [[!iki plugins/inline desc=inline]]
-  plugin is also enabled.
-
-* The [[ikiwiki/directive/trailitems]] directive has optional `pages` and
-  `pagenames` options which behave the same as in [[inline]], but don't
-  produce any output in the page, so you can have trails that don't list
-  all their pages.
-
-* The [[ikiwiki/directive/traillink]] directive makes a visible link
-  and also adds the linked page to the trail. This will typically be
-  used in a bullet list, but could also be in paragraph text:
-
-        * [[!traillink Introduction]]
-        * [[!traillink "Chapter 1"]]
-        * [[!traillink Chapter_2]]
-        * [[!traillink Appendix_A]]
-
-  or
-
-        To use this software you must \[[!traillink install]] it,
-        \[[!traillink configuration text="configure it"]],
-        and finally \[[!traillink running|run_it]].
-
-  This also counts as a [[ikiwiki/WikiLink]] for things like the `link()`
-  [[ikiwiki/PageSpec]] item.
-
-* The [[ikiwiki/directive/trailitem]] directive adds a page to the trail
-  like `traillink`, but produces an invisible link, rather like `\[[!tag]]`:
-
-        To use this software you must \[[!traillink install]] it,
-        \[[!trailitem installing_from_packages]]
-        \[[!trailitem installing_from_source]]
-        \[[!traillink configuration text="configure it"]],
-        and finally \[[!traillink running|run_it]].
-        \[[!trailitem troubleshooting]]
-
-  Like `\[[!tag]]`, this still counts as a [[ikiwiki/WikiLink]] even though
-  there's no visible link.
-
-You can mix several of these directives in one page. The resulting
-trail will contain all of the pages matched by any of the directives,
-in the same order that the directives appear (unless you use the `sort` or
-`reverse` options on `\[[!trailoptions]]`).
diff --git a/doc/plugins/headinganchors/discussion.mdwn b/doc/plugins/headinganchors/discussion.mdwn
index 151af8d92..eaf111f4e 100644
--- a/doc/plugins/headinganchors/discussion.mdwn
+++ b/doc/plugins/headinganchors/discussion.mdwn
@@ -31,3 +31,19 @@ A patch to make it more like MediaWiki:
  </pre>
 
 --Changaco
+
+----
+
+I think using this below would let the source html clear for the browser
+without changing the render:
+
+        #use URI::Escape
+        .
+        .
+
+        #$str = uri_escape_utf8($str);
+        $str = Encode::decode_utf8($str);
+        #$str =~ s/%/./g;
+
+Don't you think ?
+[[mathdesc]]
diff --git a/doc/plugins/highlight/discussion.mdwn b/doc/plugins/highlight/discussion.mdwn
index 556b04145..a258f21fd 100644
--- a/doc/plugins/highlight/discussion.mdwn
+++ b/doc/plugins/highlight/discussion.mdwn
@@ -19,3 +19,5 @@ Having trouble working out where to get the perl bindings for highlight. --[Mick
 > --[[Joey]] 
 
 Thanks for prompt reply.All working. I will post on my site tonight and link here what I did on CentOS to make this work. --[Mick](http://www.lunix.com.au) 
+
+Any hint on how to highlight actual mdwn or any other supported markup code? -- [wiebel](http://wiebels.info)
diff --git a/doc/plugins/httpauth.mdwn b/doc/plugins/httpauth.mdwn
index 0eda5554f..2fae07739 100644
--- a/doc/plugins/httpauth.mdwn
+++ b/doc/plugins/httpauth.mdwn
@@ -2,7 +2,9 @@
 [[!tag type/auth]]
 
 This plugin allows HTTP basic authentication to be used to log into the
-wiki. 
+wiki. In this mode, the web browser authenticates the user by some means,
+and sets the `REMOTE_USER CGI` environment variable. This plugin trusts
+that if that variable is set, the user is authenticated.
 
 ## fully authenticated wiki
 
diff --git a/doc/plugins/lockedit.mdwn b/doc/plugins/lockedit.mdwn
index 681163203..8569238b1 100644
--- a/doc/plugins/lockedit.mdwn
+++ b/doc/plugins/lockedit.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=lockedit core=1 author="[[Joey]]"]]
-[[!tag type/auth]]
+[[!tag type/auth type/comments]]
 
 This plugin allows the administrator of a wiki to lock some pages, limiting
 who can edit them using the online interface. This doesn't prevent anyone
diff --git a/doc/plugins/mirrorlist.mdwn b/doc/plugins/mirrorlist.mdwn
index aedc1f4a0..b63685813 100644
--- a/doc/plugins/mirrorlist.mdwn
+++ b/doc/plugins/mirrorlist.mdwn
@@ -5,3 +5,18 @@ This plugin allows adding links a list of mirrors to each page in the
 wiki. For each mirror, a name and an url should be specified. Pages are
 assumed to exist in the same location under the specified url on each
 mirror.
+
+In case the `usedirs` setting is not the same on all your mirrors, or
+if it is not the same on your local wiki as on the mirror a
+possibility is to let each mirror's ikiwiki CGI find out the correct
+target page url themselves; in that case the mirrors urls must be set
+to their ikiwiki CGI url instead of their base url. Example:
+
+	mirrorlist_use_cgi => 1,
+	mirrorlist => {
+		'mirror1' => 'https://mirror.example.org/ikiwiki.cgi',
+		'mirror2' => 'https://mirror2.example.org/ikiwiki.cgi',
+	},
+
+The mirrors must have the ikiwiki CGI and the [[goto]] plugin enabled
+for this to work.
diff --git a/doc/plugins/moderatedcomments.mdwn b/doc/plugins/moderatedcomments.mdwn
index f9466e833..85bcf652b 100644
--- a/doc/plugins/moderatedcomments.mdwn
+++ b/doc/plugins/moderatedcomments.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=moderatedcomments author="[[Joey]]"]]
-[[!tag type/auth]]
+[[!tag type/auth type/comments]]
 
 This plugin causes [[comments]] to be held for manual moderation.
 Admins can access the comment moderation queue via their preferences page.
diff --git a/doc/plugins/notifyemail.mdwn b/doc/plugins/notifyemail.mdwn
new file mode 100644
index 000000000..302979e6e
--- /dev/null
+++ b/doc/plugins/notifyemail.mdwn
@@ -0,0 +1,14 @@
+This plugin allows uses to subscribe to pages, and emails them when
+they are created or changed.
+
+It needs the [[!cpan Mail::SendMail]] perl module, and sends mail
+using the local MTA.
+
+Each user can configure which pages they are interested in, using an
+[[ikiwiki/PageSpec]] on their Preferences page. Any change to a page
+matching the PageSpec will send an email that includes the new content of
+the page, and a link to the page on the web.
+
+To make it easy to subscribe to comment threads when posting a comment,
+or a page, there is a check box that can be used to subscribe, without
+needing to manually edit the [[ikiwiki/PageSpec]].
diff --git a/doc/plugins/po.mdwn b/doc/plugins/po.mdwn
index 703244947..b7c1582ca 100644
--- a/doc/plugins/po.mdwn
+++ b/doc/plugins/po.mdwn
@@ -229,6 +229,14 @@ are not rendered correctly on the slave pages:
   could be used to support it, but it would need a security audit
 * other markup languages have not been tested.
 
+Renaming a page
+---------------
+
+A translatable page may be renamed using the web interface and the
+[[rename plugin|plugins/rename]], or using the VCS directly; in
+the latter case, *both* the "master" page and every corresponding
+`.po` file must be renamed in the same commit.
+
 Security
 ========
 
diff --git a/doc/plugins/poll/discussion.mdwn b/doc/plugins/poll/discussion.mdwn
new file mode 100644
index 000000000..eed3f6ef9
--- /dev/null
+++ b/doc/plugins/poll/discussion.mdwn
@@ -0,0 +1 @@
+Has anyone given any thought to approval voting (ie. marking more than one option), ranking or more complex decision-making protocols here? --[[anarcat]]
diff --git a/doc/plugins/recentchangesdiff.mdwn b/doc/plugins/recentchangesdiff.mdwn
index 57299f92d..660a430b9 100644
--- a/doc/plugins/recentchangesdiff.mdwn
+++ b/doc/plugins/recentchangesdiff.mdwn
@@ -2,6 +2,8 @@
 [[!tag type/meta]]
 
 This plugin extends the [[recentchanges]] plugin, adding a diff for each
-change. The diffs are by default hidden from display on the recentchanges
-page, but will display in its feeds. The [[rcs]] must have implemented
-support for the `rcs_diff()` function for any diffs to be generated.
+change. The diffs can be toggled on the recentchanges page (requires
+javascript), and are also included in its feeds.
+
+The [[rcs]] must have implemented support for the `rcs_diff()` function for
+any diffs to be generated.
diff --git a/doc/plugins/sidebar/discussion.mdwn b/doc/plugins/sidebar/discussion.mdwn
index 42bc6a3e1..245fb1544 100644
--- a/doc/plugins/sidebar/discussion.mdwn
+++ b/doc/plugins/sidebar/discussion.mdwn
@@ -8,3 +8,5 @@ I needed to include inline directives into sidebars at different site sections t
 
 Then I came across the tip to include the quick=yes variable with the inline directive, where it is described as not showing page titles included with the meta-directive, and I thought, well if it lets me have it only this way, maybe I can restrain from using meta titles.   
 But to my surprise, even with the quick=yes variable included into the inline directive in the sidebars meta titles still are shown, no more forced rebuild when editing via cgi, which is amazing, but maybe it should be noted somewhere. One more time ikiwiki showed its bright face, thank you. --Boris
+
+How to use a different sidebar and its own CSS for SubPages under a certain directory?  -- Joe
diff --git a/doc/plugins/teximg.mdwn b/doc/plugins/teximg.mdwn
index f3cade85f..866b1ee05 100644
--- a/doc/plugins/teximg.mdwn
+++ b/doc/plugins/teximg.mdwn
@@ -6,9 +6,6 @@ that renders LaTeX formulas into images.
 
 Of course you will need LaTeX installed for this to work.
 
-See [this site](http://www.der-winnie.de/opensource/gsoc2007) for rendered
-images.
-
 ## configuration
 
 There are several configuration directives that can be used in the setup
diff --git a/doc/plugins/trail.mdwn b/doc/plugins/trail.mdwn
new file mode 100644
index 000000000..14b97e35a
--- /dev/null
+++ b/doc/plugins/trail.mdwn
@@ -0,0 +1,76 @@
+[[!template id=plugin name=trail author="[[Simon_McVittie|smcv]]"]]
+[[!tag type/chrome]]
+
+This plugin provides the [[ikiwiki/directive/trailoptions]],
+[[ikiwiki/directive/traillink]], [[ikiwiki/directive/trailitem]],
+and [[ikiwiki/directive/trailitems]] [[directives|ikiwiki/directive]].
+
+It's sometimes useful to have "trails" of pages in a wiki where each
+page links to the next and/or previous page. For instance, you could use
+this for a guided tour, sequence of chapters, or sequence of blog posts.
+
+In this plugin, a trail is represented by a page, and the pages in the
+trail are indicated by specially marked links within that page, or by
+including groups of pages with a [[ikiwiki/directive]].
+
+If using the default `page.tmpl`, each page automatically displays the
+trails that it's a member of (if any), with links to the trail and to
+the next and previous members. HTML `<link>` tags with the `prev`,
+`next` and `up` relations are also generated.
+
+The [[ikiwiki/directive/trailoptions]] directive sets options for the
+entire trail.
+
+Pages can be included in a trail in various ways:
+
+* The [[ikiwiki/directive/inline]] directive with `trail="yes"` sets up an
+  [[inline]], and at the same time adds the matching pages (from `pages` or
+  `pagenames`) to the trail. One use is to navigate through all posts in
+  a blog:
+
+        \[[!inline pages="page(./posts/*) and !*/Discussion" archive=yes
+          feedshow=10 quick=yes trail=yes]]
+
+  This only works if the trail and [[!iki plugins/inline desc=inline]]
+  plugins are both enabled.
+
+* The [[ikiwiki/directive/trailitems]] directive has optional `pages` and
+  `pagenames` options which behave the same as in [[inline]], but don't
+  produce any output in the page, so you can have trails that don't list
+  all their pages.
+
+* The [[ikiwiki/directive/traillink]] directive makes a visible link
+  and also adds the linked page to the trail. This will typically be
+  used in a bullet list, but could also be in paragraph text:
+
+        * [[!traillink Introduction]]
+        * [[!traillink "Chapter 1"]]
+        * [[!traillink Chapter_2]]
+        * [[!traillink Appendix_A]]
+
+  or
+
+        To use this software you must \[[!traillink install]] it,
+        \[[!traillink configuration text="configure it"]],
+        and finally \[[!traillink running|run_it]].
+
+  This also counts as a [[ikiwiki/WikiLink]] for things like the `link()`
+  [[ikiwiki/PageSpec]] item.
+
+* The [[ikiwiki/directive/trailitem]] directive adds a page to the trail
+  like `traillink`, but produces an invisible link, rather like `\[[!tag]]`:
+
+        To use this software you must \[[!traillink install]] it,
+        \[[!trailitem installing_from_packages]]
+        \[[!trailitem installing_from_source]]
+        \[[!traillink configuration text="configure it"]],
+        and finally \[[!traillink running|run_it]].
+        \[[!trailitem troubleshooting]]
+
+  Like `\[[!tag]]`, this still counts as a [[ikiwiki/WikiLink]] even though
+  there's no visible link.
+
+You can mix several of these directives in one page. The resulting
+trail will contain all of the pages matched by any of the directives,
+in the same order that the directives appear (unless you use the `sort` or
+`reverse` options on `\[[!trailoptions]]`).
diff --git a/doc/plugins/trail/discussion.mdwn b/doc/plugins/trail/discussion.mdwn
new file mode 100644
index 000000000..6c0b790b9
--- /dev/null
+++ b/doc/plugins/trail/discussion.mdwn
@@ -0,0 +1,105 @@
+I believe the `trail3-integrated` and `trail3-prebuild` branches address
+Joey's review comments from IRC:
+
+    06-12-2011 19:01:07 <joeyh>: ok, light review finished. so, if you want
+    to make a branch with inline trail=yes, and perhaps also adding a hook
+    so you don't need to inject, I think I can merge it right away
+
+I haven't published instructions for using this version as a
+standalone plugin, because it needs core and inline changes.
+
+Commits up to 63bb8b42 make the trail plugin better-integrated,
+including `\[[!inline trail=yes]]`. 63bb8b42 is the commit to
+merge if you don't like the design of my hooks.
+
+Commit 24168b99 adds a `build_affected` hook, run at about the
+same time as `render_backlinks`, and uses it to render the
+extra pages. This removes the need for `trail` to inject
+anything. In principle, backlinks etc. could use this hook
+too, if they weren't core.
+
+Commit d0dea308 on the `trail3-prebuild` branch adds a
+`prebuild` hook, which runs after everything has been scanned
+but before anything is rendered. This removes the need
+for `trail` to run its old `prerender` function in its
+render hooks (preprocess, pagetemplate etc.) to collate
+metadata before it renders anything. However, I'm not sure
+that this is really the right thing to do, which is why it's
+in its own branch: the `prebuild` hook is a lot like
+`needsbuild` (but later), so it's called even if no trail
+or trail member has actually been edited.
+
+For it to be useful for `trail`, the `prebuild` hook has to run
+after both pagespecs and sorting work. The other use case
+I've seen for a similar hook was for Giuseppe Bilotta to
+sort an inline-of-inlines by mtime of newest post, but that
+can't be the same hook, because it has to run after pagespecs
+work, but before sorting.
+
+--[[smcv]]
+
+> I've merged trail3-integrated, but not prebuild. I don't exactly dislike
+> prebuild, but dunno that the hook prolieration is worth the minor cleanup
+> it allows in trail. --[[Joey]]
+
+>> Hmm, t/trail.t is failing several tests here. To reproduce, I build the
+>> debian package from a clean state, or `rm -rf .t` between test runs. --[[Joey]]
+
+<pre>
+t/trail.t .................... 1/? 
+#   Failed test at t/trail.t line 211.
+#   Failed test at t/trail.t line 213.
+#   Failed test at t/trail.t line 215.
+#   Failed test at t/trail.t line 217.
+#   Failed test at t/trail.t line 219.
+#   Failed test at t/trail.t line 221.
+#   Failed test at t/trail.t line 223.
+#   Failed test at t/trail.t line 225.
+#   Failed test at t/trail.t line 227.
+#   Failed test at t/trail.t line 229.
+#   Failed test at t/trail.t line 231.
+</pre>
+
+> Looking at the first of these, it expected "trail=sorting n=sorting/new p="
+> but gets: "trail=sorting n=sorting/ancient p=sorting/new"
+>
+> Looking at the second failure, it expected "trail=sorting n=sorting/middle p=sorting/old$"
+> but got: "trail=sorting n=sorting/old p=sorting/end"
+> 
+> Perhaps a legitimate bug? --[[Joey]] 
+
+>> I saw this while developing, but couldn't reproduce it, and assumed
+>> I'd failed to update `blib` before `make test`, or some such.
+>> In fact it's a race condition, I think.
+>>
+>> The change and failure here is that `sorting.mdwn` is modified
+>> to sort its trail in reverse order of title. Previously, it
+>> was sorted by order of directives in the page, and secondarily
+>> by whatever sort order each directive specified (e.g.
+>> new, old and ancient were sorted by increasing age).
+>> `old` appearing between `new` and `ancient`, and `new` appearing
+>> between `end` and `old`, indicates that this re-sorting has not
+>> actually taken effect, and the old sort order is still used.
+>>
+>> I believe this is because the system time (as an integer) remained
+>> the same for the entire test, and mtimes as used in ikiwiki
+>> only have a 1-second resolution. We can either fix this with
+>> utime or sleep; I chose utime, since sleeping for 1 second would
+>> slow down the test significantly. Please merge or cherry-pick
+>> `smcv/trail-test` (there's only one commit). --[[smcv]]
+
+----
+
+[[!template id=gitbranch branch=smcv/ready/trail author=smcv]]
+
+Some later changes to trail:
+
+* Display the trail links at beginning/end of default `page.tmpl`
+  as suggested on IRC
+* Improve CSS, particularly in blueview and goldtype themes
+  ([example](http://blueview.hosted.pseudorandom.co.uk/posts/second_post/))
+* Fix a possible bug regarding state deletion
+
+--[[smcv]]
+
+> Applied --[[Joey]] 
diff --git a/doc/plugins/type/comments.mdwn b/doc/plugins/type/comments.mdwn
new file mode 100644
index 000000000..6eaa2c25a
--- /dev/null
+++ b/doc/plugins/type/comments.mdwn
@@ -0,0 +1 @@
+These plugins relate to [[plugins/comments]].
diff --git a/doc/plugins/wmd.mdwn b/doc/plugins/wmd.mdwn
index 2eac0788c..7202aece6 100644
--- a/doc/plugins/wmd.mdwn
+++ b/doc/plugins/wmd.mdwn
@@ -5,7 +5,7 @@
 [[mdwn]]. This plugin makes WMD be used for editing pages in the wiki.
 
 To use the plugin, you will need to install WMD. Download the [WMD
-source](http://ftp.netbsd.org/pub/NetBSD/packages/distfiles/wmd-1.0.1.zip).  In that zip file
+source](https://code.google.com/p/pagedown/).  In that zip file
 you'll find a few example html files, a readme and `wmd` directory.  Create
 a 'wmd' subdirectory in the ikiwiki `underlaydir` directory (ie `sudo mkdir
 /usr/share/ikiwiki/wmd`). Move the `wmd` directory into the directory you
diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index dcab041dc..2b8202655 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -1,4 +1,4 @@
-lkiwiki's plugin interface allows all kinds of useful [[plugins]] to be
+Ikiwiki's plugin interface allows all kinds of useful [[plugins]] to be
 written to extend ikiwiki in many ways. Despite the length of this page,
 it's not really hard. This page is a complete reference to everything a
 plugin might want to do. There is also a quick [[tutorial]].
@@ -31,20 +31,26 @@ is accomplished by calling various hooks provided by plugins.
 
 ### compiler
 
-As a compiler, ikiwiki starts by calling the `refresh` hook. Then it checks
-the wiki's source to find new or changed pages. The `needsbuild` hook is
-then called to allow manipulation of the list of pages that need to be
-built. 
-
-Now that it knows what pages it needs to build, ikiwiki runs two
-compile passes. First, it runs `scan` hooks, which collect metadata about
-the pages. Then it runs a page rendering pipeline, by calling in turn these
-hooks: `filter`, `preprocess`, `linkify`, `htmlize`, `indexhtml`,
-`pagetemplate`, `sanitize`, `format`.
-
-After all necessary pages are built, it calls the `change` hook. Finally,
-if a page is was deleted, the `delete` hook is called, and the files that
-page had previously produced are removed.
+As a compiler, ikiwiki starts by calling the
+[[`refresh`|plugins/write#refresh]] hook. Then it checks the wiki's source to
+find new or changed pages. The [[`needsbuild`|plugins/write#needsbuild]] hook
+is then called to allow manipulation of the list of pages that need to be
+built.
+
+Now that it knows what pages it needs to build, ikiwiki runs two compile
+passes. First, it runs [[`scan`|plugins/write#scan]] hooks, which collect
+metadata about the pages. Then it runs a page rendering pipeline, by calling
+in turn these hooks: [[`filter`|plugins/write#filter]],
+[[`preprocess`|plugins/write#preprocess]],
+[[`linkify`|plugins/write#linkify]], [[`htmlize`|plugins/write#htmlize]],
+[[`indexhtml`|plugins/write#indexhtml]],
+[[`pagetemplate`|plugins/write#pagetemplate]],
+[[`sanitize`|plugins/write#sanitize]], [[`format`|plugins/write#format]].
+
+After all necessary pages are built, it calls the
+[[`changes`|plugins/write#changes]] hook. Finally, if a page was deleted, the
+[[`delete`|plugins/write#delete]] hook is called, and the files that page had
+previously produced are removed.
 
 ### cgi
 
@@ -53,33 +59,39 @@ an example.
 
 Alice browses to a page and clicks Edit.
 
-* Ikiwiki is run as a cgi. It assigns Alice a session cookie, and,
-  by calling the `auth` hooks, sees that she is not yet logged in.
-* The `sessioncgi` hooks are then called, and one of them,
-  from the [[editpage]] plugin, notices that the cgi has been told "do=edit".
-* The [[editpage]] plugin calls the `canedit` hook to check if this
-  page edit is allowed. The [[signinedit]] plugin has a hook that says not:
-  Alice is not signed in.
-* The [[signinedit]] plugin then launches the signin process. A signin
-  page is built by calling the `formbuilder_setup` hook.
+* Ikiwiki is run as a cgi. It assigns Alice a session cookie, and, by calling
+  the [[`auth`|plugins/write#auth]] hooks, sees that she is not yet logged in.
+* The [[`sessioncgi`|plugins/write#sessioncgi]] hooks are then called, and one
+  of them, from the [[editpage]] plugin, notices that the cgi has been told
+  "do=edit".
+* The [[editpage]] plugin calls the [[`canedit`|plugins/write#canedit]] hook
+  to check if this page edit is allowed. The [[signinedit]] plugin has a hook
+  that says not: Alice is not signed in.
+* The [[signinedit]] plugin then launches the signin process. A signin page is
+  built by calling the [[`formbuilder_setup`|plugins/write#formbuilder]]
+  hook.
 
 Alice signs in with her openid.
 
-* The [[openid]] plugin's `formbuilder` hook sees that an openid was
-  entered in the signin form, and redirects to Alice's openid provider.
-* Alice's openid provider calls back to ikiwiki. The [[openid]] plugin
-  has an `auth` hook that finishes the openid signin process.
+* The [[openid]] plugin's [[`formbuilder`|plugins/write#formbuilder]] hook
+  sees that an openid was entered in the signin form, and redirects to Alice's
+  openid provider.
+* Alice's openid provider calls back to ikiwiki. The [[openid]] plugin has an
+  [[`auth`|plugins/write#auth]] hook that finishes the openid signin process.
 * Signin complete, ikiwiki returns to what Alice was doing before; editing
   a page.
-* Now all the `canedit` hooks are happy. The [[editpage]] plugin calls
-  `formbuilder_setup` to display the page editing form.
+* Now all the [[`canedit`|plugins/write#canedit]] hooks are happy. The
+  [[editpage]] plugin calls
+  [[`formbuilder_setup`|plugins/write#formbuilder]] to display the page
+  editing form.
 
 Alice saves her change to the page.
 
-* The [[editpage]] plugin's `formbuilder` hook sees that the Save button
-  was pressed, and calls the `checkcontent` and `editcontent` hooks.
-  Then it saves the page to disk, and branches into the compiler part
-  of ikiwiki to refresh the wiki.
+* The [[editpage]] plugin's [[`formbuilder`|plugins/write#formbuilder]] hook
+  sees that the Save button was pressed, and calls the
+  [[`checkcontent`|plugins/write#checkcontent]] and
+  [[`editcontent`|plugins/write#editcontent]] hooks.  Then it saves the page
+  to disk, and branches into the compiler part of ikiwiki to refresh the wiki.
 
 ## Types of plugins
 
@@ -165,7 +177,7 @@ is populated at this point, but other state has not yet been loaded.
 The function is passed no values. It's ok for the function to call
 `error()` if something isn't configured right.
 
-### refresh
+### <a name="refresh">refresh</a>
 
 	hook(type => "refresh", id => "foo", call => \&refresh);
 
@@ -173,7 +185,7 @@ This hook is called just before ikiwiki scans the wiki for changed files.
 It's useful for plugins that need to create or modify a source page. The
 function is passed no values.
 
-### needsbuild
+### <a name="needsbuild">needsbuild</a>
 
 	hook(type => "needsbuild", id => "foo", call => \&needsbuild);
 
@@ -187,7 +199,7 @@ modified version of its input. It can add or remove files from it.
 The second parameter passed to the function is a reference to an array of
 files that have been deleted.
 
-### scan
+### <a name="scan">scan</a>
 
 	hook(type => "scan", id => "foo", call => \&scan);
 
@@ -199,7 +211,7 @@ them to `%links`. Present in IkiWiki 2.40 and later.
 The function is passed named parameters "page" and "content". Its return
 value is ignored.
 
-### filter
+### <a name="filter">filter</a>
 
 	hook(type => "filter", id => "foo", call => \&filter);
 
@@ -207,7 +219,7 @@ Runs on the full raw source of a page, before anything else touches it, and
 can make arbitrary changes. The function is passed named parameters "page",
 "destpage", and "content". It should return the filtered content.
 
-### preprocess
+### <a name="preprocess">preprocess</a>
 
 Adding a preprocessor [[ikiwiki/directive]] is probably the most common use
 of a plugin.
@@ -250,7 +262,7 @@ format at preprocessor time. Text output by a preprocessor directive will
 be linkified and passed through markdown (or whatever engine is used to
 htmlize the page) along with the rest of the page.
 
-### linkify
+### <a name="linkify">linkify</a>
 
 	hook(type => "linkify", id => "foo", call => \&linkify);
 
@@ -263,7 +275,7 @@ Plugins that implement linkify must also implement a scan hook, that scans
 for the links on the page and adds them to `%links` (typically by calling
 `add_link`).
 
-### htmlize
+### <a name="htmlize">htmlize</a>
 
 	hook(type => "htmlize", id => "ext", call => \&htmlize);
 
@@ -287,7 +299,7 @@ like `Makefile` that have no extension.
 If `hook` is passed an optional "longname" parameter, this value is used
 when prompting a user to choose a page type on the edit page form.
 
-### indexhtml
+### <a name="indexhtml">indexhtml</a>
 
 	hook(type => "indexhtml", id => "foo", call => \&indexhtml);
 
@@ -298,7 +310,7 @@ update search indexes. Added in ikiwiki 2.54.
 The function is passed named parameters "page", "destpage", and "content".
 Its return value is ignored.
 
-### pagetemplate
+### <a name="pagetemplate">pagetemplate</a>
 
 	hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
 
@@ -333,7 +345,7 @@ page (next to Edit, RecentChanges, etc). The hook is passed a "page"
 parameter, and can return a list of html fragments to add to the action
 bar.
 
-### sanitize
+### <a name="sanitize">sanitize</a>
 
 	hook(type => "sanitize", id => "foo", call => \&sanitize);
 
@@ -343,7 +355,7 @@ modify the body of a page after it has been fully converted to html.
 The function is passed named parameters: "page", "destpage", and "content",
 and should return the sanitized content.
 
-### format
+### <a name="format">format</a>
 
 	hook(type => "format", id => "foo", call => \&format);
 
@@ -356,21 +368,48 @@ when the page is being previewed.)
 The function is passed named parameters: "page" and "content", and 
 should return the formatted content.
 
-### delete
+### build_affected
+
+	hook(type => "build_affected", id => "foo", call => \&build_affected);
+
+This hook is called after the directly changed pages have been built,
+and can cause extra pages to be built. If links and backlinks were provided
+by a plugin, this would be where that plugin would rebuild pages whose
+backlinks have changed, for instance. The [[trail]] plugin uses this hook
+to rebuild pages whose next or previous page has changed.
+
+The function should currently ignore its parameters. It returns a list with
+an even number of items (a hash in list context), where the first item of
+each pair is a page name to be rebuilt (if it was not already rebuilt), and
+the second is a log message resembling
+`building plugins/write because the phase of the moon has changed`.
+
+### <a name="delete">delete</a>
 
 	hook(type => "delete", id => "foo", call => \&delete);
 
-Each time a page or pages is removed from the wiki, the referenced function
+After a page or pages is removed from the wiki, the referenced function
 is called, and passed the names of the source files that were removed.
 
-### change
+### rendered
 
-	hook(type => "change", id => "foo", call => \&render);
+	hook(type => "rendered", id => "foo", call => \&rendered);
 
-Each time ikiwiki renders a change or addition (but not deletion) to the
+After ikiwiki renders a change or addition (but not deletion) to the
 wiki, the referenced function is called, and passed the names of the
 source files that were rendered.
 
+(This hook used to be called "change", but that was not accurate.
+For now, plugins using the old hook name will still work.)
+
+### <a name="changes">changes</a>
+
+	hook(type => "changes", id => "foo", call => \&changes);
+
+After ikiwiki renders changes to the wiki, the referenced function is
+called, and passed the names of the source files that were added, modified,
+or deleted.
+
 ### cgi
 
 	hook(type => "cgi", id => "foo", call => \&cgi);
@@ -383,7 +422,7 @@ parameters, and if it will handle this CGI request, output a page
 Note that cgi hooks are called as early as possible, before any ikiwiki
 state is loaded, and with no session information.
 
-### auth
+### <a name="auth">auth</a>
 
 	hook(type => "auth", id => "foo", call => \&auth);
 
@@ -396,7 +435,7 @@ object's "name" parameter to the authenticated user's name. Note that
 if the name is set to the name of a user who is not registered,
 a basic registration of the user will be automatically performed.
 
-### sessioncgi
+### <a name="sessioncgi">sessioncgi</a>
 
 	hook(type => "sessioncgi", id => "foo", call => \&sessioncgi);
 
@@ -405,7 +444,7 @@ is only run once a session object is available. It is passed both a CGI
 object and a session object. To check if the user is in fact signed in, you
 can check if the session object has a "name" parameter set.
 
-### canedit
+### <a name="canedit">canedit</a>
 
 	hook(type => "canedit", id => "foo", call => \&canedit);
 
@@ -445,7 +484,7 @@ bypass it). It works exactly like the `canedit` hook,
 but is passed the named parameters `cgi` (a CGI object), `session` (a
 session object), `src`, `srcfile`, `dest` and `destfile`.
 
-### checkcontent
+### <a name="checkcontent">checkcontent</a>
 	
 	hook(type => "checkcontent", id => "foo", call => \&checkcontent);
 
@@ -466,7 +505,7 @@ should return a message stating what the problem is, or a function
 that can be run to perform whatever action is necessary to allow the user
 to post the content.
 
-### editcontent
+### <a name="editcontent">editcontent</a>
 
 	hook(type => "editcontent", id => "foo", call => \&editcontent);
 
@@ -477,7 +516,7 @@ user, the page name, a `CGI` object, and the user's `CGI::Session`.
 
 It can modify the content as desired, and should return the content.
 
-### formbuilder
+### <a name="formbuilder">formbuilder</a>
 
 	hook(type => "formbuilder_setup", id => "foo", call => \&formbuilder_setup);
 	hook(type => "formbuilder", id => "foo", call => \&formbuilder);
diff --git a/doc/plugins/write/tutorial.mdwn b/doc/plugins/write/tutorial.mdwn
index 5345f71f2..1912c8a2f 100644
--- a/doc/plugins/write/tutorial.mdwn
+++ b/doc/plugins/write/tutorial.mdwn
@@ -81,8 +81,8 @@ textbook.
 
 	sub fib {
 		my $num=shift;
-		return 0 if $num == 1;
-		return 1 if $num == 2;
+		return 0 if $num == 0;
+		return 1 if $num == 1;
 		return fib($num - 1) + fib($num - 2);
 	}
 
@@ -92,7 +92,7 @@ And let's change the `preprocess` sub to use it:
 
 	sub preprocess {
 		my %params=@_;
-		my $num=$last++;
+		my $num=++$last;
 		return fib($num);
 	}
 
@@ -102,7 +102,7 @@ Feel free to try it out with a simple page like this:
 
 Looks like it works ok, doesn't it? That creates a page that lists:
 
-	1, 1, 3, 5, 8
+	1, 1, 2, 3, 5
 
 But what happens if there are two pages that both use fib? Try it out.
 If ikiwiki builds both pages in one pass, the sequence will continue
@@ -127,7 +127,7 @@ to start from 1 in every page that uses it.
 	sub preprocess {
 		my %params=@_;
 		my $page=$params{destpage};
-		my $num=$last{$page}++;
+		my $num=++$last{$page};
 		return fib($num);
 	}
 
@@ -145,7 +145,7 @@ Just insert these lines of code inside `preprocess`, in the appropriate
 spot:
 
 		if (exists $params{seed}) {
-			$last{$page}=$params{seed}-1;
+			$last{$page}=$params{seed};
 		}
 
 But this highlights another issue with the plugin. The `fib()` function is
@@ -158,7 +158,7 @@ Now, we could try to fix `fib()` to run in constant time for any number,
 but that's not the focus of this tutorial. Instead, let's concentrate on
 making the plugin use the existing function safely. A good first step would
 be a guard on how high it will go.
-	
+
 	my %last;
 
 	sub preprocess {
@@ -167,7 +167,7 @@ be a guard on how high it will go.
 		if (exists $params{seed}) {
 			$last{$page}=$params{seed}-1;
 		}
-		my $num=$last{$page}++;
+		my $num=++$last{$page};
 		if ($num > 25) {
 			error "can only calculate the first 25 numbers in the sequence";
 		}
@@ -178,10 +178,10 @@ Returning an error message like this is standard for preprocessor plugins,
 so that the user can look at the built page and see what went wrong.
 
 Are we done? Nope, there's still a security hole. Consider what `fib()`
-does for numbers less than 1. Or for any number that's not an integer. In
+does for numbers less than 0. Or for any number that's not an integer. In
 either case, it will run forever. Here's one way to fix that:
 
-		if (int($num) != $num || $num < 1) {
+		if (int($num) != $num || $num < 0) {
 			error "positive integers only, please";
 		}
 
diff --git a/doc/plugins/write/tutorial/discussion.mdwn b/doc/plugins/write/tutorial/discussion.mdwn
new file mode 100644
index 000000000..19f7e4084
--- /dev/null
+++ b/doc/plugins/write/tutorial/discussion.mdwn
@@ -0,0 +1,20 @@
+Thanks for the tutorial!
+
+But I think you have an error in the fib function! If you really start with
+
+    my $last = 0;
+
+and your fib function, you'll get this error, as you've produced a never ending recursion:
+
+    Deep recursion on subroutine "IkiWiki::Plugin::fib::fib" at ./fib.pm line 29.
+
+So the fib function should better look like this, which is its true definition (see [[Wikipedia|http://de.wikipedia.org/wiki/Fibonacci-Folge]], for example):
+
+	sub fib {
+		my $num=shift;
+		return 0 if $num == 0;
+		return 1 if $num == 1;
+		return fib($num - 1) + fib($num - 2);
+	}
+
+Just as a hint for people who run into this error while doing this tutorial.