Merge commit 'upstream/master' into prv/po

Conflicts:

	debian/control
	debian/copyright
	doc/ikiwiki/pagespec.mdwn

Signed-off-by: intrigeri <intrigeri@boum.org>

20 files changed, 282 insertions, 34 deletions

diff --git a/doc/plugins/aggregate.mdwn b/doc/plugins/aggregate.mdwn
index c40a6dc22..6fc87853b 100644
--- a/doc/plugins/aggregate.mdwn
+++ b/doc/plugins/aggregate.mdwn
@@ -9,9 +9,9 @@ New users of aggregate should enable the `aggregateinternal => 1` option in the
 .setup file. If you don't do so, you will need to enable the [[html]] plugin
 as well as aggregate itself, since feed entries will be stored as HTML.
 
-The [[meta]] and [[tag]] plugins are also recommended. The
-[[htmltidy]] plugin is suggested, since feeds can easily contain html
-problems, some of which tidy can fix.
+The [[meta]] and [[tag]] plugins are also recommended. Either the
+[[htmltidy]] or [[htmlbalance]] plugin is suggested, since feeds can easily
+contain html problems, some of which these plugins can fix.
 
 You will need to run ikiwiki periodically from a cron job, passing it the
 --aggregate parameter, to make it check for new posts. Here's an example
diff --git a/doc/plugins/aggregate/discussion.mdwn b/doc/plugins/aggregate/discussion.mdwn
index 1db6240d5..1a9844577 100644
--- a/doc/plugins/aggregate/discussion.mdwn
+++ b/doc/plugins/aggregate/discussion.mdwn
@@ -35,7 +35,7 @@ Two things aren't working as I'd expect:
 > problem. You can see the feed validator complain about it here:
 > <http://feedvalidator.org/check.cgi?url=http%3A%2F%2Fwww.davidj.org%2Frss.xml>
 > 
-> It's sorta unfortunate that [[cpan XML::Feed]] doesn't just assume the
+> It's sorta unfortunate that [[!cpan XML::Feed]] doesn't just assume the
 > un-esxaped html is part of the description field. Probably other feed
 > parsers are more lenient. --[[Joey]]
 
diff --git a/doc/plugins/anonok.mdwn b/doc/plugins/anonok.mdwn
index 2a8a922cd..ab2f744e2 100644
--- a/doc/plugins/anonok.mdwn
+++ b/doc/plugins/anonok.mdwn
@@ -5,5 +5,10 @@ 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
 by default.
 
-The plugin also has a configuration setting, `anonok_pagespec`. This
+The plugin also has a configuration setting, `anonok_pages`. This
 [[PageSpec]] can be used to allow anonymous editing of matching pages.
+
+If you're using the [[comments]] plugin, you can allow anonymous comments
+to be posted by setting:
+
+	anonok_pages => "postcomment(*)"
diff --git a/doc/plugins/calendar/discussion.mdwn b/doc/plugins/calendar/discussion.mdwn
index 148b83522..9d57b7a1e 100644
--- a/doc/plugins/calendar/discussion.mdwn
+++ b/doc/plugins/calendar/discussion.mdwn
@@ -2,3 +2,5 @@ It would be nice if the "month" type calendar could collect all of the
 matching pages on a given date in some inline type way. --[[DavidBremner]]
 
 Is it possible to get the calendar to link to pages based not on their timestamp (as I understand that it does now, or have I misunderstood this?) and instead on for example their location in a directory hierarchy. That way the calendar could be used as a planning / timeline device which I think would be great. --[[Alexander]]
