multiple formats now supported

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

diff --git a/doc/plugins/contrib/comments/discussion.mdwn b/doc/plugins/contrib/comments/discussion.mdwn
index 8f98c1cb5cd107fb149a89764b7ab049845dbeed..59740ec37b03860a17866ef22653ccc9a1a709cd 100644 (file)
--- a/doc/plugins/contrib/comments/discussion.mdwn
+++ b/doc/plugins/contrib/comments/discussion.mdwn
@@ -1,7 +1,7 @@
-# Why internal pages? (unresolved)
+## Why internal pages? (unresolved)

 
 Comments are saved as internal pages, so they can never be edited through the CGI,
 
 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]].
+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
 
 > 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


@@ -36,27 +36,15 @@ only by direct committers. Currently, comments are always in [[ikiwiki/markdown]
 >>> (I've now implemented this in my branch. --[[smcv]])
 
 >> The best reason to keep the pages internal seems to me to be that you
 >>> (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.
->> The worst problem with it though is that you have to assume the pages
->> are mdwn (or `default_pageext`) and not support other formats. --[[Joey]]
-
->>> Well, you could always have `comment1._mdwn`, `comment2._creole` etc. and
->>> alter the htmlize logic so that the `mdwn` hook is called for both `mdwn`
->>> and `_mdwn` (assuming this is not already the case). I'm not convinced
->>> that multi-format comments are a killer feature, though - part of the point
->>> of this plugin, in my mind, is that it's less flexible than the full power
->>> of ikiwiki and gives users fewer options. This could be construed
->>> to be a feature, for people who don't care how flexible the technology is
->>> and just want a simple way to leave a comment. The FormattingHelp page
->>> assumes you're writing 100% Markdown in any case...
->>>
->>> Internal pages do too many things, perhaps: they suppress generation of
->>> HTML pages, they disable editing over the web, and they have a different
->>> namespace of htmlize hooks. I think the first two of those are useful
->>> for this plugin, and the last is harmless; you seem to think the first
->>> is useful, and the other two are harmful. --[[smcv]]
-
-# Access control (unresolved?)
+>> 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
 
 By the way, I think that who can post comments should be controllable by
 the existing plugins opendiscussion, anonok, signinedit, and lockedit. Allowing


@@ -85,14 +73,16 @@ spam problems. So, use `check_canedit` as at least a first-level check?
 > 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
 > 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'.
+> 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]]
 
 
 > 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?)
+## 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,
 
 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,


@@ -137,3 +127,34 @@ the comments. [This requirement has now been removed --[[smcv]]]
 >>>> conffiles.) --[[smcv]]
 
 >>>>> I've switched my branch to use page.tmpl instead; see what you think? --[[smcv]]
 >>>> 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]]