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.

1 files changed, 52 insertions, 0 deletions

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