+
+I would like the ability to specify relative previous months. This way I could have a sidebar with the last three months by specifying no month, then 'month="-1"' and 'month="-2"'. Negative numbers for the month would otherwise be invalid, so this shouldn't produce any conflicts with expected behavior. (Right?) -- [[StevenBlack]]
diff --git a/doc/plugins/comments.mdwn b/doc/plugins/comments.mdwn
new file mode 100644
index 000000000..72b11af64
--- /dev/null
+++ b/doc/plugins/comments.mdwn
@@ -0,0 +1,43 @@
+[[!template id=plugin name=comments author="[[Simon_McVittie|smcv]]"]]
+[[!tag type/useful]]
+
+This plugin adds "blog-style" comments. Unlike the wiki-style freeform 
+Discussion pages, these comments are posted by a simple form, cannot later
+be edited, and rss/atom feeds are provided of each page's comments.
+
+When using this plugin, you should also enable [[htmlscrubber]] and either
+[[htmltidy]] or [[htmlbalance]]. Directives are filtered out by default, to
+avoid commenters slowing down the wiki by causing time-consuming
+processing. As long as the recommended plugins are enabled, comment
+authorship should hopefully be unforgeable by CGI users.
+
+The intention is that on a non-wiki site (like a blog) you can lock all
+pages for admin-only access, then allow otherwise unprivileged (or perhaps
+even anonymous) users to comment on posts. See the documentation of the
+[[lockedit]] and [[anonok]] pages for details on locking down a wiki so
+users can only post comments.
+
+Individual comments are stored as internal-use pages named something like
+`page/comment_1`, `page/comment_2`, etc. These pages internally use a
+`\[[!_comment]]` [[ikiwiki/directive]].
+
+There are some global options for the setup file:
+
+* `comments_pagespec`: [[ikiwiki/PageSpec]] of pages where comments are
+  allowed. The default is not to allow comments on any pages. To allow
+  comments to all posts to a blog, you could use
+  `blog/posts/* and !*/Discussion`.
+* `comments_closed_pagespec`: [[ikiwiki/PageSpec]] of pages where
+  posting of new comments is closed, but any existing comments will still
+  be displayed. Often you will list a set of individual pages here.
+  For example: `blog/controversial or blog/flamewar`
+* `comments_pagename`: if this is e.g. `comment_` (the default), then
+  comment pages will be named something like `page/comment_12`
+* `comments_allowdirectives`: if true (default false), comments may
+  contain IkiWiki [[directives|ikiwiki/directive]]
+* `comments_commit`: if true (default true), comments will be committed to
+  the version control system
+* `comments_allowauthor`: if true (default false), anonymous commenters may
+  specify a name for themselves, and the \[[!meta author]] and
+  \[[!meta authorurl]] directives will not be overridden by the comments
+  plugin
diff --git a/doc/plugins/comments/discussion.mdwn b/doc/plugins/comments/discussion.mdwn
new file mode 100644
index 000000000..2a87a3d93
--- /dev/null
+++ b/doc/plugins/comments/discussion.mdwn
@@ -0,0 +1,163 @@
+## Why internal pages? (unresolved)
+
+Comments are saved as internal pages, so they can never be edited through the CGI,
+only by direct committers.
+
+> So, why do it this way, instead of using regular wiki pages in a
+> namespace, such as `$page/comments/*`? Then you could use [[plugins/lockedit]] to
+> limit editing of comments in more powerful ways. --[[Joey]]
+
+>> Er... I suppose so. I'd assumed that these pages ought to only exist as inlines
+>> rather than as individual pages (same reasoning as aggregated posts), though.
+>>
+>> lockedit is actually somewhat insufficient, since `check_canedit()`
+>> doesn't distinguish between creation and editing; I'd have to continue to use
+>> some sort of odd hack to allow creation but not editing.
+>>
+>> I also can't think of any circumstance where you'd want a user other than
+>> admins (~= git committers) and possibly the commenter (who we can't check for
+>> at the moment anyway, I don't think?) to be able to edit comments - I think
+>> user expectations for something that looks like ordinary blog comments are
+>> likely to include "others can't put words into my mouth".
+>>
+>> My other objection to using a namespace is that I'm not particularly happy about
+>> plugins consuming arbitrary pieces of the wiki namespace - /discussion is bad
+>> enough already. Indeed, this very page would accidentally get matched by rules
+>> aiming to control comment-posting... :-) --[[smcv]]
+
+>>> Thinking about it, perhaps one way to address this would be to have the suffix
+>>> (e.g. whether commenting on Sandbox creates sandbox/comment1 or sandbox/c1 or
+>>> what) be configurable by the wiki admin, in the same way that recentchanges has
+>>> recentchangespage => 'recentchanges'? I'd like to see fewer hard-coded page
+>>> names in general, really - it seems odd to me that shortcuts and smileys
+>>> hard-code the name of the page to look at. Perhaps I could add
+>>> discussionpage => 'discussion' too? --[[smcv]]
+
+>>> (I've now implemented this in my branch. --[[smcv]])
+
+>> The best reason to keep the pages internal seems to me to be that you
+>> don't want the overhead of every comment spawning its own wiki page. --[[Joey]]
+
+## Formats (resolved)
+
+The plugin now allows multiple comment formats while still using internal
+pages; each comment is saved as a page containing one `\[[!comment]]` directive,
+which has a superset of the functionality of [[ikiwiki/directives/format]].
+
+## Access control (unresolved?)
+
+By the way, I think that who can post comments should be controllable by
+the existing plugins opendiscussion, anonok, signinedit, and lockedit. Allowing
+posting comments w/o any login, while a nice capability, can lead to
+spam problems. So, use `check_canedit` as at least a first-level check?
+--[[Joey]]
+
+> This plugin already uses `check_canedit`, but that function doesn't have a concept
+> of different actions. The hack I use is that when a user comments on, say, sandbox,
+> I call `check_canedit` for the pseudo-page "sandbox[postcomment]". The
+> special `postcomment(glob)` [[ikiwiki/pagespec]] returns true if the page ends with
+> "[postcomment]" and the part before (e.g. sandbox) matches the glob. So, you can
+> have postcomment(blog/*) or something. (Perhaps instead of taking a glob, postcomment
+> should take a pagespec, so you can have postcomment(link(tags/commentable))?)
+>
+> This is why `anonok_pages => 'postcomment(*)'` and `locked_pages => '!postcomment(*)'`
+> are necessary to allow anonymous and logged-in editing (respectively).
+>
+>> I changed that to move the flag out of the page name, and into a variable that the `match_postcomment`
+>> function checks for. Other ugliness still applies. :-) --[[Joey]] 
+>
+> This is ugly - one alternative would be to add `check_permission()` that takes a
+> page and a verb (create, edit, rename, remove and maybe comment are the ones I
+> can think of so far), use that, and port the plugins you mentioned to use that
+> API too. This plugin could either call `check_can("$page/comment1", 'create')` or
+> call `check_can($page, 'comment')`.
+> 
+> One odd effect of the code structure I've used is that we check for the ability to
+> create the page before we actually know what page name we're going to use - when
+> posting the comment I just increment a number until I reach an unused one - so
+> either the code needs restructuring, or the permission check for 'create' would
+> always be for 'comment1' and never 'comment123'. --[[smcv]]
+
+>> Now resolved, in fact --[[smcv]]
+
+> Another possibility is to just check for permission to edit (e.g.) `sandbox/comment1`.
+> However, this makes the "comments can only be created, not edited" feature completely
+> reliant on the fact that internal pages can't be edited. Perhaps there should be a
+> `editable_pages` pagespec, defaulting to `'*'`? --[[smcv]]
+
+## comments directive vs global setting (resolved?)
+
+When comments have been enabled generally, you still need to mark which pages
+can have comments, by including the `\[[!comments]]` directive in them. By default,
+this directive expands to a "post a comment" link plus an `\[[!inline]]` with
+the comments. [This requirement has now been removed --[[smcv]]]
+
+> I don't like this, because it's hard to explain to someone why they have
+> to insert this into every post to their blog. Seems that the model used
+> for discussion pages could work -- if comments are enabled, automatically
+> add the comment posting form and comments to the end of each page.
+> --[[Joey]]
+
+>> I don't think I'd want comments on *every* page (particularly, not the
+>> front page). Perhaps a pagespec in the setup file, where the default is "*"?
+>> Then control freaks like me could use "link(tags/comments)" and tag pages
+>> as allowing comments.
+>>
+>>> Yes, I think a pagespec is the way to go. --[[Joey]]
+
+>>>> Implemented --[[smcv]]
+
+>> 
+>> The model used for discussion pages does require patching the existing
+>> page template, which I was trying to avoid - I'm not convinced that having
+>> every possible feature hard-coded there really scales (and obviously it's
+>> rather annoying while this plugin is on a branch). --[[smcv]]
+
+>>> Using the template would allow customising the html around the comments
+>>> which seems like a good thing? --[[Joey]]
+
+>>>> The \[[!comments]] directive is already template-friendly - it expands to
+>>>> the contents of the template `comments_embed.tmpl`, possibly with the
+>>>> result of an \[[!inline]] appended. I should change `comments_embed.tmpl`
+>>>> so it uses a template variable `INLINE` for the inline result rather than
+>>>> having the perl code concatenate it, which would allow a bit more
+>>>> customization (whether the "post" link was before or after the inline).
+>>>> Even if you want comments in page.tmpl, keeping the separate comments_embed.tmpl
+>>>> and having a `COMMENTS` variable in page.tmpl might be the way forward,
+>>>> since the smaller each templates is, the easier it will be for users
+>>>> to maintain a patched set of templates. (I think so, anyway, based on what happens
+>>>> with dpkg prompts in Debian packages with monolithic vs split
+>>>> conffiles.) --[[smcv]]
+
+>>>>> I've switched my branch to use page.tmpl instead; see what you think? --[[smcv]]
+
+## Raw HTML (resolved?)
+
+Raw HTML was not initially allowed by default (this was configurable).
+
+> I'm not sure that raw html should be a problem, as long as the
+> htmlsanitizer and htmlbalanced plugins are enabled. I can see filtering
+> out directives, as a special case. --[[Joey]]
+
+>> Right, if I sanitize each post individually, with htmlscrubber and either htmltidy
+>> or htmlbalance turned on, then there should be no way the user can forge a comment;
+>> I was initially wary of allowing meta directives, but I think those are OK, as long
+>> as the comment template puts the \[[!meta author]] at the *end*. Disallowing
+>> directives is more a way to avoid commenters causing expensive processing than
+>> anything else, at this point.
+>>
+>> I've rebased the plugin on master, made it sanitize individual posts' content
+>> and removed the option to disallow raw HTML. Sanitizing individual posts before
+>> they've been htmlized required me to preserve whitespace in the htmlbalance
+>> plugin, so I did that. Alternatively, we could htmlize immediately and always
+>> save out raw HTML? --[[smcv]]
+
+>>> There might be some use cases for other directives, such as img, in
+>>> comments.
+>>> 
+>>> I don't know if meta is "safe" (ie, guaranteed to be inexpensive and not
+>>> allow users to do annoying things) or if it will continue to be in the
+>>> future. Hard to predict really, all that can be said with certainty is
+>>> all directives will contine to be inexpensive and safe enough that it's
+>>> sensible to allow users to (ab)use them on open wikis.
+>>> --[[Joey]]
diff --git a/doc/plugins/contrib/headinganchors.mdwn b/doc/plugins/contrib/headinganchors.mdwn
index ef2fa122a..c80cc0b49 100644
--- a/doc/plugins/contrib/headinganchors.mdwn
+++ b/doc/plugins/contrib/headinganchors.mdwn
@@ -12,9 +12,9 @@ rst and any other format that produces html. The code is available here:
 	use strict;
 	use IkiWiki 2.00;
 
-	sub import { #{{{
+	sub import {
 	        hook(type => "sanitize", id => "headinganchors", call => \&headinganchors);
-	} # }}}
+	}
 
 	sub text_to_anchor {
 	        my $str = shift;
@@ -26,11 +26,11 @@ rst and any other format that produces html. The code is available here:
 	        return $str;
 	}
 
-	sub headinganchors (@) { #{{{
+	sub headinganchors (@) {
 	        my %params=@_;
 	        my $content=$params{content};
 	        $content=~s{<h([0-9])>([^>]*)</h([0-9])>}{'<h'.$1.' id="'.text_to_anchor($2).'">'.$2.'</h'.$3.'>'}gie;
 	        return $content;
-	} # }}}
+	}
 
 	1
diff --git a/doc/plugins/contrib/po.mdwn b/doc/plugins/contrib/po.mdwn
index 0fd06cb81..f90ffeed2 100644
--- a/doc/plugins/contrib/po.mdwn
+++ b/doc/plugins/contrib/po.mdwn
@@ -160,3 +160,6 @@ Any thoughts on this?
 >>>>> I am able to do myself in this area. --[[intrigeri]]
 >>>>>>
 >>>>>> I came up with a patch for the WrapI18N issue --[[Joey]]
+
+I've set this plugin development aside for a while. I will be back and
+finish it at some point in the first quarter of 2009. --[[intrigeri]]
diff --git a/doc/plugins/contrib/siterel2pagerel.mdwn b/doc/plugins/contrib/siterel2pagerel.mdwn
index 956b6728f..9b09657bf 100644
--- a/doc/plugins/contrib/siterel2pagerel.mdwn
+++ b/doc/plugins/contrib/siterel2pagerel.mdwn
@@ -13,11 +13,11 @@ other format that produces html. The code is available here:
 	use strict;
 	use IkiWiki 2.00;
 
-	sub import { #{{{
+	sub import {
 	        hook(type => "sanitize", id => "siterel2pagerel", call => \&siterel2pagerel);
-	} # }}}
+	}
 
-	sub siterel2pagerel (@) { #{{{
+	sub siterel2pagerel (@) {
 	        my %params=@_;
 	        my $baseurl=IkiWiki::baseurl($params{page});
 	        my $content=$params{content};
@@ -25,6 +25,6 @@ other format that produces html. The code is available here:
 	        $content=~s/(<img(?:\s+(?:class|id|width|height)\s*="?\w+"?)*)\s+src=\s*"\/([^"]*)"/$1 src="$baseurl$2"/mig;
 	        # FIXME: do <script and everything else that can have URLs in it
 	        return $content;
-	} # }}}
+	}
 
 	1
diff --git a/doc/plugins/contrib/unixauth.mdwn b/doc/plugins/contrib/unixauth.mdwn
index d91ed45f1..76a847744 100644
--- a/doc/plugins/contrib/unixauth.mdwn
+++ b/doc/plugins/contrib/unixauth.mdwn
@@ -22,7 +22,7 @@ __Security__: [As with passwordauth](/security/#index14h2), be wary of sending u
 
     --- Wrapper.pm.orig 2008-07-29 00:09:10.000000000 -0400
     +++ Wrapper.pm
-    @@ -28,7 +28,7 @@ sub gen_wrapper () { #{{{
+    @@ -28,7 +28,7 @@ sub gen_wrapper () {
         my @envsave;
         push @envsave, qw{REMOTE_ADDR QUERY_STRING REQUEST_METHOD REQUEST_URI
                        CONTENT_TYPE CONTENT_LENGTH GATEWAY_INTERFACE
@@ -46,16 +46,16 @@ __Security__: [As with passwordauth](/security/#index14h2), be wary of sending u
     use strict;
     use IkiWiki 2.00;
     
-    sub import { #{{{
+    sub import {
         hook(type => "getsetup", id => "unixauth", call => \&getsetup);
             hook(type => "formbuilder_setup", id => "unixauth",
                 call => \&formbuilder_setup);
             hook(type => "formbuilder", id => "unixauth",
                 call => \&formbuilder);
         hook(type => "sessioncgi", id => "unixauth", call => \&sessioncgi);
-    } # }}}
+    }
     
-    sub getsetup () { #{{{
+    sub getsetup () {
         return
         unixauth_type => {
                 type => "string",
@@ -83,10 +83,10 @@ __Security__: [As with passwordauth](/security/#index14h2), be wary of sending u
                 safe => 0,
                 rebuild => 1,
         },
-    } #}}}
+    }
     
     # Checks if a string matches a user's password, and returns true or false.
-    sub checkpassword ($$;$) { #{{{
+    sub checkpassword ($$;$) {
         my $user=shift;
         my $password=shift;
         my $field=shift || "password";
@@ -131,9 +131,9 @@ __Security__: [As with passwordauth](/security/#index14h2), be wary of sending u
         }
     
         return $ret;
-    } #}}}
+    }
     
-    sub formbuilder_setup (@) { #{{{
+    sub formbuilder_setup (@) {
         my %params=@_;
     
         my $form=$params{form};
@@ -204,7 +204,7 @@ __Security__: [As with passwordauth](/security/#index14h2), be wary of sending u
         }
     }
     
-    sub formbuilder (@) { #{{{
+    sub formbuilder (@) {
         my %params=@_;
     
         my $form=$params{form};
@@ -225,12 +225,12 @@ __Security__: [As with passwordauth](/security/#index14h2), be wary of sending u
                         my $user_name=$form->field('name');
                 }
         }
-    } #}}}
+    }
     
-    sub sessioncgi ($$) { #{{{
+    sub sessioncgi ($$) {
         my $q=shift;
         my $session=shift;
-    } #}}}
+    }
     
     1
 
diff --git a/doc/plugins/contrib/unixauth/discussion.mdwn b/doc/plugins/contrib/unixauth/discussion.mdwn
index dfa4fe6cc..232649863 100644
--- a/doc/plugins/contrib/unixauth/discussion.mdwn
+++ b/doc/plugins/contrib/unixauth/discussion.mdwn
@@ -32,3 +32,7 @@ I've added support for [checkpassword](http://cr.yp.to/checkpwd/interface.html),
 > to disentangle the two locks. --[[Joey]]
 
 >> Ah, ok, I misunderstood your comment. I'll see what I can figure out. --[[schmonz]]
+
+>>> My time's been limited for this, but I just saw [[todo/avoid_thrashing]]. How does that interact with pwauth or checkpassword? --[[schmonz]]
+
+>>>> The DOS still happens, it just uses less memory. --[[Joey]]
diff --git a/doc/plugins/cutpaste.mdwn b/doc/plugins/cutpaste.mdwn
index 1b78e60fc..f74f8a269 100644
--- a/doc/plugins/cutpaste.mdwn
+++ b/doc/plugins/cutpaste.mdwn
@@ -1,4 +1,4 @@
-[[!template id=plugin name=toggle author="[[Enrico]]"]]
+[[!template id=plugin name=cutpaste author="[[Enrico]]"]]
 [[!tag type/chrome]]
 
 This plugin provides the [[ikiwiki/directive/cut]],
diff --git a/doc/plugins/htmlbalance.mdwn b/doc/plugins/htmlbalance.mdwn
new file mode 100644
index 000000000..f4e2298ee
--- /dev/null
+++ b/doc/plugins/htmlbalance.mdwn
@@ -0,0 +1,9 @@
+[[!template id=plugin name=htmlbalance author="[[Simon_McVittie|smcv]]"]]
+[[!tag type/html]]
+
+This plugin ensures that the HTML emitted by ikiwiki contains well-balanced
+HTML tags, by parsing it with [[!cpan HTML::TreeBuilder]] and re-serializing it. This
+acts as a lighter-weight alternative to [[plugins/htmltidy]]; it doesn't
+ensure validity, but it does at least ensure that formatting from a
+blog post pulled in by the [[ikiwiki/directive/inline]] directive doesn't
+leak into the rest of the page.
diff --git a/doc/plugins/htmlbalance/discussion.mdwn b/doc/plugins/htmlbalance/discussion.mdwn
new file mode 100644
index 000000000..c66528a4f
--- /dev/null
+++ b/doc/plugins/htmlbalance/discussion.mdwn
@@ -0,0 +1,10 @@
+Would it be possible to use [[!cpan HTML::Entities]] rather than
+`XML::Atom::Util` for encoding entities? The former is already an ikiwiki
+dependency (via [[!cpan HTML::Parser]]).
+
+> Now switched to HTML::Entities --[[Joey]]
+
+I also wonder if there's any benefit to using this plugin aside from with
+aggregate. Perhaps a small one but aggregate seems like the main case..
+wondering if it would be better to just have aggregate balanace the html
+automatically and do away with the separate plugin. --[[Joey]]
diff --git a/doc/plugins/htmlscrubber.mdwn b/doc/plugins/htmlscrubber.mdwn
index 7db372e1b..b9f7e6d22 100644
--- a/doc/plugins/htmlscrubber.mdwn
+++ b/doc/plugins/htmlscrubber.mdwn
@@ -32,7 +32,7 @@ other HTML-related functionality, such as whether [[meta]] allows
 potentially unsafe HTML tags.
 
 The `htmlscrubber_skip` configuration setting can be used to skip scrubbing
-of some pages. Set it to a [[PageSpec]], such as "!*/Discussion", and pages
+of some pages. Set it to a [[ikiwiki/PageSpec]], such as "!*/Discussion", and pages
 matching that can have all the evil CSS, JavsScript, and unsafe html
 elements you like. One safe way to use this is to use [[lockedit]] to lock
 those pages, so only admins can edit them.
diff --git a/doc/plugins/htmltidy.mdwn b/doc/plugins/htmltidy.mdwn
index f675a01ae..580e56f59 100644
--- a/doc/plugins/htmltidy.mdwn
+++ b/doc/plugins/htmltidy.mdwn
@@ -7,4 +7,5 @@ emitted by ikiwiki. Besides being nicely formatted, this helps ensure that
 even if users enter suboptimal html, your wiki generates valid html.
 
 Note that since tidy is an external program, that is run each time a page
-is built, this plugin will slow ikiwiki down somewhat.
+is built, this plugin will slow ikiwiki down somewhat. [[plugins/htmlbalance]]
+might provide a faster alternative.
diff --git a/doc/plugins/lockedit.mdwn b/doc/plugins/lockedit.mdwn
index 71bf232ab..d2e98e07a 100644
--- a/doc/plugins/lockedit.mdwn
+++ b/doc/plugins/lockedit.mdwn
@@ -17,6 +17,10 @@ One handy thing to do if you're using ikiwiki for your blog is to lock
 posts in your blog, while still letting them comment via the Discussion
 pages.
 
+Alternatively, if you're using the [[comments]] plugin, you can lock
+"!postcomment(*)" to allow users to comment on pages, but not edit anything
+else.
+
 Wiki administrators can always edit locked pages. The [[ikiwiki/PageSpec]]
 can specify that some pages are not locked for some users. For example,
 "important_page and !user(joey)" locks `important_page` while still
diff --git a/doc/plugins/pagecount.mdwn b/doc/plugins/pagecount.mdwn
index 6235963d3..a56027e60 100644
--- a/doc/plugins/pagecount.mdwn
+++ b/doc/plugins/pagecount.mdwn
@@ -6,5 +6,5 @@ This plugin provides the [[ikiwiki/directive/pagecount]]
 currently in the wiki.
 
 If it is turned on it can tell us that this wiki includes
-[[!pagecount pages="* and !recentchanges"]]
-pages, of which [[!pagecount pages="*/Discussion"]] are discussion pages.
+[[!pagecount ]] pages, of which
+[[!pagecount pages="*/Discussion"]] are discussion pages.
diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index abcabbdc3..9b5cf27f7 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -55,8 +55,8 @@ plugin, and a "call" parameter, which tells what function to call for the
 hook.
 
 An optional "last" parameter, if set to a true value, makes the hook run
-after all other hooks of its type. Useful if the hook depends on some other
-hook being run first.
+after all other hooks of its type, and an optional "first" parameter makes
+it run first. Useful if the hook depends on some other hook being run first.
 
 ## Types of hooks
 
@@ -696,11 +696,15 @@ This can be called when creating a new page, to determine what filename
 to save the page to. It's passed a page name, and its type, and returns
 the name of the file to create, relative to the srcdir.
 
-#### `targetpage($$)`
+#### `targetpage($$;$)`
 
 Passed a page and an extension, returns the filename that page will be
 rendered to.
 
+Optionally, a third parameter can be passed, to specify the preferred
+filename of the page. For example, `targetpage("foo", "rss", "feed")`
+will yield something like `foo/feed.rss`.
+
 ## Miscellaneous
 
 ### Internal use pages
diff --git a/doc/plugins/write/discussion.mdwn b/doc/plugins/write/discussion.mdwn
index 9a36d7b0b..24a556ffe 100644
--- a/doc/plugins/write/discussion.mdwn
+++ b/doc/plugins/write/discussion.mdwn
@@ -43,4 +43,4 @@ distributed wiki.
 
 ---
 
-I would find this page clearer split up into sub-pages. Does anyone agree/disagree? -- [[JonDowland]]
+I would find this page clearer split up into sub-pages. Does anyone agree/disagree? -- [[users/Jon]]