Move some more discussion here
[ikiwiki.git] / doc / plugins / contrib / comments / discussion.mdwn
1 ## Why internal pages? (unresolved)
2
3 Comments are saved as internal pages, so they can never be edited through the CGI,
4 only by direct committers. Currently, comments are always in [[ikiwiki/markdown]].
5
6 > So, why do it this way, instead of using regular wiki pages in a
7 > namespace, such as `$page/comments/*`? Then you could use [[plugins/lockedit]] to
8 > limit editing of comments in more powerful ways. --[[Joey]]
9
10 >> Er... I suppose so. I'd assumed that these pages ought to only exist as inlines
11 >> rather than as individual pages (same reasoning as aggregated posts), though.
12 >>
13 >> lockedit is actually somewhat insufficient, since `check_canedit()`
14 >> doesn't distinguish between creation and editing; I'd have to continue to use
15 >> some sort of odd hack to allow creation but not editing.
16 >>
17 >> I also can't think of any circumstance where you'd want a user other than
18 >> admins (~= git committers) and possibly the commenter (who we can't check for
19 >> at the moment anyway, I don't think?) to be able to edit comments - I think
20 >> user expectations for something that looks like ordinary blog comments are
21 >> likely to include "others can't put words into my mouth".
22 >>
23 >> My other objection to using a namespace is that I'm not particularly happy about
24 >> plugins consuming arbitrary pieces of the wiki namespace - /discussion is bad
25 >> enough already. Indeed, this very page would accidentally get matched by rules
26 >> aiming to control comment-posting... :-) --[[smcv]]
27
28 >>> Thinking about it, perhaps one way to address this would be to have the suffix
29 >>> (e.g. whether commenting on Sandbox creates sandbox/comment1 or sandbox/c1 or
30 >>> what) be configurable by the wiki admin, in the same way that recentchanges has
31 >>> recentchangespage => 'recentchanges'? I'd like to see fewer hard-coded page
32 >>> names in general, really - it seems odd to me that shortcuts and smileys
33 >>> hard-code the name of the page to look at. Perhaps I could add
34 >>> discussionpage => 'discussion' too? --[[smcv]]
35
36 >>> (I've now implemented this in my branch. --[[smcv]])
37
38 >> The best reason to keep the pages internal seems to me to be that you
39 >> don't want the overhead of every comment spawning its own wiki page.
40 >> The worst problem with it though is that you have to assume the pages
41 >> are mdwn (or `default_pageext`) and not support other formats. --[[Joey]]
42
43 >>> Well, you could always have `comment1._mdwn`, `comment2._creole` etc. and
44 >>> alter the htmlize logic so that the `mdwn` hook is called for both `mdwn`
45 >>> and `_mdwn` (assuming this is not already the case). I'm not convinced
46 >>> that multi-format comments are a killer feature, though - part of the point
47 >>> of this plugin, in my mind, is that it's less flexible than the full power
48 >>> of ikiwiki and gives users fewer options. This could be construed
49 >>> to be a feature, for people who don't care how flexible the technology is
50 >>> and just want a simple way to leave a comment. The FormattingHelp page
51 >>> assumes you're writing 100% Markdown in any case...
52 >>>
53 >>> Internal pages do too many things, perhaps: they suppress generation of
54 >>> HTML pages, they disable editing over the web, and they have a different
55 >>> namespace of htmlize hooks. I think the first two of those are useful
56 >>> for this plugin, and the last is harmless; you seem to think the first
57 >>> is useful, and the other two are harmful. --[[smcv]]
58
59 ## Access control (unresolved?)
60
61 By the way, I think that who can post comments should be controllable by
62 the existing plugins opendiscussion, anonok, signinedit, and lockedit. Allowing
63 posting comments w/o any login, while a nice capability, can lead to
64 spam problems. So, use `check_canedit` as at least a first-level check?
65 --[[Joey]]
66
67 > This plugin already uses `check_canedit`, but that function doesn't have a concept
68 > of different actions. The hack I use is that when a user comments on, say, sandbox,
69 > I call `check_canedit` for the pseudo-page "sandbox[postcomment]". The
70 > special `postcomment(glob)` [[ikiwiki/pagespec]] returns true if the page ends with
71 > "[postcomment]" and the part before (e.g. sandbox) matches the glob. So, you can
72 > have postcomment(blog/*) or something. (Perhaps instead of taking a glob, postcomment
73 > should take a pagespec, so you can have postcomment(link(tags/commentable))?)
74 >
75 > This is why `anonok_pages => 'postcomment(*)'` and `locked_pages => '!postcomment(*)'`
76 > are necessary to allow anonymous and logged-in editing (respectively).
77 >
78 > This is ugly - one alternative would be to add `check_permission()` that takes a
79 > page and a verb (create, edit, rename, remove and maybe comment are the ones I
80 > can think of so far), use that, and port the plugins you mentioned to use that
81 > API too. This plugin could either call `check_can("$page/comment1", 'create')` or
82 > call `check_can($page, 'comment')`.
83
84 > One odd effect of the code structure I've used is that we check for the ability to
85 > create the page before we actually know what page name we're going to use - when
86 > posting the comment I just increment a number until I reach an unused one - so
87 > either the code needs restructuring, or the permission check for 'create' would
88 > always be for 'comment1' and never 'comment123'.
89
90 > Another possibility is to just check for permission to edit (e.g.) `sandbox/comment1`.
91 > However, this makes the "comments can only be created, not edited" feature completely
92 > reliant on the fact that internal pages can't be edited. Perhaps there should be a
93 > `editable_pages` pagespec, defaulting to `'*'`? --[[smcv]]
94
95 ## comments directive vs global setting (resolved?)
96
97 When comments have been enabled generally, you still need to mark which pages
98 can have comments, by including the `\[[!comments]]` directive in them. By default,
99 this directive expands to a "post a comment" link plus an `\[[!inline]]` with
100 the comments. [This requirement has now been removed --[[smcv]]]
101
102 > I don't like this, because it's hard to explain to someone why they have
103 > to insert this into every post to their blog. Seems that the model used
104 > for discussion pages could work -- if comments are enabled, automatically
105 > add the comment posting form and comments to the end of each page.
106 > --[[Joey]]
107
108 >> I don't think I'd want comments on *every* page (particularly, not the
109 >> front page). Perhaps a pagespec in the setup file, where the default is "*"?
110 >> Then control freaks like me could use "link(tags/comments)" and tag pages
111 >> as allowing comments.
112 >>
113 >>> Yes, I think a pagespec is the way to go. --[[Joey]]
114
115 >>>> Implemented --[[smcv]]
116
117 >> 
118 >> The model used for discussion pages does require patching the existing
119 >> page template, which I was trying to avoid - I'm not convinced that having
120 >> every possible feature hard-coded there really scales (and obviously it's
121 >> rather annoying while this plugin is on a branch). --[[smcv]]
122
123 >>> Using the template would allow customising the html around the comments
124 >>> which seems like a good thing? --[[Joey]]
125
126 >>>> The \[[!comments]] directive is already template-friendly - it expands to
127 >>>> the contents of the template `comments_embed.tmpl`, possibly with the
128 >>>> result of an \[[!inline]] appended. I should change `comments_embed.tmpl`
129 >>>> so it uses a template variable `INLINE` for the inline result rather than
130 >>>> having the perl code concatenate it, which would allow a bit more
131 >>>> customization (whether the "post" link was before or after the inline).
132 >>>> Even if you want comments in page.tmpl, keeping the separate comments_embed.tmpl
133 >>>> and having a `COMMENTS` variable in page.tmpl might be the way forward,
134 >>>> since the smaller each templates is, the easier it will be for users
135 >>>> to maintain a patched set of templates. (I think so, anyway, based on what happens
136 >>>> with dpkg prompts in Debian packages with monolithic vs split
137 >>>> conffiles.) --[[smcv]]
138
139 >>>>> I've switched my branch to use page.tmpl instead; see what you think? --[[smcv]]
140
141 ## Raw HTML (resolved?)
142
143 Raw HTML was not initially allowed by default (this was configurable).
144
145 > I'm not sure that raw html should be a problem, as long as the
146 > htmlsanitizer and htmlbalanced plugins are enabled. I can see filtering
147 > out directives, as a special case. --[[Joey]]
148
149 >> Right, if I sanitize each post individually, with htmlscrubber and either htmltidy
150 >> or htmlbalance turned on, then there should be no way the user can forge a comment;
151 >> I was initially wary of allowing meta directives, but I think those are OK, as long
152 >> as the comment template puts the \[[!meta author]] at the *end*. Disallowing
153 >> directives is more a way to avoid commenters causing expensive processing than
154 >> anything else, at this point.
155 >>
156 >> I've rebased the plugin on master, made it sanitize individual posts' content
157 >> and removed the option to disallow raw HTML. Sanitizing individual posts before
158 >> they've been htmlized required me to preserve whitespace in the htmlbalance
159 >> plugin, so I did that. Alternatively, we could htmlize immediately and always
160 >> save out raw HTML? --[[smcv]]
161
162 >>> There might be some use cases for other directives, such as img, in
163 >>> comments.
164 >>> 
165 >>> I don't know if meta is "safe" (ie, guaranteed to be inexpensive and not
166 >>> allow users to do annoying things) or if it will continue to be in the
167 >>> future. Hard to predict really, all that can be said with certainty is
168 >>> all directives will contine to be inexpensive and safe enough that it's
169 >>> sensible to allow users to (ab)use them on open wikis.
170 >>> --[[Joey]]