diff options
Diffstat (limited to 'doc/plugins/contrib')
| -rw-r--r-- | doc/plugins/contrib/comments.mdwn | 91 | ||||
| -rw-r--r-- | doc/plugins/contrib/comments/discussion.mdwn | 160 |
2 files changed, 0 insertions, 251 deletions
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/contrib/comments/discussion.mdwn b/doc/plugins/contrib/comments/discussion.mdwn deleted file mode 100644 index 59740ec37..000000000 --- a/doc/plugins/contrib/comments/discussion.mdwn +++ /dev/null @@ -1,160 +0,0 @@ -## Why internal pages? (unresolved) - -Comments are saved as internal pages, so they can never be edited through the CGI, -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 -> 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]] - ->>> Thinking about it, perhaps one way to address this would be to have the suffix ->>> (e.g. whether commenting on Sandbox creates sandbox/comment1 or sandbox/c1 or ->>> what) be configurable by the wiki admin, in the same way that recentchanges has ->>> recentchangespage => 'recentchanges'? I'd like to see fewer hard-coded page ->>> names in general, really - it seems odd to me that shortcuts and smileys ->>> hard-code the name of the page to look at. Perhaps I could add ->>> discussionpage => 'discussion' too? --[[smcv]] - ->>> (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. --[[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 -posting comments w/o any login, while a nice capability, can lead to -spam problems. So, use `check_canedit` as at least a first-level check? ---[[Joey]] - -> This plugin already uses `check_canedit`, but that function doesn't have a concept -> of different actions. The hack I use is that when a user comments on, say, sandbox, -> I call `check_canedit` for the pseudo-page "sandbox[postcomment]". The -> special `postcomment(glob)` [[ikiwiki/pagespec]] returns true if the page ends with -> "[postcomment]" and the part before (e.g. sandbox) matches the glob. So, you can -> have postcomment(blog/*) or something. (Perhaps instead of taking a glob, postcomment -> should take a pagespec, so you can have postcomment(link(tags/commentable))?) -> -> This is why `anonok_pages => 'postcomment(*)'` and `locked_pages => '!postcomment(*)'` -> are necessary to allow anonymous and logged-in editing (respectively). -> -> This is ugly - one alternative would be to add `check_permission()` that takes a -> page and a verb (create, edit, rename, remove and maybe comment are the ones I -> can think of so far), use that, and port the plugins you mentioned to use that -> API too. This plugin could either call `check_can("$page/comment1", 'create')` or -> call `check_can($page, 'comment')`. -> -> One odd effect of the code structure I've used is that we check for the ability to -> 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'. --[[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]] - -## 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, -this directive expands to a "post a comment" link plus an `\[[!inline]]` with -the comments. [This requirement has now been removed --[[smcv]]] - -> 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. ->> ->>> Yes, I think a pagespec is the way to go. --[[Joey]] - ->>>> Implemented --[[smcv]] - ->> ->> 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]] - ->>> Using the template would allow customising the html around the comments ->>> which seems like a good thing? --[[Joey]] - ->>>> The \[[!comments]] directive is already template-friendly - it expands to ->>>> the contents of the template `comments_embed.tmpl`, possibly with the ->>>> result of an \[[!inline]] appended. I should change `comments_embed.tmpl` ->>>> so it uses a template variable `INLINE` for the inline result rather than ->>>> having the perl code concatenate it, which would allow a bit more ->>>> customization (whether the "post" link was before or after the inline). ->>>> Even if you want comments in page.tmpl, keeping the separate comments_embed.tmpl ->>>> and having a `COMMENTS` variable in page.tmpl might be the way forward, ->>>> since the smaller each templates is, the easier it will be for users ->>>> to maintain a patched set of templates. (I think so, anyway, based on what happens ->>>> with dpkg prompts in Debian packages with monolithic vs split ->>>> 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]] |