Move some discussion to discussion/

[ikiwiki.git] / doc / plugins / contrib / comments.mdwn

diff --git a/doc/plugins/contrib/comments.mdwn b/doc/plugins/contrib/comments.mdwn
index 3e6dcfd769c451067abab312926c5a5c5dc65c9b..891d3dee563513f0bc191a871dbc46888433fe54 100644 (file)
--- a/doc/plugins/contrib/comments.mdwn
+++ b/doc/plugins/contrib/comments.mdwn
@@ -5,33 +5,10 @@ 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.
 
 (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.
 

-Comments are saved as internal pages, so they can never be edited through the CGI,
-only by direct committers. Currently, comments are always in [[ikiwiki/markdown]].
-
-> 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]]
-
-Directives and raw HTML are filtered out by default, and comment authorship should
-hopefully be unforgeable by CGI users.
+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.

 
 > 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
 
 > 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


@@ -44,30 +21,21 @@ hopefully be unforgeable by CGI users.
 >> directives is more a way to avoid commenters causing expensive processing than
 >> anything else, at this point.
 >>
 >> directives is more a way to avoid commenters causing expensive processing than
 >> anything else, at this point.
 >>

->> I've rebased the plugin on master and made it sanitize individual posts' content now.
->> Disallowing HTML is still optional and on by default, but it's trivial to remove
->> the code. --[[smcv]]
-
-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.
-
-> 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.
->>
->> 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]]
+>> 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]]

 
 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 plugin adds a new [[ikiwiki/PageSpec]] match type, `postcomment`, for use
 with `anonok_pagespec` from the [[plugins/anonok]] plugin or `locked_pages` from


@@ -81,25 +49,23 @@ to allow non-admin users to comment on pages, but not edit anything. You can als
 
 to allow anonymous comments (the IP address will be used as the "author").
 
 
 to allow anonymous comments (the IP address will be used as the "author").
 

-> This is still called postcomment, although I've renamed the rest of the plugin
-> to comments as suggested on #ikiwiki --[[smcv]]
-
-Optional parameters to the comments directive:
+There are some global options for the setup file:

 
 

-* `commit=no`: by default, comments are committed to version control. Use this to
-  disable commits.
-* `allowhtml=yes`: by default, raw HTML is filtered out. Use this to allow HTML
-  (you should enable [[plugins/htmlscrubber]] and either [[plugins/htmltidy]] or
-  [[plugins/contrib/htmlbalance]] if you do this).
-* `allowdirectives=yes`: by default, IkiWiki directives are filtered out. Use this
-  to allow directives (avoid enabling any [[plugins/type/slow]] directives if you
-  do this).
-* `closed=yes`: use this to prevent new comments while still displaying existing ones.
-* `atom`, `rss`, `feeds`, `feedshow`, `timeformat`, `feedonly`: the same as for [[plugins/inline]]
+* `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

 
 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
 
 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

-`postcomment` branch).
+`postcomment` branch). A demo wiki with the plugin enabled is running at
+<http://www.pseudorandom.co.uk/2008/ikiwiki/demo/>.

 
 Known issues:
 
 
 Known issues:
 


@@ -107,10 +73,15 @@ Known issues:
 * The access control via postcomment() is rather strange
 * There is some common code cargo-culted from other plugins (notably inline and editpage) which
   should probably be shared
 * The access control via postcomment() is rather strange
 * There is some common code cargo-culted from other plugins (notably inline and editpage) which
   should probably be shared

-* If the comments directive is removed from a page, comments can still be made on that page,
-  and will be committed but not displayed; to disable comments properly you have to set the
-  closed="yes" directive parameter (and refresh the wiki), *then* remove the directive if
-  desired

 
 > I haven't done a detailed code review, but I will say I'm pleased you
 > avoided re-implementing inline! --[[Joey]]
 
 > I haven't done a detailed code review, but I will say I'm pleased you
 > avoided re-implementing inline! --[[Joey]]

+
+Wishlist:
+
+* tbm would like anonymous people to be able to enter their name and possibly email
+  address
+* smcv would like an indication of who you're posting as / the ability to log in
+  as someone else (even if anonymous comments are allowed, it'd be nice to be
+  able to choose to log in with a username or OpenID, like in Livejournal);
+  perhaps editpage needs this too