first pass through comments documentation

Moved documentation out of contrib.

Mostly tweaked some wording. Moved documentation of various bits to other
pages (pagespec, etc), and linked to those.

Documented the new templates in wikitemplates.

Small quantities of documentation were removed. Particularly the list of
template variables, which I think is fairly obvious when editing the
template.

7 files changed, 68 insertions, 92 deletions

diff --git a/doc/ikiwiki/pagespec.mdwn b/doc/ikiwiki/pagespec.mdwn
index c78666c40..90b96c936 100644
--- a/doc/ikiwiki/pagespec.mdwn
+++ b/doc/ikiwiki/pagespec.mdwn
@@ -47,6 +47,8 @@ Some more elaborate limits can be added to what matches using these functions:
   wiki admins.
 * "`ip(address)`" - tests whether a modification is being made from the
   specified IP address.
+* "`postcomment(glob)`" - matches internal-use pages created by the
+  comments plugin as comments for pages that match the specified glob.
 
 For example, to match all pages in a blog that link to the page about music
 and were written in 2005:
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/comments.mdwn b/doc/plugins/comments.mdwn
new file mode 100644
index 000000000..347d7fc8d
--- /dev/null
+++ b/doc/plugins/comments.mdwn
@@ -0,0 +1,52 @@
+[[!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]], and comment pages can be matched
+using a special `postcomment()` [[ikiwiki/PageSpec]].
+
+There are some global options for the setup file:
+
+* `comments_shown_pagespec`: pages where comments will be displayed inline,
+  e.g. `blog/*` or `!*/discussion`.
+* `comments_open_pagespec`: pages where new comments can be posted, e.g.
+  `blog/* and created_after(close_old_comments)` or `!*/discussion`
+* `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
+
+Known issues:
+
+* Needs code review
+* The access control via postcomment() is rather strange (see [[discussion]] for more details)
+* There is some common code cargo-culted from other plugins (notably inline and editpage) which
+  should probably be shared
+* Joey doesn't think it should necessarily use internal pages (see [[discussion]])
+* Previews always say "unknown IP address"
+* Add `COMMENTOPENID`: the authenticated/verified user name, if and only if it was an OpenID
+* The default template should have a (?) icon next to unauthenticated users (with the IP address
+  as title) and an OpenID icon next to OpenIDs
diff --git a/doc/plugins/contrib/comments/discussion.mdwn b/doc/plugins/comments/discussion.mdwn
index 59740ec37..59740ec37 100644
--- a/doc/plugins/contrib/comments/discussion.mdwn
+++ b/doc/plugins/comments/discussion.mdwn
diff --git a/doc/plugins/contrib/comments.mdwn b/doc/plugins/contrib/comments.mdwn
deleted file mode 100644
index d2ca8d17d..000000000
--- a/doc/plugins/contrib/comments.mdwn
+++ /dev/null
@@ -1,91 +0,0 @@
-[[!template id=plugin name=comments author="[[Simon_McVittie|smcv]]"]]
-[[!tag type/useful]]
-
-This plugin adds "blog-style" comments. 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.
-
-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 plugin adds a new [[ikiwiki/PageSpec]] match type, `postcomment`, for use
-with `anonok_pagespec` from the [[plugins/anonok]] plugin or `locked_pages` from
-the [[plugins/lockedit]] plugin. Typical usage would be something like:
-
-    locked_pages => "!postcomment(*)"
-
-to allow non-admin users to comment on pages, but not edit anything. You can also do
-
-    anonok_pages => "postcomment(*)"
-
-to allow anonymous comments (the IP address will be used as the "author").
-
-There are some global options for the setup file:
-
-* `comments_shown_pagespec`: pages where comments will be displayed inline, e.g. `blog/*`
-  or `*/discussion`.
-* `comments_open_pagespec`: pages where new comments can be posted, e.g.
-  `blog/* and created_after(close_old_comments)` or `*/discussion`
-* `comments_pagename`: if this is e.g. `comment_` (the default), then comments on the
-  [[sandbox]] will be called something like `sandbox/comment_12`
-* `comments_allowdirectives`: if true (default false), comments may contain IkiWiki
-  directives
-* `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
-
-Templates that will display comments (by default that means `comments_display.tmpl`)
-can use the following additional `<TMPL_VAR>`s:
-
-* `COMMENTUSER`: the authenticated/verified user name, or undefined if the user was not signed in
-* `COMMENTIP`: the remote IP address, or undefined if not known (this is not currently recorded
-  for users who are signed in, who are assumed to be vaguely accountable)
-* `COMMENTAUTHOR`: a "prettier" version of the authenticated/verified user name (e.g. OpenIDs are
-  formatted the same way as in [[RecentChanges]]), or the result of localizing "Anonymous" if the
-  user was not signed in
-* `COMMENTAUTHORURL`: if the user was signed in with an OpenID, that URL; if the user was signed
-  in with some other username, a CGI URL that redirects to their user page (if any)
-
-This plugin also adds a `\[[!_comment]]` directive which is used when storing comments. This
-directive is for internal use only and shouldn't be used on pages that are edited in the usual way.
-
-This plugin aims to close the [[todo]] item "[[todo/supporting_comments_via_disussion_pages]]",
-and is currently available from [[smcv]]'s git repository on git.pseudorandom.co.uk (it's the
-`comments-rebase2` branch). A demo wiki with the plugin enabled is running at
-<http://www.pseudorandom.co.uk/2008/ikiwiki/demo/>; the
-[sandbox page](http://www.pseudorandom.co.uk/2008/ikiwiki/demo/sandbox/#comments) has some
-examples of comments.
-
-Known issues:
-
-* Needs code review
-* The access control via postcomment() is rather strange (see [[discussion]] for more details)
-* There is some common code cargo-culted from other plugins (notably inline and editpage) which
-  should probably be shared
-* Joey doesn't think it should necessarily use internal pages (see [[discussion]])
-* Previews always say "unknown IP address"
-* Add `COMMENTOPENID`: the authenticated/verified user name, if and only if it was an OpenID
-* The default template should have a (?) icon next to unauthenticated users (with the IP address
-  as title) and an OpenID icon next to OpenIDs
-
-> I haven't done a detailed code review, but I will say I'm pleased you
-> avoided re-implementing inline! --[[Joey]]
-
-Fixed issues:
-
-* Joey didn't think the `\[[!comments]]` directive was appropriate; comments now appear
-  on pages selected with a [[ikiwiki/pagespec]]
-* Joey thought that raw HTML should always be allowed; it now is
-* tbm wanted anonymous people to be able to enter their name and possibly email
-  address; a name and website can now be supplied
-* There is now an indication of who you're signed in as
-* Each comment is now one big \[[!_comment]] directive invocation, avoiding previous
-  issues with unambiguous and un-spoofable metadata
-* `\[[!comment]]` should be `\[[!_comment]]`, or a special filter/htmlize hook rather
-  than being a directive at all
-* [[todo/inline_plugin:_ability_to_override_the_feed_name]]
-* [[todo/inline_plugin:_hide_feed_buttons_if_empty]]
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/wikitemplates.mdwn b/doc/wikitemplates.mdwn
index babd70211..6fb4d5f49 100644
--- a/doc/wikitemplates.mdwn
+++ b/doc/wikitemplates.mdwn
@@ -29,6 +29,10 @@ located in /usr/share/ikiwiki/templates by default.
   form to wiki pages.
 * `searchquery.tmpl` - This is an omega template, used by the
   [[plugins/search]] plugin.
+* `comments_display.tmpl` - This template is used to display a comment
+  by the [[plugins/comments]] plugin.
+* `comments_form.tmpl` - This template is the comment post form for the
+  [[plugins/comments]] plugin.
 
 The [[plugins/pagetemplate]] plugin can allow individual pages to use a
 different template than `page.tmpl`.