diff options
Diffstat (limited to 'doc/plugins')
62 files changed, 1166 insertions, 128 deletions
diff --git a/doc/plugins/404.mdwn b/doc/plugins/404.mdwn new file mode 100644 index 000000000..ad332ee04 --- /dev/null +++ b/doc/plugins/404.mdwn @@ -0,0 +1,20 @@ +[[!template id=plugin name=404 author="[[Simon_McVittie|smcv]]"]] +[[!tag type/useful]] + +This plugin lets you use the IkiWiki CGI script as an Apache 404 handler, +to give the behaviour of various other wiki engines where visiting a +nonexistent page provides you with a link to create it. + +To achieve this, put something like this in the wiki's Apache configuration +file: + + ErrorDocument 404 /ikiwiki.cgi + +(The path here needs to be whatever the path is to the ikiwiki.cgi from +the root of your web server.) + +Or put something like this in the wiki's Lighttpd (>=1.4.17) configuration file: + + server.error-handler-404 = "/ikiwiki.cgi" + + diff --git a/doc/plugins/aggregate.mdwn b/doc/plugins/aggregate.mdwn index c40a6dc22..e2efcd83f 100644 --- a/doc/plugins/aggregate.mdwn +++ b/doc/plugins/aggregate.mdwn @@ -5,13 +5,9 @@ This plugin allows content from other feeds to be aggregated into the wiki. To specify feeds to aggregate, use the [[ikiwiki/directive/aggregate]] [[ikiwiki/directive]]. -New users of aggregate should enable the `aggregateinternal => 1` option in the -.setup file. If you don't do so, you will need to enable the [[html]] plugin -as well as aggregate itself, since feed entries will be stored as HTML. - -The [[meta]] and [[tag]] plugins are also recommended. The -[[htmltidy]] plugin is suggested, since feeds can easily contain html -problems, some of which tidy can fix. +The [[meta]] and [[tag]] plugins are also recommended. Either the +[[htmltidy]] or [[htmlbalance]] plugin is suggested, since feeds can easily +contain html problems, some of which these plugins can fix. You will need to run ikiwiki periodically from a cron job, passing it the --aggregate parameter, to make it check for new posts. Here's an example @@ -27,37 +23,19 @@ visit is `http://whatever/ikiwiki.cgi?do=aggregate_webtrigger`. Anyone can visit the url to trigger an aggregation run, but it will only check each feed if its `updateinterval` has passed. -## internal pages and `aggregateinternal` +## aggregated pages This plugin creates a page for each aggregated item. If the `aggregateinternal` option is enabled in the setup file (which is -recommended), aggregated pages are stored in the source directory with a +the default), aggregated pages are stored in the source directory with a "._aggregated" extension. These pages cannot be edited by web users, and do not generate first-class wiki pages. They can still be inlined into a blog, but you have to use `internal` in [[PageSpecs|IkiWiki/PageSpec]], like `internal(blog/*)`. -For backward compatibility, the default is that these pages have the -".html" extension, and are first-class wiki pages -- each one generates -a separate HTML page in the output, and they can even be edited. - -That turns out to not be ideal for aggregated content, because publishing -files for each of those pages is a waste of disk space and CPU, and you -probably don't want to allow them to be edited. So, there is an alternative -method that can be used (and is recommended), turned on by the -`aggregateinternal` option in the setup file. - -If you are already using aggregate and want to enable `aggregateinternal`, -you should follow this process: - -1. Update all [[PageSpecs|ikiwiki/PageSpec]] that refer to the aggregated - pages -- such as those in inlines. Put "internal()" around globs - in those PageSpecs. For example, if the PageSpec was `foo/*`, it should - be changed to `internal(foo/*)`. This has to be done because internal - pages are not matched by regular globs. -2. Turn on `aggregateinternal` in the setup file. -3. Use [[ikiwiki-transition]] to rename all existing aggregated `.html` - files in the srcdir. The command to run is - `ikiwiki-transition aggregateinternal $setupfile`, -4. Refresh the wiki. (`ikiwiki -setup your.setup -refresh`) +If `aggregateinternal` is disabled, you will need to enable the [[html]] +plugin as well as aggregate itself, since feed entries will be stored as +HTML, and as first-class wiki pages -- each one generates +a separate HTML page in the output, and they can even be edited. This +option is provided only for backwards compatability. diff --git a/doc/plugins/aggregate/discussion.mdwn b/doc/plugins/aggregate/discussion.mdwn index 1db6240d5..1a9844577 100644 --- a/doc/plugins/aggregate/discussion.mdwn +++ b/doc/plugins/aggregate/discussion.mdwn @@ -35,7 +35,7 @@ Two things aren't working as I'd expect: > problem. You can see the feed validator complain about it here: > <http://feedvalidator.org/check.cgi?url=http%3A%2F%2Fwww.davidj.org%2Frss.xml> > -> It's sorta unfortunate that [[cpan XML::Feed]] doesn't just assume the +> It's sorta unfortunate that [[!cpan XML::Feed]] doesn't just assume the > un-esxaped html is part of the description field. Probably other feed > parsers are more lenient. --[[Joey]] diff --git a/doc/plugins/anonok.mdwn b/doc/plugins/anonok.mdwn index 2a8a922cd..a3fec4d89 100644 --- a/doc/plugins/anonok.mdwn +++ b/doc/plugins/anonok.mdwn @@ -7,3 +7,8 @@ by default. The plugin also has a configuration setting, `anonok_pagespec`. This [[PageSpec]] can be used to allow anonymous editing of matching pages. + +If you're using the [[comments]] plugin, you can allow anonymous comments +to be posted by setting: + + anonok_pagespec => "postcomment(*)" diff --git a/doc/plugins/autoindex/discussion.mdwn b/doc/plugins/autoindex/discussion.mdwn new file mode 100644 index 000000000..82e30aab1 --- /dev/null +++ b/doc/plugins/autoindex/discussion.mdwn @@ -0,0 +1,7 @@ +Would it be possible to add an option to only generate the index files +for the html output and not place the markdown files in the wiki source? + +The reason being that I have a lot of directories which need to be autoindexed, +but I would prefer if the index files didn't clutter up my git repository. + +even without that feature the plugin is a great help, thanks diff --git a/doc/plugins/blogspam.mdwn b/doc/plugins/blogspam.mdwn new file mode 100644 index 000000000..1d152faac --- /dev/null +++ b/doc/plugins/blogspam.mdwn @@ -0,0 +1,26 @@ +[[!template id=plugin name=blogspam author="[[Joey]]"]] +[[!tag type/auth]] + +This plugin adds antispam support to ikiwiki, using the +[blogspam.net](http://blogspam.net/) API. Both page edits and +[[comment|comments]] postings can be checked for spam. Page edits that +appear to contain spam will be rejected; comments that look spammy will be +stored in a queue for moderation by an admin. + +The plugin requires the [[!cpan RPC::XML]] perl module. + +You can control how content is tested via the `blogspam_options` setting. +The list of options is [here](http://blogspam.net/api/testComment.html#options). +By default, the options are configured in a way that is appropriate for +wiki content. This includes turning off some of the more problimatic tests. + +The `blogspam_pagespec` setting is a [[ikiwiki/PageSpec]] that can be +used to configure which pages are checked for spam. The default is to check +all edits. If you only want to check [[comments]] (not wiki page edits), +set it to "postcomment(*)". + +By default, the blogspam.net server is used to do the spam checking. To +change this, the `blogspam_server` option can be set to the url for a +different server implementing the same API. Note that content is sent +unencrypted over the internet to the server, and the server sees +the full text of the content. diff --git a/doc/plugins/calendar.mdwn b/doc/plugins/calendar.mdwn index c9e95ce7e..d695762b7 100644 --- a/doc/plugins/calendar.mdwn +++ b/doc/plugins/calendar.mdwn @@ -6,7 +6,7 @@ The directive displays a calendar, similar to the typical calendars shown on some blogs. Since ikiwiki is a wiki compiler, to keep the calendar up-to-date, -wikis that include it need to be preiodically refreshes, typically by cron +wikis that include it need to be periodically refreshes, typically by cron at midnight. Example crontab: 0 0 * * * ikiwiki -setup ~/ikiwiki.setup -refresh diff --git a/doc/plugins/calendar/discussion.mdwn b/doc/plugins/calendar/discussion.mdwn index 65c2459c6..9d57b7a1e 100644 --- a/doc/plugins/calendar/discussion.mdwn +++ b/doc/plugins/calendar/discussion.mdwn @@ -1,2 +1,6 @@ It would be nice if the "month" type calendar could collect all of the matching pages on a given date in some inline type way. --[[DavidBremner]] + +Is it possible to get the calendar to link to pages based not on their timestamp (as I understand that it does now, or have I misunderstood this?) and instead on for example their location in a directory hierarchy. That way the calendar could be used as a planning / timeline device which I think would be great. --[[Alexander]] + +I would like the ability to specify relative previous months. This way I could have a sidebar with the last three months by specifying no month, then 'month="-1"' and 'month="-2"'. Negative numbers for the month would otherwise be invalid, so this shouldn't produce any conflicts with expected behavior. (Right?) -- [[StevenBlack]] diff --git a/doc/plugins/comments.mdwn b/doc/plugins/comments.mdwn new file mode 100644 index 000000000..c13a6daa6 --- /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]]. + +There are some global options for the setup file: + +* `comments_pagespec`: [[ikiwiki/PageSpec]] of pages where comments are + allowed. The default is not to allow comments on any pages. To allow + comments to all posts to a blog, you could use + `blog/posts/* and !*/Discussion`. +* `comments_closed_pagespec`: [[ikiwiki/PageSpec]] of pages where + posting of new comments is closed, but any existing comments will still + be displayed. Often you will list a set of individual pages here. + For example: `blog/controversial or blog/flamewar` +* `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 + +## comment moderation + +If you enable the [[blogspam]] plugin, comments that appear spammy will be +held for moderation. Wiki admins can access the comment moderation queue +via a button on their Preferences page. + +The comments are stored in `.ikiwiki/comments_pending/`, and can be +deleted, or moved into the wiki's srcdir to be posted. diff --git a/doc/plugins/comments/discussion.mdwn b/doc/plugins/comments/discussion.mdwn new file mode 100644 index 000000000..3d7452b9a --- /dev/null +++ b/doc/plugins/comments/discussion.mdwn @@ -0,0 +1,163 @@ +## 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_pagespec => 'postcomment(*)'` and `locked_pages => '!postcomment(*)'` +> are necessary to allow anonymous and logged-in editing (respectively). +> +>> I changed that to move the flag out of the page name, and into a variable that the `match_postcomment` +>> function checks for. Other ugliness still applies. :-) --[[Joey]] +> +> 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]] diff --git a/doc/plugins/contrib.mdwn b/doc/plugins/contrib.mdwn index 7a28edaba..e22b13f71 100644 --- a/doc/plugins/contrib.mdwn +++ b/doc/plugins/contrib.mdwn @@ -2,6 +2,6 @@ Contributed [[plugins]]: (See [[install]] for installation help.) -[[!inline pages="plugins/contrib/* !*/Discussion" +[[!inline pages="plugins/contrib/* and !*/Discussion" feedpages="created_after(plugins/contrib/navbar)" archive="yes" rootpage="plugins/contrib" postformtext="Add a new plugin named:" show=0]] diff --git a/doc/plugins/contrib/default_content_for___42__copyright__42___and___42__license__42__.mdwn b/doc/plugins/contrib/default_content_for___42__copyright__42___and___42__license__42__.mdwn index b4a7cd5d6..adb414ffb 100644 --- a/doc/plugins/contrib/default_content_for___42__copyright__42___and___42__license__42__.mdwn +++ b/doc/plugins/contrib/default_content_for___42__copyright__42___and___42__license__42__.mdwn @@ -20,14 +20,14 @@ template variable somebody wants to use. --[[bma]] Copyright and license values are not "template values", they are values -tracked by the meta plugin, and that various code compares and uses to fill +tracked by the [[meta]] plugin, and that various code compares and uses to fill out the templates. Something like varioki cannot do that. --[[Joey]] Somewhat more detailed usage documentation would be appreciated. I tried to setup those plugins with a current ikiwiki release, i.e. 2.61, but they appeared to do nothing, really. Also, those example pages don't seem to use those plugins, even; they set "copyright" and "license" properties using ordinary [[meta]] tags. Maybe -I'm missing something terribly obvious? --[[Peter]] +I'm missing something terribly obvious? --Peter > Only obvious if you read the source :-). You need to put a file named "copyright.html" >(respectively "license.html") in your wiki. Everything underneath that (in the wikilink sense) will use that >content for the license or copyright. Saves putting \[[meta license="foo"]] in every page [[DavidBremner]] diff --git a/doc/plugins/contrib/gallery.mdwn b/doc/plugins/contrib/gallery.mdwn index 7148de3ef..72df13bd0 100644 --- a/doc/plugins/contrib/gallery.mdwn +++ b/doc/plugins/contrib/gallery.mdwn @@ -2,7 +2,7 @@ This plugin would create a nice looking gallery of the images. It has been build over the img plugin in Ikiwiki -SVN repository of plugin is located at <http://ned.snow-crash.org:8080/svn/ikiwiki-gallery> +GIT repo of the plugin is located at <http://github.com/joeyh/ikiwiki/tree/gallery> USAGE : diff --git a/doc/plugins/contrib/headinganchors.mdwn b/doc/plugins/contrib/headinganchors.mdwn index ef2fa122a..c80cc0b49 100644 --- a/doc/plugins/contrib/headinganchors.mdwn +++ b/doc/plugins/contrib/headinganchors.mdwn @@ -12,9 +12,9 @@ rst and any other format that produces html. The code is available here: use strict; use IkiWiki 2.00; - sub import { #{{{ + sub import { hook(type => "sanitize", id => "headinganchors", call => \&headinganchors); - } # }}} + } sub text_to_anchor { my $str = shift; @@ -26,11 +26,11 @@ rst and any other format that produces html. The code is available here: return $str; } - sub headinganchors (@) { #{{{ + sub headinganchors (@) { my %params=@_; my $content=$params{content}; $content=~s{<h([0-9])>([^>]*)</h([0-9])>}{'<h'.$1.' id="'.text_to_anchor($2).'">'.$2.'</h'.$3.'>'}gie; return $content; - } # }}} + } 1 diff --git a/doc/plugins/contrib/highlightcode.mdwn b/doc/plugins/contrib/highlightcode.mdwn index 9b43a106c..8abb76583 100644 --- a/doc/plugins/contrib/highlightcode.mdwn +++ b/doc/plugins/contrib/highlightcode.mdwn @@ -1,3 +1,6 @@ +[[!template id=plugin name=highlightcode author="[[sabr]]"]] +[[!tag type/format]] + A small plugin to allow Ikiwiki to display source files complete with syntax highlighting. Files with recognized extensions (i.e. my-file.cpp) are be rendered just like any other Ikiwiki page. You can even edit your source files with Ikiwiki's editor. It uses the Syntax::Highlight::Engine::Kate Perl module to do the highlighting. diff --git a/doc/plugins/contrib/linguas.mdwn b/doc/plugins/contrib/linguas.mdwn index 0c3366846..bf502606e 100644 --- a/doc/plugins/contrib/linguas.mdwn +++ b/doc/plugins/contrib/linguas.mdwn @@ -10,7 +10,8 @@ Download: [linguas.pm](http://ettin.org/pub/ikiwiki/linguas.pm) (2006-08-21). Note that even though it is still available for download, this plugin is no longer actively maintained. If you are interested in multilingual wiki pages, you -can also take a look at other approaches such as [[todo/l10n]] or Lars Wirzenius's +can also take a look at other approaches such as [[todo/l10n]], [[plugins/contrib/po]], +or Lars Wirzenius's [Static website, with translations, using IkiWiki](http://liw.iki.fi/liw/log/2007-05.html#20070528b). Usage diff --git a/doc/plugins/contrib/mediawiki.mdwn b/doc/plugins/contrib/mediawiki.mdwn new file mode 100644 index 000000000..c0a23254f --- /dev/null +++ b/doc/plugins/contrib/mediawiki.mdwn @@ -0,0 +1,5 @@ +[[!template id=plugin name=mediawiki author="[[sabr]]"]] +[[!tag type/format]] + +[The Mediawiki plugin](http://u32.net/Mediawiki_Plugin/) allows ikiwiki to +process pages written using MediaWiki markup. diff --git a/doc/plugins/contrib/opml.mdwn b/doc/plugins/contrib/opml.mdwn new file mode 100644 index 000000000..3f98e8065 --- /dev/null +++ b/doc/plugins/contrib/opml.mdwn @@ -0,0 +1,11 @@ +[[!template id=plugin name=opml author="[[JanWalzer|jwalzer]]"]] +[[!tag type/format]] + +The idea of this plugin is to parse in an OPML-File and output a linklist, maybe some customization. +OPML-Files are xml-files that most RSS-Readers write out, to summarize their subscribes feedlist. + +I have a "dumb" perlscript running on my website, that tries to do a opml2mdwn transformation, but its quite bad on that. + +This Plugin is **NOT Ready** in any way. I'm just putting this page up as a hook, to discuss it. + +I intend to work on this, but I'd appreciate any help on this. diff --git a/doc/plugins/contrib/opml/discussion.mdwn b/doc/plugins/contrib/opml/discussion.mdwn new file mode 100644 index 000000000..3a145c79a --- /dev/null +++ b/doc/plugins/contrib/opml/discussion.mdwn @@ -0,0 +1,4 @@ +If this is the wrong place for the development of the plugin, please mode it on to a more appropriate one. + +Currently I'm quite stuck with the perl-stuff itself. I'm trying to become comfortable with the language, but it seems, the language doesn't like me. I'm lost in complex datastructures, when trying to iterate through the output of XML::Simple. --[[Jan|jwalzer]] + diff --git a/doc/plugins/contrib/po.mdwn b/doc/plugins/contrib/po.mdwn new file mode 100644 index 000000000..61ec53ea8 --- /dev/null +++ b/doc/plugins/contrib/po.mdwn @@ -0,0 +1,386 @@ +I've been working on a plugin called "po", that adds support for multi-lingual wikis, +translated with gettext, using [po4a](http://po4a.alioth.debian.org/). + +More information: + +* It can be found in my "po" branch: + `git clone git://gaffer.ptitcanardnoir.org/ikiwiki.git` +* It is self-contained, *i.e.* it does not modify ikiwiki core at all. +* It is documented (including TODO and plans for next work steps) in + `doc/plugins/po.mdwn`, which can be found in the same branch. +* No public demo site is available so far, I'm working on this. + +My plan is to get this plugin clean enough to be included in ikiwiki. + +The current version is a proof-of-concept, mature enough for me to dare submitting it here, +but I'm prepared to hear various helpful remarks, and to rewrite parts of it as needed. + +Any thoughts on this? + +> Well, I think it's pretty stunning what you've done here. Seems very +> complete and well thought out. I have not read the code in great detail +> yet. +> +> Just using po files is an approach I've never seen tried with a wiki. I +> suspect it will work better for some wikis than others. For wikis that +> just want translations that match the master language as closely as +> possible and don't wander off and diverge, it seems perfect. (But what happens +> if someone edits the Discussion page of a translated page?) +> +> Please keep me posted, when you get closer to having all issues solved +> and ready for merging I can do a review and hopefully help with the +> security items you listed. --[[Joey]] + +>> Thanks a lot for your quick review, it's reassuring to hear such nice words +>> from you. I did not want to design and write a full translation system, when +>> tools such as gettext/po4a already have all the needed functionality, for cases +>> where the master/slave languages paradigm fits. +>> Integrating these tools into ikiwiki plugin system was a pleasure. +>> +>> I'll tell you when I'm ready for merging, but in the meantime, +>> I'd like you to review the changes I did to the core (3 added hooks). +>> Can you please do this? If not, I'll go on and hope I'm not going to far in +>> the wrong direction. +>> +>>> Sure.. I'm not completly happy with any of the hooks since they're very +>>> special purpose, and also since `run_hooks` is not the best interface +>>> for a hook that modifies a variable, where only the last hook run will +>>> actually do anything. It might be better to just wrap +>>> `targetpage`, `bestlink`, and `beautify_urlpath`. But, I noticed +>>> the other day that such wrappers around exported functions are only visible by +>>> plugins loaded after the plugin that defines them. +>>> +>>> Update: Take a look at the new "Function overriding" section of +>>> [[plugins/write]]. I think you can just inject wrappers about a few ikiwiki +>>> functions, rather than adding hooks. The `inject` function is pretty +>>> insane^Wlow level, but seems to work great. --[[Joey]] +>>> +>>>> Thanks a lot, it seems to be a nice interface for what I was trying to achieve. +>>>> I may be forced to wait two long weeks before I have a chance to confirm +>>>> this. Stay tuned. --[[intrigeri]] +>>>> +>>>>> I've updated the plugin to use `inject`. It is now fully self-contained, +>>>>> and does not modify the core anymore. --[[intrigeri]] +>> +>> The Discussion pages issue is something I am not sure about yet. But I will +>> probably decide that "slave" pages, being only translations, don't deserve +>> a discussion page: the discussion should happen in the language in which the +>> pages are written for real, which is the "master" one. --[[intrigeri]] +>> +>> I think that's a good decision, you don't want to translate discussion, +>> and if the discussion page turns out multilingual, well, se la vi. ;-) +>> +>> Relatedly, what happens if a translated page has a broken link, and you +>> click on it to edit it? Seems you'd first have to create a master page +>> and could only then translate it, right? I wonder if this will be clear +>> though to the user. +>> +>>> Right: a broken link points to the URL that allows to create +>>> a page that can either be a new master page or a non-translatable +>>> page, depending on `po_translatable_pages` value. The best +>>> solution I can thing of is to use [[plugins/edittemplate]] to +>>> insert something like "Warning: this is a master page, that must +>>> be written in $MASTER_LANGUAGE" into newly created master pages, +>>> and maybe another warning message on newly created +>>> non-translatable pages. It seems quite doable to me, but in order +>>> to avoid breaking existing functionality, it implies to hack a bit +>>> [[plugins/edittemplate]] so that multiple templates can be +>>> inserted at page creation time. [[--intrigeri]] +>>> +>>>> I implemented such a warning using the formbuilder_setup hook. +>>>> --[[intrigeri]] +>> +>> And also, is there any way to start a translation of a page into a new +>> lanauge using the web interface? +>> +>>> When a new language is added to `po_slave_languages`, a rebuild is +>>> triggered, and all missing PO files are created and checked into +>>> VCS. An unpriviledged wiki user can not add a new language to +>>> `po_slave_languages`, though. One could think of adding the needed +>>> interface to translate a page into a yet-unsupported slave +>>> language, and this would automagically add this new language to +>>> `po_slave_languages`. It would probably be useful in some +>>> usecases, but I'm not comfortable with letting unpriviledged wiki +>>> users change the wiki configuration as a side effect of their +>>> actions; if this were to be implemented, special care would be +>>> needed. [[--intrigeri]] +>>> +>>>> Actually I meant into any of the currently supported languages. +>>>> I guess that if the template modification is made, it will list those +>>>> languages on the page, and if a translation to a language is missing, +>>>> the link will allow creating it? +>>>> +>>>>> Any translation page always exist for every supported slave +>>>>> language, even if no string at all have been translated yet. +>>>>> This implies the po plugin is especially friendly to people who +>>>>> prefer reading in their native language if available, but don't +>>>>> mind reading in English else. +>>>>> +>>>>> While I'm at it, there is a remaining issue that needs to be +>>>>> sorted out: how painful it could be for non-English speakers +>>>>> (assuming the master language is English) to be perfectly able +>>>>> to navigate between translation pages supposed to be written in +>>>>> their own language, when their translation level is most +>>>>> often low. +>>>>> +>>>>> (It is currently easy to display this status on the translation +>>>>> page itself, but then it's too late, and how frustrating to load +>>>>> a page just to realize it's actually not translated enough for +>>>>> you. The "other languages" loop also allows displaying this +>>>>> information, but it is generally not the primary +>>>>> navigation tool.) +>>>>> +>>>>> IMHO, this is actually a social problem (i.e. it's no use adding +>>>>> a language to the supported slave ones if you don't have the +>>>>> manpower to actually do the translations), that can't be fully +>>>>> solved by technical solutions, but I can think of some hacks +>>>>> that would limit the negative impact: a given translation's +>>>>> status (currently = percent translated) could be displayed next +>>>>> to the link that leads to it; a color code could as well be used +>>>>> ("just" a matter of adding a CSS id or class to the links, +>>>>> depending on this variable). As there is already work to be done +>>>>> to have the links text generation more customizable through +>>>>> plugins, I could do both at the same time if we consider this +>>>>> matter to be important enough. --[[intrigeri]] +>>>>> +>>>>>> The translation status in links is now implemented in my +>>>>>> `po`branch. It requires my `meta` branch changes to +>>>>>> work, though. I consider the latter to be mature enough to +>>>>>> be merged. --[[intrigeri]] + +>> FWIW, I'm tracking your po branch in ikiwiki master git in the po +>> branch. One thing I'd like to try in there is setting up a translated +>> basewiki, which seems like it should be pretty easy to do, and would be +>> a great demo! --[[Joey]] +>> +>>> I've merged your changes into my own branch, and made great +>>> progress on the various todo items. Please note my repository +>>> location has changed a few days ago, my user page was updated +>>> accordingly, but I forgot to update this page at the same time. +>>> Hoping it's not too complicated to relocated an existing remote... +>>> (never done that, I'm a Git beginner as well as a Perl +>>> newbie) --[[intrigeri]] +>>>> +>>>> Just a matter of editing .git/config, thanks for the heads up. +>>>>> +>>>>> Joey, please have a look at my branch, your help would be really +>>>>> welcome for the security research, as I'm almost done with what +>>>>> I am able to do myself in this area. --[[intrigeri]] +>>>>>> +>>>>>> I came up with a patch for the WrapI18N issue --[[Joey]] + +I've set this plugin development aside for a while. I will be back and +finish it at some point in the first quarter of 2009. --[[intrigeri]] + +> Abstract: Joey, please have a look at my po and meta branches. +> +> Detailed progress report: +> +> * it seems the po branch in your repository has not been tracking my +> own po branch for two months. any config issue? +> * all the plugin's todo items have been completed, robustness tests +> done +> * I've finished the detailed security audit, and the fix for po4a +> bugs has entered upstream CVS last week +> * I've merged your new `checkcontent` hook with the `cansave` hook +> I previously introduced in my own branch; blogspam plugin updated +> accordingly +> * the rename hook changes we discussed elsewhere are also part of my +> branch +> * I've introduced two new hooks (`canremove` and `canrename`), not +> a big deal; IMHO, they extend quite logically the plugin interface +> * as highlighted on [[bugs/pagetitle_function_does_not_respect_meta_titles]], +> my `meta` branch contains a new feature that is really useful in a +> translatable wiki +> +> As a conclusion, I'm feeling that my branches are ready to be +> merged; only thing missing, I guess, are a bit of discussion and +> subsequent adjustments. +> +> --[[intrigeri]] + +> I've looked it over and updated my branch with some (untested) +> changes. +> +>> I've merged your changes into my branch. Only one was buggy. +> +> Sorry, I'd forgotten about your cansave hook.. sorry for the duplicate +> work there. +> +> Reviewing the changes, mostly outside of `po.pm`, I have +> the following issues. +> +> * renamepage to renamelink change would break the ikiwiki +> 3.x API, which I've promised not to do, so needs to be avoided +> somehow. (Sorry, I guess I dropped the ball on not getting this +> API change in before cutting 3.0..) +>> +>> Fixed, see [[todo/need_global_renamepage_hook]]. +>> +> * I don't understand the parentlinks code change and need to figure it +> out. Can you explain what is going on there? +>> +>> I'm calling `bestlink` there so that po's injected `bestlink` is +>> run. This way, the parent links of a page link to the parent page +>> version in the proper language, depending on the +>> `po_link_to=current` and `po_link_to=negotiated` settings. +>> Moreover, when using my meta branch enhancements plus meta title to +>> make pages titles translatable, this small patch is needed to get +>> the translated titles into parentlinks. +>> +> * canrename's mix of positional and named parameters is way too +> ugly to get into an ikiwiki API. Use named parameters +> entirely. Also probably should just use named parameters +> for canremove. +> * `skeleton.pm.example`'s canrename needs fixing to use either +> the current or my suggested parameters. +>> +>> Done. +>> +> * I don't like the exporting of `%backlinks` and `$backlinks_calculated` +> (the latter is exported but not used). +>> +>> The commit message for 85f865b5d98e0122934d11e3f3eb6703e4f4c620 +>> contains the rationale for this change. I guess I don't understand +>> the subtleties of `our` use, and perldoc does not help me a lot. +>> IIRC, I actually did not use `our` to "export" these variables, but +>> rather to have them shared between `Render.pm` uses. +>> +>>> My wording was unclear, I meant exposing. --[[Joey]] +>>> +>>>> I guess I still don't know Perl's `our` enough to understand clearly. +>>>> No matter whether these variables are declared with `my` or `our`, +>>>> any plugin can `use IkiWiki::Render` and then access +>>>> `$IkiWiki::backlinks`, as already does e.g. the pagestat plugin. +>>>> So I guess your problem is not with letting plugins use these +>>>> variables, but with them being visible for every piece of +>>>> (possibly external) code called from `Render.pm`. Am I right? +>>>> If I understand clearly, using a brace block to lexically enclose +>>>> these two `our` declarations, alongside with the `calculate_backlinks` +>>>> and `backlinks` subs definitions, would be a proper solution, wouldn't +>>>> it? --[[intrigeri]] +>>>> +>>>>> No, %backlinks and the backlinks() function are not the same thing. +>>>>> The variable is lexically scoped; only accessible from inside +>>>>> `Render.pm` --[[Joey]] +>>>> +> * What is this `IkiWiki::nicepagetitle` and why are you +> injecting it into that namespace when only your module uses it? +> Actually, I can't even find a caller of it in your module. +>> +>> I guess you should have a look to my `meta` branch and to +>> [[bugs/pagetitle_function_does_not_respect_meta_titles]] in order +>> to understand this :) +>> +>>> It would probably be good if I could merge this branch without +>>> having to worry about also immediatly merging that one. --[[Joey]] +>>> +>>>> I removed all dependencies on my `meta` branch from the `po` one. +>>>> This implied removing the `po_translation_status_in_links` and +>>>> `po_strictly_refresh_backlinks` features, and every link text is now +>>>> displayed in the master language. I believe the removed features really +>>>> enhance user experience of a translatable wiki, that's why I was +>>>> initially supposing the `meta` branch would be merged first. +>>>> IMHO, we'll need to come back to this quite soon after `po` is merged. +>>>> --[[intrigeri]] +>>>> +>>>> Maybe you should keep those features in a meta-po branch? +>>>> I did a cursory review of your meta last night, have some issues with it, +>>>> but this page isn't the place for a detailed review. --[[Joey]] +>>>> +>>>>> Done. --[[intrigeri]] +>>> +> * I'm very fearful of the `add_depends` in `postscan`. +> Does this make every page depend on every page that links +> to it? Won't this absurdly bloat the dependency pagespecs +> and slow everything down? And since nicepagetitle is given +> as the reason for doing it, and nicepagetitle isn't used, +> why do it? +>> +>> As explained in the 85f865b5d98e0122934d11e3f3eb6703e4f4c620 log: +>> this feature hits performance a bit. Its cost was quite small in my +>> real-world use-cases (a few percents bigger refresh time), but +>> could be bigger in worst cases. When using the po plugin with my +>> meta branch changes (i.e. the `nicepagetitle` thing), and having +>> enabled the option to display translation status in links, this +>> maintains the translation status up-to-date in backlinks. Same when +>> using meta title to make the pages titles translatable. It does +>> help having a nice and consistent translated wiki, but as it can +>> also involve problems, I just turned it into an option. +>> +>>> This has been completely removed for now due to the removal of +>>> the dependency on my `meta` branch. --[[intrigeri]] +>> +> * The po4a Suggests should be versioned to the first version +> that can be used safely, and that version documented in +> `plugins/po.mdwn`. +>> +>> Done. +>> +>> --[[intrigeri]] +> +> --[[Joey]] + +I reverted the `%backlinks` and `$backlinks_calculated` exposing. +The issue they were solving probably will arise again when I'll work +on my meta branch again (i.e. when the simplified po one is merged), +but the po thing is supposed to work without these ugly `our`. +Seems like it was the last unaddressed item from Joey's review, so I'm +daring a timid "please pull"... or rather, please review again :) +--[[intrigeri]] + +> Ok, I've reviewed and merged into my own po branch. It's looking very +> mergeable. +> +> * Is it worth trying to fix compatability with `indexpages`? +>> +>> Supporting `usedirs` being enabled or disabled was already quite +>> hard IIRC, so supporting all four combinations of `usedirs` and +>> `indexpages` settings will probably be painful. I propose we forget +>> about it until someone reports he/she badly needs it, and then +>> we'll see what can be done. +>> +> * Would it make sense to go ahead and modify `page.tmpl` to use +> OTHERLANGUAGES and PERCENTTRANSLATED, instead of documenting how to modify it? +>> +>> Done in my branch. +>> +> * Would it be better to disable po support for pages that use unsupported +> or poorly-supported markup languages? +> +>> I prefer keeping it enabled, as: +>> +>> * most wiki markups "almost work" +>> * when someone needs one of these to be fully supported, it's not +>> that hard to add dedicated support for it to po4a; if it were +>> disabled, I fear the ones who could do this would maybe think +>> it's blandly impossible and give up. +>> + +> * What's the reasoning behind checking that the link plugin +> is enabled? AFAICS, the same code in the scan hook should +> also work when other link plugins like camelcase are used. +> * In `pagetemplate` there is a comment that claims the code +> relies on `genpage`, but I don't see how it does; it seems +> to always add a discussion link? +> * Is there any real reason not to allow removing a translation? +> I'm imagining a spammy translation, which an admin might not +> be able to fix, but could remove. +> * Re the meta title escaping issue worked around by `change`. +> I suppose this does not only affect meta, but other things +> at scan time too. Also, handling it only on rebuild feels +> suspicious -- a refresh could involve changes to multiple +> pages and trigger the same problem, I think. Also, exposing +> this rebuild to the user seems really ugly, not confidence inducing. +> +> So I wonder if there's a better way. Such as making po, at scan time, +> re-run the scan hooks, passing them modified content (either converted +> from po to mdwn or with the escaped stuff cheaply de-escaped). (Of +> course the scan hook would need to avoid calling itself!) +> +> (This doesn't need to block the merge, but I hope it can be addressed +> eventually..) +> +> --[[Joey]] +>> +>> --[[intrigeri]] diff --git a/doc/plugins/contrib/siterel2pagerel.mdwn b/doc/plugins/contrib/siterel2pagerel.mdwn index 956b6728f..9b09657bf 100644 --- a/doc/plugins/contrib/siterel2pagerel.mdwn +++ b/doc/plugins/contrib/siterel2pagerel.mdwn @@ -13,11 +13,11 @@ other format that produces html. The code is available here: use strict; use IkiWiki 2.00; - sub import { #{{{ + sub import { hook(type => "sanitize", id => "siterel2pagerel", call => \&siterel2pagerel); - } # }}} + } - sub siterel2pagerel (@) { #{{{ + sub siterel2pagerel (@) { my %params=@_; my $baseurl=IkiWiki::baseurl($params{page}); my $content=$params{content}; @@ -25,6 +25,6 @@ other format that produces html. The code is available here: $content=~s/(<img(?:\s+(?:class|id|width|height)\s*="?\w+"?)*)\s+src=\s*"\/([^"]*)"/$1 src="$baseurl$2"/mig; # FIXME: do <script and everything else that can have URLs in it return $content; - } # }}} + } 1 diff --git a/doc/plugins/contrib/sourcehighlight.mdwn b/doc/plugins/contrib/sourcehighlight.mdwn index 2eb22e6ed..07ac2086f 100644 --- a/doc/plugins/contrib/sourcehighlight.mdwn +++ b/doc/plugins/contrib/sourcehighlight.mdwn @@ -10,13 +10,21 @@ where foo and bar are the (source-supported) languages you want to highlight ### Issues -- I would like to have a link to the raw source; using will_render() and then copying the file should work. +- I would like to have a link to the raw source; using will_render() and then copying the file should work. -- the common case of foo.c and foo.h breaks -because they both generate page working/dir/foo. -It looks to me like ikiwiki is hardcoded to strip the extension in `pagename()` (IkiWiki.pm). -This problem with sourcehighlight needs to be fixed before it is very useful. +> You might also like to look at the [[todo/source_link]] todo. -- [[Will]] - Is there a way to configure the colors used by source-highlight (other than editing the globally installed "default.style" file)? It would help if I could pass the command arbitrary command-line arguments; then I could configure which config file it's supposed to use. For instance, I'm not a fan of hard-coding the colors into the HTML output. IMHO, css-style formatting should be preferred. All that can be set via the command line ... --Peter > I don't really have time right now, but it should be easy to add, if you look at how src-lang is handled. Patches are welcome :-) --[[DavidBremner]] + +Note that [[Will]] wrote a plugin that uses source-highlight also. It's +available +[[here|todo/automatic_use_of_syntax_plugin_on_source_code_files/discussion]]. +--[[Joey]] + +To be honest, [[Will]]'s version of this looks more polished. I will try his +plugin and see if it can just replace mine. --[[DavidBremner]] + + +*Updated* Now uses keepextension so multiple extensions should be OK diff --git a/doc/plugins/contrib/unixauth.mdwn b/doc/plugins/contrib/unixauth.mdwn index d91ed45f1..76a847744 100644 --- a/doc/plugins/contrib/unixauth.mdwn +++ b/doc/plugins/contrib/unixauth.mdwn @@ -22,7 +22,7 @@ __Security__: [As with passwordauth](/security/#index14h2), be wary of sending u --- Wrapper.pm.orig 2008-07-29 00:09:10.000000000 -0400 +++ Wrapper.pm - @@ -28,7 +28,7 @@ sub gen_wrapper () { #{{{ + @@ -28,7 +28,7 @@ sub gen_wrapper () { my @envsave; push @envsave, qw{REMOTE_ADDR QUERY_STRING REQUEST_METHOD REQUEST_URI CONTENT_TYPE CONTENT_LENGTH GATEWAY_INTERFACE @@ -46,16 +46,16 @@ __Security__: [As with passwordauth](/security/#index14h2), be wary of sending u use strict; use IkiWiki 2.00; - sub import { #{{{ + sub import { hook(type => "getsetup", id => "unixauth", call => \&getsetup); hook(type => "formbuilder_setup", id => "unixauth", call => \&formbuilder_setup); hook(type => "formbuilder", id => "unixauth", call => \&formbuilder); hook(type => "sessioncgi", id => "unixauth", call => \&sessioncgi); - } # }}} + } - sub getsetup () { #{{{ + sub getsetup () { return unixauth_type => { type => "string", @@ -83,10 +83,10 @@ __Security__: [As with passwordauth](/security/#index14h2), be wary of sending u safe => 0, rebuild => 1, }, - } #}}} + } # Checks if a string matches a user's password, and returns true or false. - sub checkpassword ($$;$) { #{{{ + sub checkpassword ($$;$) { my $user=shift; my $password=shift; my $field=shift || "password"; @@ -131,9 +131,9 @@ __Security__: [As with passwordauth](/security/#index14h2), be wary of sending u } return $ret; - } #}}} + } - sub formbuilder_setup (@) { #{{{ + sub formbuilder_setup (@) { my %params=@_; my $form=$params{form}; @@ -204,7 +204,7 @@ __Security__: [As with passwordauth](/security/#index14h2), be wary of sending u } } - sub formbuilder (@) { #{{{ + sub formbuilder (@) { my %params=@_; my $form=$params{form}; @@ -225,12 +225,12 @@ __Security__: [As with passwordauth](/security/#index14h2), be wary of sending u my $user_name=$form->field('name'); } } - } #}}} + } - sub sessioncgi ($$) { #{{{ + sub sessioncgi ($$) { my $q=shift; my $session=shift; - } #}}} + } 1 diff --git a/doc/plugins/contrib/unixauth/discussion.mdwn b/doc/plugins/contrib/unixauth/discussion.mdwn index dfa4fe6cc..232649863 100644 --- a/doc/plugins/contrib/unixauth/discussion.mdwn +++ b/doc/plugins/contrib/unixauth/discussion.mdwn @@ -32,3 +32,7 @@ I've added support for [checkpassword](http://cr.yp.to/checkpwd/interface.html), > to disentangle the two locks. --[[Joey]] >> Ah, ok, I misunderstood your comment. I'll see what I can figure out. --[[schmonz]] + +>>> My time's been limited for this, but I just saw [[todo/avoid_thrashing]]. How does that interact with pwauth or checkpassword? --[[schmonz]] + +>>>> The DOS still happens, it just uses less memory. --[[Joey]] diff --git a/doc/plugins/creole.mdwn b/doc/plugins/creole.mdwn index c6491f754..6961e8d1d 100644 --- a/doc/plugins/creole.mdwn +++ b/doc/plugins/creole.mdwn @@ -13,4 +13,10 @@ wiki markup formats, so should be fairly easy to guess at. There is also a Links are standard [[WikiLinks|ikiwiki/WikiLink]]. Links and [[directives|ikiwiki/directive]] inside `{{{ }}}` blocks are still expanded, -since this happens before the creole format is processed. +since this happens before the creole format is processed. (You need to escape +them manually, via \\\[[directives]], the ~ escaping of creole doesn't work on +this.) + +The standard ikiwiki [[WikiLinks|ikiwiki/WikiLink]] is almost the same as Creole link, except that creole uses \[[pagename|description]] while ikiwiki uses \[[description|pagename]]. + + diff --git a/doc/plugins/creole/discussion.mdwn b/doc/plugins/creole/discussion.mdwn index 36b7ba869..38ee2bd78 100644 --- a/doc/plugins/creole/discussion.mdwn +++ b/doc/plugins/creole/discussion.mdwn @@ -8,4 +8,8 @@ I've installed Text::WikiCreole 0.05 and enabled the plugin, but I get an error >> I've added the patch to pkgsrc as well. Thanks. --[[schmonz]] +>> Currently the creole plugin is included in ikiwiki but the ikiwiki deb (3.0.3) doesn't suggests libtext-wikicreole-perl. Why? --[[weakish]] + +>>> forgot, done now --[[Joey]] + I'm moving over a really stinkingly old UseMod and creole seems the nearest match. I've worked out that Bare /Subpage links need to become \[\[Subpage\]\], and Top/Sub links need to be \[\[Top/Sub\]\] (or \[\[Top/Sub|Top/Sub\]\], to display in exactly the same way), but I'm stuck on generic hyperlinks. The creole cheat sheet says I should be able to do \[\[http://url.path/foo|LinkText\]\], but that comes out as a link to create the "linktext" page, and Markdown-style \[Link Text\](http://url.path/foo) just gets rendered as is. Any suggestions? --[[schmonz]] diff --git a/doc/plugins/cutpaste.mdwn b/doc/plugins/cutpaste.mdwn index 1b78e60fc..f74f8a269 100644 --- a/doc/plugins/cutpaste.mdwn +++ b/doc/plugins/cutpaste.mdwn @@ -1,4 +1,4 @@ -[[!template id=plugin name=toggle author="[[Enrico]]"]] +[[!template id=plugin name=cutpaste author="[[Enrico]]"]] [[!tag type/chrome]] This plugin provides the [[ikiwiki/directive/cut]], diff --git a/doc/plugins/ddate.mdwn b/doc/plugins/ddate.mdwn index e82760d88..741606a6e 100644 --- a/doc/plugins/ddate.mdwn +++ b/doc/plugins/ddate.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=ddate author="[[Joey]]"]] [[!tag type/fun]] +[[!tag type/date]] Enables use of Discordian dates. `--timeformat` can be used to change the date format; see `ddate(1)`. diff --git a/doc/plugins/discussion.mdwn b/doc/plugins/discussion.mdwn index 70157f1e2..854307a98 100644 --- a/doc/plugins/discussion.mdwn +++ b/doc/plugins/discussion.mdwn @@ -34,12 +34,3 @@ Any objections to listing plugins alphabetically rather than by creation date? >> "recently changed" list with the 10 most recently changed plugins >> at the top. That would allow what you suggested, but still allow >> the main list to be alphabetical. -- [[Will]] - -How about adding a deprecated tag in order to clean up the plugin list? - -> AFAIK it's currently the only one. --[[Joey]] - -For instance [[googlecalendar]] is listed as plugin but should probably be removed from Ikiwiki in a future major version (v3?). - --- [[AlexandreDupas]] - diff --git a/doc/plugins/embed.mdwn b/doc/plugins/embed.mdwn index 1d43061e0..85592cb72 100644 --- a/doc/plugins/embed.mdwn +++ b/doc/plugins/embed.mdwn @@ -13,6 +13,14 @@ In the examples below, the parts of the html that you can change are denoted with "XXX"; everything else must appear exactly as shown to be accepted by the plugin. +**This plugin is deprecated.** Rather than relying on these complex lists +of safe content, which constantly fall out of date, you're recommended to +configure the [[htmlscrubber]] to not scrub some pages, which only trusted +users can edit. Then you can embed anything from anywhere on those pages. +See [[tips/embedding_content]] for details and examples. +This plugin's lists of safe embedded content will not be maintained, and +the plugin will be removed in a future release. + ## google maps Use html like this to embed a map: diff --git a/doc/plugins/format.mdwn b/doc/plugins/format.mdwn new file mode 100644 index 000000000..91e707fcf --- /dev/null +++ b/doc/plugins/format.mdwn @@ -0,0 +1,9 @@ +[[!template id=plugin name=format core=0 author="[[Joey]]"]] +[[!tag type/format]] + +This plugin allows mixing different page formats together, by embedding +text formatted one way inside a page formatted another way. This is done +using the [[ikiwiki/directive/format]] [[ikiwiki/directive]]. + +For example, it could be used to embed an [[otl]] outline inside a page +that is formatted as [[mdwn]]. diff --git a/doc/plugins/format/discussion.mdwn b/doc/plugins/format/discussion.mdwn new file mode 100644 index 000000000..df8448ed6 --- /dev/null +++ b/doc/plugins/format/discussion.mdwn @@ -0,0 +1,15 @@ +Is there any way to tell if an htmlize hook have been called from a format directive? + +I am currently modifying the [[contrib/highlightcode]] plugin by [[sabr]] and I wanted to have a different behavior depending on the fact that the htmlize hook is called from a format directive or not. For instance, this could disable the raw copy of the highlighted code. Since I have enabled the keepextension option, I tried to rely on the page extension to decide whenever I have to create the raw file or not but this does not seems a reliable approach. + +One possible solution is to add an optional parameter to the htmlize hook (and thus to htmlize function in IkiWiki.pm) which could tell if this is the format directive that called the function but I am not sure that is a good way to do this. + +> It's (probably) not just the format directive that has a potential problem here. +> Imagine a syntax highlighted source code file that contains some other +> directive, such as table or meta. Such a directive calls `htmlize` on the +> parameters passed to it. +> +> There is one way to detect this ATM. If `%IkiWiki::preprocessing` has +> anything in it, then ikiwiki is in the middle of handling a preprocessing +> directive. So you could check that. It's getting into internals, so not +> ideal.. --[[Joey]] diff --git a/doc/plugins/goodstuff.mdwn b/doc/plugins/goodstuff.mdwn index 83b60f4fa..ee1bffcfa 100644 --- a/doc/plugins/goodstuff.mdwn +++ b/doc/plugins/goodstuff.mdwn @@ -12,7 +12,6 @@ Currently included: * [[brokenlinks]] * [[img]] * [[map]] -* [[meta]] * [[more]] * [[orphans]] * [[pagecount]] @@ -25,5 +24,6 @@ Currently included: * [[template]] * [[toc]] * [[toggle]] +* [[repolist]] New plugins will be added to this bundle from time to time. diff --git a/doc/plugins/google/discussion.mdwn b/doc/plugins/google/discussion.mdwn new file mode 100644 index 000000000..babc919d2 --- /dev/null +++ b/doc/plugins/google/discussion.mdwn @@ -0,0 +1,6 @@ +This plugin uses the googleform.tmpl +which produces valid HTML but invalid XHTML. +This is not very good since the default ikiwiki +templates produce XHTML instead of HTML. + +> Fixed, thanks for the patch! --[[Joey]] diff --git a/doc/plugins/googlecalendar.mdwn b/doc/plugins/googlecalendar.mdwn deleted file mode 100644 index bca2ae74f..000000000 --- a/doc/plugins/googlecalendar.mdwn +++ /dev/null @@ -1,20 +0,0 @@ -[[!template id=plugin name=googlecalendar author="[[Joey]]"]] -[[!tag type/special-purpose]] - -*Note*: This plugin is deprecated. Please switch to the [[embed]] plugin. - -This plugin allows embedding a google calendar iframe in the wiki. -Normally, if the [[htmlscrubber]] is enabled, such iframes are scrubbed out -of the wiki content since they're not very safe if created by malicious -users. But some iframes are legitimate, and safe, if you trust the embedded -content. This plugin is an example of how to deal with this in ikiwiki. - -Example use: - - \[[!googlecalendar html=""" - <iframe src="http://www.google.com/calendar/embed?src=adkrdken8mupngh13jshlbenoc%40group.calendar.google.com&title=OSEL%20Calendar&chrome=NAVIGATION&bgcolor=%2371d873&height=588" style=" border-width:0 " width="480" frameborder="0" height="588"></iframe> - """]] - -The iframe should be the one provided by google. Note that it's used in a -way that avoids cross-site scripting attacks, assuming you trust google's -content. diff --git a/doc/plugins/goto.mdwn b/doc/plugins/goto.mdwn new file mode 100644 index 000000000..9c401c5d2 --- /dev/null +++ b/doc/plugins/goto.mdwn @@ -0,0 +1,10 @@ +[[!template id=plugin name=goto author="[[Simon_McVittie|smcv]]"]] +[[!tag type/useful]] + +This plugin adds a `do=goto` mode for the IkiWiki CGI script. It's mainly +for internal use by the [[404]], [[comments]] and [[recentchanges]] +plugins, which enable it automatically. + +With this plugin enabled you can link to `ikiwiki.cgi?do=goto&page=some/where` +to make a link that will redirect to the page `/some/where` if it exists, or +offer a link to create it if it doesn't. diff --git a/doc/plugins/htmlbalance.mdwn b/doc/plugins/htmlbalance.mdwn new file mode 100644 index 000000000..f4e2298ee --- /dev/null +++ b/doc/plugins/htmlbalance.mdwn @@ -0,0 +1,9 @@ +[[!template id=plugin name=htmlbalance author="[[Simon_McVittie|smcv]]"]] +[[!tag type/html]] + +This plugin ensures that the HTML emitted by ikiwiki contains well-balanced +HTML tags, by parsing it with [[!cpan HTML::TreeBuilder]] and re-serializing it. This +acts as a lighter-weight alternative to [[plugins/htmltidy]]; it doesn't +ensure validity, but it does at least ensure that formatting from a +blog post pulled in by the [[ikiwiki/directive/inline]] directive doesn't +leak into the rest of the page. diff --git a/doc/plugins/htmlbalance/discussion.mdwn b/doc/plugins/htmlbalance/discussion.mdwn new file mode 100644 index 000000000..c66528a4f --- /dev/null +++ b/doc/plugins/htmlbalance/discussion.mdwn @@ -0,0 +1,10 @@ +Would it be possible to use [[!cpan HTML::Entities]] rather than +`XML::Atom::Util` for encoding entities? The former is already an ikiwiki +dependency (via [[!cpan HTML::Parser]]). + +> Now switched to HTML::Entities --[[Joey]] + +I also wonder if there's any benefit to using this plugin aside from with +aggregate. Perhaps a small one but aggregate seems like the main case.. +wondering if it would be better to just have aggregate balanace the html +automatically and do away with the separate plugin. --[[Joey]] diff --git a/doc/plugins/htmlscrubber.mdwn b/doc/plugins/htmlscrubber.mdwn index 7db372e1b..c59b46e14 100644 --- a/doc/plugins/htmlscrubber.mdwn +++ b/doc/plugins/htmlscrubber.mdwn @@ -32,10 +32,10 @@ other HTML-related functionality, such as whether [[meta]] allows potentially unsafe HTML tags. The `htmlscrubber_skip` configuration setting can be used to skip scrubbing -of some pages. Set it to a [[PageSpec]], such as "!*/Discussion", and pages -matching that can have all the evil CSS, JavsScript, and unsafe html -elements you like. One safe way to use this is to use [[lockedit]] to lock -those pages, so only admins can edit them. +of some pages. Set it to a [[ikiwiki/PageSpec]], such as "!*/Discussion", +and pages matching that can have all the evil CSS, JavsScript, and unsafe +html elements you like. One safe way to use this is to use [[lockedit]] to +lock those pages, so only admins can edit them. ---- diff --git a/doc/plugins/htmltidy.mdwn b/doc/plugins/htmltidy.mdwn index f675a01ae..580e56f59 100644 --- a/doc/plugins/htmltidy.mdwn +++ b/doc/plugins/htmltidy.mdwn @@ -7,4 +7,5 @@ emitted by ikiwiki. Besides being nicely formatted, this helps ensure that even if users enter suboptimal html, your wiki generates valid html. Note that since tidy is an external program, that is run each time a page -is built, this plugin will slow ikiwiki down somewhat. +is built, this plugin will slow ikiwiki down somewhat. [[plugins/htmlbalance]] +might provide a faster alternative. diff --git a/doc/plugins/img/discussion.mdwn b/doc/plugins/img/discussion.mdwn index 02d46e380..e1bb2d15b 100644 --- a/doc/plugins/img/discussion.mdwn +++ b/doc/plugins/img/discussion.mdwn @@ -5,3 +5,8 @@ logo link to \[[hurd/logo]] / <http://www.bddebian.com/~wiki/hurd/logo/> instead of linking to the PNG image file. --[[tschwinge]] > Done, use link=somepage --[[Joey]] + +It would be handy if the `class` and `id` tags were passed through to the surrounding `table` in the case of `caption` being present. Would this break anything? --[[neale]] + +> Seems unlikely to break *too* much. I can imagine css that styles the img +> unexpectedly applying the table. --[[Joey]] diff --git a/doc/plugins/lockedit.mdwn b/doc/plugins/lockedit.mdwn index 71bf232ab..c8f64ea47 100644 --- a/doc/plugins/lockedit.mdwn +++ b/doc/plugins/lockedit.mdwn @@ -4,7 +4,7 @@ This plugin allows the administrator of a wiki to lock some pages, limiting who can edit them using the online interface. This doesn't prevent anyone who can commit to the underlying revision control system from editing the -pages, however. +pages, however. (Unless you set up [[tips/untrusted_git_push]].) The `locked_pages` setting configures what pages are locked. It is a [[ikiwiki/PageSpec]], so you have lots of control over what kind of pages @@ -17,6 +17,10 @@ One handy thing to do if you're using ikiwiki for your blog is to lock posts in your blog, while still letting them comment via the Discussion pages. +Alternatively, if you're using the [[comments]] plugin, you can lock +"!postcomment(*)" to allow users to comment on pages, but not edit anything +else. + Wiki administrators can always edit locked pages. The [[ikiwiki/PageSpec]] can specify that some pages are not locked for some users. For example, "important_page and !user(joey)" locks `important_page` while still diff --git a/doc/plugins/mdwn/discussion.mdwn b/doc/plugins/mdwn/discussion.mdwn new file mode 100644 index 000000000..4b05e7f4e --- /dev/null +++ b/doc/plugins/mdwn/discussion.mdwn @@ -0,0 +1,7 @@ +Unlike other format, ikiwiki is somehow depends +on mdwn, since the underlay dir +is written in mdwn. If you want to disable mdwn, +you need to overwrite the underlay +dir (set underlaydir in ikiwiki.setup +to your own underlay dir or replace underlay pages +in your $SRC). diff --git a/doc/plugins/meta.mdwn b/doc/plugins/meta.mdwn index afd554993..e49bdcc50 100644 --- a/doc/plugins/meta.mdwn +++ b/doc/plugins/meta.mdwn @@ -1,4 +1,4 @@ -[[!template id=plugin name=meta author="[[Joey]]"]] +[[!template id=plugin name=meta core=1 author="[[Joey]]"]] [[!tag type/meta]] This plugin provides the [[ikiwiki/directive/meta]] [[ikiwiki/directive]], diff --git a/doc/plugins/pagecount.mdwn b/doc/plugins/pagecount.mdwn index 6235963d3..a56027e60 100644 --- a/doc/plugins/pagecount.mdwn +++ b/doc/plugins/pagecount.mdwn @@ -6,5 +6,5 @@ This plugin provides the [[ikiwiki/directive/pagecount]] currently in the wiki. If it is turned on it can tell us that this wiki includes -[[!pagecount pages="* and !recentchanges"]] -pages, of which [[!pagecount pages="*/Discussion"]] are discussion pages. +[[!pagecount ]] pages, of which +[[!pagecount pages="*/Discussion"]] are discussion pages. diff --git a/doc/plugins/passwordauth/discussion.mdwn b/doc/plugins/passwordauth/discussion.mdwn index f4e7ae7a1..672970c21 100644 --- a/doc/plugins/passwordauth/discussion.mdwn +++ b/doc/plugins/passwordauth/discussion.mdwn @@ -9,3 +9,71 @@ the *Preferences -- Subscriptions*. --[[tschwinge]] >> Aha, then the problem is Firefox, which is automatically filling the >> *Password* field with its previous value, but not filling the >> *Confirm Password* one. --[[tschwinge]] + +## easy access to the userdb for apache auth? + +My use case is: + +* restricted ikiwiki +* read/edit only allowed from the local network (done with apache restrictions) +* edit only for people authenticated (done with vanilla ikiwiki passwordauth) + +I would like to allow people to read/edit the wiki from outside of the +local network, if and only if they already have an ikiwiki account. + +[[httpauth]] doesn't fit since it doesn't allow anonymous local users +to create their own account. I want a single, local, simple auth +database. + +My (naïve?) idea would be: + +* keep the [[passwordauth]] system +* provide a way for Apache to use the userdb for authentication if +people want to connect from outside + +I looked at the various auth modules for apache2. It seems that none +can use a "perl Storable data" file. So, I think some solutions could +be: + +* use a sqlite database instead of a perl Storable file + * can be used with + [mod_auth_dbd](http://httpd.apache.org/docs/2.2/mod/mod_authn_dbd.html) + * requires a change in ikiwiki module [[passwordauth]] +* use an external program to read the userdb and talk with + [mod_auth_external](http://unixpapa.com/mod_auth_external.html) + * requires the maintainance of this external auth proxy over ikiwiki + userdb format changes + * (I don't know perl) +* include this wrapper in ikiwiki + * something like `ikiwiki --auth user:pass:userdb` check the + `user:pass` pair in `userdb` and returns an Accept/Reject flag to + Apache + * requires a change in ikiwiki core + * still requires + [mod_auth_external](http://unixpapa.com/mod_auth_external.html) +* do it with Apache perl sections + * (I don't know perl) + +Any opinion/suggestion/solution to this is welcome and appreciated. + +-- +[[NicolasLimare]] + +For a similar use case, I've been intending to implement +[[todo/httpauth_feature_parity_with_passwordauth]], but your idea may +actually be the way to go. IMHO, the Perl sections idea is the +easiest to setup, but on the long run, I'd prefer ikiwiki to optionnally +use a userdb storage backend supported at least by Apache and lighttpd. +--[[intrigeri]] + +Tons of CPAN modules may help, but most of them are specific to `mod_perl`, +and AFAIK, ikiwiki is generally not run with `mod_perl`. It's not clear to me +wether these modules depend on the webapp to be run with `mod_perl` set +as the script handler, or only on `mod_perl` to be installed and loaded. + +* CPAN's `Apache::AuthenHook` allows to plug arbitrary Perl handlers as + Apache authentication providers. +* CPAN's `Apache::Authen::Program` (`mod_perl`) +* [http://www.openfusion.com.au/labs/mod_auth_tkt/](mod_auth_tkt) along with CPAN's + `Apache::AuthTkt` +--[[intrigeri]] diff --git a/doc/plugins/pingee.mdwn b/doc/plugins/pingee.mdwn index d012004f9..6156c235f 100644 --- a/doc/plugins/pingee.mdwn +++ b/doc/plugins/pingee.mdwn @@ -3,7 +3,7 @@ This plugin causes ikiwiki to listen for pings, typically delivered from another ikiwiki instance using the [[pinger]] plugin. When a ping is -recieved, ikiwiki will update the wiki, the same as if `ikiwiki --refresh` +received, ikiwiki will update the wiki, the same as if `ikiwiki --refresh` were ran at the command line. An url such as the following is used to trigger a ping: diff --git a/doc/plugins/prettydate.mdwn b/doc/plugins/prettydate.mdwn index 9a67f5dca..11ad4252f 100644 --- a/doc/plugins/prettydate.mdwn +++ b/doc/plugins/prettydate.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=prettydate author="[[Joey]]"]] -[[!tag type/format]] +[[!tag type/date]] Enabling this plugin changes the dates displayed on pages in the wiki to a format that is nice and easy to read. Examples: "late Wednesday evening, diff --git a/doc/plugins/relativedate.mdwn b/doc/plugins/relativedate.mdwn new file mode 100644 index 000000000..3ada0864b --- /dev/null +++ b/doc/plugins/relativedate.mdwn @@ -0,0 +1,16 @@ +[[!template id=plugin name=relativedate author="[[Joey]]"]] +[[!tag type/date]] + +This plugin lets dates be displayed in relative form. Examples: "2 days ago", +"1 month and 3 days ago", "30 minutes ago". Hovering over the date will +cause a tooltip to pop up with the absolute date. + +This only works in browsers with javascript enabled; other browsers will +show the absolute date instead. Also, this plugin can be used with other +plugins like [[prettydate]] that change how the absolute date is displayed. + +If this plugin is enabled, you may also add relative dates to pages in the +wiki, by using html elements in the "relativedate" class. For example, this +will display as a relative date: + + <span class="relativedate">Tue Jan 20 12:00:00 EDT 2009</span> diff --git a/doc/plugins/repolist.mdwn b/doc/plugins/repolist.mdwn new file mode 100644 index 000000000..9b3a7575e --- /dev/null +++ b/doc/plugins/repolist.mdwn @@ -0,0 +1,17 @@ +[[!template id=plugin name=repolist author="[[Joey]]"]] +[[!tag type/useful]] + +This plugin allows you to configure ikiwiki with the location of +[[rcs]] repositories for your wiki's source. This is done via the +"repositories" setting in the setup file. Once you tell it where the source +to your wiki can be downloaded from, this information can be published on +your wiki in various ways. + +This plugin supports the [rel-vcs-*](http://kitenet.net/~joey/rfc/rel-vcs/) +microformat, and uses it to embed the repository location information in +every wiki page. + +By using this plugin, you will make [[Joey]] very happy, as he will be able +to easily check out the source of your wiki, for purposes of debugging and +general curiosity. More generally, making it easy for others to find the +repository for your wiki is just a Plain Good Idea(TM). diff --git a/doc/plugins/rst.mdwn b/doc/plugins/rst.mdwn index 9355597ac..5e97e2d80 100644 --- a/doc/plugins/rst.mdwn +++ b/doc/plugins/rst.mdwn @@ -11,7 +11,7 @@ ikiwiki. Limitations include: * There are issues with inserting raw html into documents, as ikiwiki does with [[WikiLinks|ikiwiki/WikiLink]] and many - preprocessor [[directives|ikiwiki/directive]]. + [[directives|ikiwiki/directive]]. So while you may find this useful for importing old files into your wiki, using this as your main markup language in ikiwiki isn't recommended at diff --git a/doc/plugins/shortcut/discussion.mdwn b/doc/plugins/shortcut/discussion.mdwn index 8b1378917..4e11ce08c 100644 --- a/doc/plugins/shortcut/discussion.mdwn +++ b/doc/plugins/shortcut/discussion.mdwn @@ -1 +1,12 @@ +The plugin depends on [[mdwn]]. If you have +disabled [[mdwn]], to get [[shortcut]] work, you need +commit in a shortcuts.ext (ext is `rcs|creole|html|txt|etc`), +and edit/patch [[shortcut]]. + +Maybe use the `default_pageext` is better than hardcode .mdwn? + +--[[weakish]] + +> done, it will use `default_pageext` now --[[Joey]] + diff --git a/doc/plugins/tag.mdwn b/doc/plugins/tag.mdwn index 17bb086a1..8ff70a069 100644 --- a/doc/plugins/tag.mdwn +++ b/doc/plugins/tag.mdwn @@ -5,6 +5,9 @@ This plugin provides the [[ikiwiki/directive/tag]] and [[ikiwiki/directive/taglink]] [[directives|ikiwiki/directive]]. These directives allow tagging pages. +It also provides the `tagged()` [[ikiwiki/PageSpec]], which can be used to +match pages that are tagged with a specific tag. + [[!if test="enabled(tag)" then=""" This wiki has the tag plugin enabled, so you'll see a note below that this page is tagged with the "tags" tag. diff --git a/doc/plugins/tag/discussion.mdwn b/doc/plugins/tag/discussion.mdwn index 7e7b88bc5..b6dab5358 100644 --- a/doc/plugins/tag/discussion.mdwn +++ b/doc/plugins/tag/discussion.mdwn @@ -22,3 +22,9 @@ AOLMODE=true echo "I too would really like this feature, which would make cgi fr better" --[[DavidBremner]] Please make the actual text used a template some way or another. I may want `map` instead of `inline`. --[[madduck]] + + +See [[todo/auto-create tag pages according to a template]] + +-- Jeremy Schultz <jeremy.schultz@uleth.ca> + diff --git a/doc/plugins/textile/discussion.mdwn b/doc/plugins/textile/discussion.mdwn deleted file mode 100644 index 945c9b46d..000000000 --- a/doc/plugins/textile/discussion.mdwn +++ /dev/null @@ -1 +0,0 @@ -.
\ No newline at end of file diff --git a/doc/plugins/type/date.mdwn b/doc/plugins/type/date.mdwn new file mode 100644 index 000000000..eae1226da --- /dev/null +++ b/doc/plugins/type/date.mdwn @@ -0,0 +1 @@ +These plugins control how ikiwiki displays dates. diff --git a/doc/plugins/underlay.mdwn b/doc/plugins/underlay.mdwn new file mode 100644 index 000000000..09d096a6e --- /dev/null +++ b/doc/plugins/underlay.mdwn @@ -0,0 +1,14 @@ +[[!template id=plugin name=underlay author="[[Simon_McVittie|smcv]]"]] +[[!tag type/useful]] + +This plugin adds an `add_underlays` option to the `.setup` file. +Its value is a list of underlay directories whose content is added to the wiki. + +Multiple underlays are normally set up automatically by other plugins (for +instance, the images used by the [[plugins/smiley]] plugin), but they can also be +used as a way to pull in external files that you don't want in revision control, +like photos or software releases. + +Directories in `add_underlays` should usually be absolute. If relative, they're +interpreted as relative to the parent directory of the basewiki underlay, which +is probably not particularly useful in this context. diff --git a/doc/plugins/wmd.mdwn b/doc/plugins/wmd.mdwn new file mode 100644 index 000000000..dc9a30703 --- /dev/null +++ b/doc/plugins/wmd.mdwn @@ -0,0 +1,16 @@ +[[!template id=plugin name=wmd author="[[Will]]"]] +[[!tag type/chrome]] + +[WMD](http://wmd-editor.com/) is a What You See Is What You Mean editor for +[[mdwn]]. This plugin makes WMD be used for editing pages in the wiki. + +To use the plugin, you will need to install WMD. Download the [WMD +source](http://wmd-editor.com/downloads/wmd-1.0.1.zip). In that zip file +you'll find a few example html files, a readme and `wmd` directory. Create +a 'wmd' subdirectory in the ikiwiki `underlaydir` directory (ie `sudo mkdir +/usr/share/ikiwiki/wmd`). Move the `wmd` directory into the directory you +made. You should now have a `wmd/wmd/wmd.js` file as well as some other +javascript files and an images directory in the same place. + +Note that the WMD plugin does **not** handle ikiwiki directives. For this +reason the normal `preview` button remains. diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index 1b78f5900..696bc6bc3 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -19,7 +19,7 @@ that can be fleshed out to make a useful plugin. `IkiWiki::Plugin::pagecount` is another simple example. All perl plugins should `use IkiWiki` to import the ikiwiki plugin interface. It's a good idea to include the version number of the plugin interface that your plugin -expects: `use IkiWiki 2.00`. +expects: `use IkiWiki 3.00`. An external plugin is an executable program. It can be written in any language. Its interface to ikiwiki is via XML RPC, which it reads from @@ -55,8 +55,8 @@ plugin, and a "call" parameter, which tells what function to call for the hook. An optional "last" parameter, if set to a true value, makes the hook run -after all other hooks of its type. Useful if the hook depends on some other -hook being run first. +after all other hooks of its type, and an optional "first" parameter makes +it run first. Useful if the hook depends on some other hook being run first. ## Types of hooks @@ -107,7 +107,7 @@ adding or removing files from it. This hook is called early in the process of building the wiki, and is used as a first pass scan of the page, to collect metadata about the page. It's -mostly used to scan the page for WikiLinks, and add them to `%links`. +mostly used to scan the page for [[WikiLinks|ikiwiki/WikiLink]], and add them to `%links`. Present in IkiWiki 2.40 and later. The function is passed named parameters "page" and "content". Its return @@ -168,7 +168,7 @@ htmlize the page) along with the rest of the page. hook(type => "linkify", id => "foo", call => \&linkify); -This hook is called to convert [[WikiLinks|WikiLink]] on the page into html +This hook is called to convert [[WikiLinks|ikiwiki/WikiLink]] on the page into html links. The function is passed named parameters "page", "destpage", and "content". It should return the linkified content. Present in IkiWiki 2.40 and later. @@ -189,14 +189,18 @@ The function is passed named parameters: "page" and "content" and should return the htmlized content. If `hook` is passed an optional "keepextension" parameter, set to a true -value, then this extension will not be stripped from the source filename when +value, then the extension will not be stripped from the source filename when generating the page. +If `hook` is passed an optional "noextension" parameter, set to a true +value, then the id parameter specifies not a filename extension, but +a whole filename that can be htmlized. This is useful for files +like `Makefile` that have no extension. + ### pagetemplate hook(type => "pagetemplate", id => "foo", call => \&pagetemplate); - [[Templates|wikitemplates]] are filled out for many different things in ikiwiki, like generating a page, or part of a blog page, or an rss feed, or a cgi. This hook allows modifying the variables available on those @@ -304,7 +308,7 @@ can check if the session object has a "name" parameter set. ### canedit - hook(type => "canedit", id => "foo", call => \&pagelocked); + hook(type => "canedit", id => "foo", call => \&canedit); This hook can be used to implement arbitrary access methods to control when a page can be edited using the web interface (commits from revision control @@ -322,6 +326,26 @@ This hook should avoid directly redirecting the user to a signin page, since it's sometimes used to test to see which pages in a set of pages a user can edit. +### checkcontent + + hook(type => "checkcontent", id => "foo", call => \&checkcontent); + +This hook is called to check the content a user has entered on a page, +before it is saved, and decide if it should be allowed. + +It is passed named parameters: `content`, `page`, `cgi`, and `session`. If +the content the user has entered is a comment, it may also be passed some +additional parameters: `author`, `url`, and `subject`. The `subject` +parameter may also be filled with the user's comment about the change. + +Note: When the user edits an existing wiki page, the passed `content` will +include only the lines that they added to the page, or modified. + +The hook should return `undef` on success. If the content is disallowed, it +should return a message stating what the problem is, or a function +that can be run to perform whatever action is necessary to allow the user +to post the content. + ### editcontent hook(type => "editcontent", id => "foo", call => \&editcontent); @@ -415,7 +439,7 @@ describes the plugin as a whole. For example: * `example` can be set to an example value. * `description` is a short description of the option. * `link` is a link to further information about the option. This can either - be a wikilink, or an url. + be a [[ikiwiki/WikiLink]], or an url. * `advanced` can be set to true if the option is more suitable for advanced users. * `safe` should be false if the option should not be displayed in unsafe @@ -432,7 +456,7 @@ describes the plugin as a whole. For example: To import the ikiwiki plugin interface: - use IkiWiki '2.00'; + use IkiWiki '3.00'; This will import several variables and functions into your plugin's namespace. These variables and functions are the ones most plugins need, @@ -487,7 +511,7 @@ use the following hashes, using a page name as the key: destination file. * `%pagesources` contains the name of the source file for each page. -Also, the %IkiWiki::version variable contains the version number for the +Also, the `%IkiWiki::version` variable contains the version number for the ikiwiki program. ### Library functions @@ -610,6 +634,16 @@ A failure to write the file will result in it dying with an error. If the destination directory doesn't exist, it will first be created. +The filename and directory are separate parameters because of +some security checks done to avoid symlink attacks. Before writing a file, +it checks to make sure there's not a symlink with its name, to avoid +following the symlink. If the filename parameter includes a subdirectory +to put the file in, it also checks if that subdirectory is a symlink, etc. +The directory parameter, however, is not checked for symlinks. So, +generally the directory parameter is a trusted toplevel directory like +the srcdir or destdir, and any subdirectories of this are included in the +filename parameter. + #### `will_render($$)` Given a page name and a destination file name (not including the base @@ -651,7 +685,7 @@ a wiki page name. #### `linkpage($)` This converts text that could have been entered by the user as a -[[WikiLink]] into a wiki page name. +[[ikiwiki/WikiLink]] into a wiki page name. #### `srcfile($;$)` @@ -697,11 +731,15 @@ This can be called when creating a new page, to determine what filename to save the page to. It's passed a page name, and its type, and returns the name of the file to create, relative to the srcdir. -#### `targetpage($$)` +#### `targetpage($$;$)` Passed a page and an extension, returns the filename that page will be rendered to. +Optionally, a third parameter can be passed, to specify the preferred +filename of the page. For example, `targetpage("foo", "rss", "feed")` +will yield something like `foo/feed.rss`. + ## Miscellaneous ### Internal use pages @@ -712,7 +750,7 @@ are collected together to form the RecentChanges page, for example. To make an internal use page, register a filename extension that starts with "_". Internal use pages cannot be edited with the web interface, -generally shouldn't contain wikilinks or preprocessor directives (use +generally shouldn't contain [[WikiLinks|ikiwiki/WikiLink]] or preprocessor directives (use either on them with extreme caution), and are not matched by regular PageSpecs glob patterns, but instead only by a special `internal()` [[ikiwiki/PageSpec]]. @@ -821,6 +859,30 @@ it up in the history. It's ok if this is not implemented, and throws an error. +#### `rcs_receive()` + +This is called when ikiwiki is running as a pre-receive hook (or +equivalent), and is testing if changes pushed into the RCS from an +untrusted user should be accepted. This is optional, and doesn't make +sense to implement for all RCSs. + +It should examine the incoming changes, and do any sanity +checks that are appropriate for the RCS to limit changes to safe file adds, +removes, and changes. If something bad is found, it should exit +nonzero, to abort the push. Otherwise, it should return a list of +files that were changed, in the form: + + { + file => # name of file that was changed + action => # either "add", "change", or "remove" + path => # temp file containing the new file content, only + # needed for "add"/"change", and only if the file + # is an attachment, not a page + } + +The list will then be checked to make sure that each change is one that +is allowed to be made via the web interface. + ### PageSpec plugins It's also possible to write plugins that add new functions to @@ -847,3 +909,82 @@ to a hash containing all the config items. They should also implement a By the way, to parse a ikiwiki setup file and populate `%config`, a program just needs to do something like: `use IkiWiki::Setup; IkiWiki::Setup::load($filename)` + +### Function overriding + +Sometimes using ikiwiki's pre-defined hooks is not enough. Your plugin +may need to replace one of ikiwiki's own functions with a modified version, +or wrap one of the functions. + +For example, your plugin might want to override `displaytime`, to change +the html markup used when displaying a date. Or it might want to override +`IkiWiki::formattime`, to change how a date is formatted. Or perhaps you +want to override `bestlink` and change how ikiwiki deals with [[WikiLinks|ikiwiki/WikiLink]]. + +By venturing into this territory, your plugin is becoming tightly tied to +ikiwiki's internals. And it might break if those internals change. But +don't let that stop you, if you're brave. + +Ikiwiki provides an `inject()` function, that is a powerful way to replace +any function with one of your own. This even allows you to inject a +replacement for an exported function, like `bestlink`. Everything that +imports that function will get your version instead. Pass it the name of +the function to replace, and a new function to call. + +For example, here's how to replace `displaytime` with a version using HTML 5 +markup: + + inject(name => 'IkiWiki::displaytime', call => sub { + return "<time>".formattime(@_)."</time>"; + }); + +Here's how to wrap `bestlink` with a version that tries to handle +plural words: + + my $origbestlink=\&bestlink; + inject(name => 'IkiWiki::bestlink', call => \&mybestlink); + + sub deplural ($) { + my $word=shift; + $word =~ s/e?s$//; # just an example :-) + return $word; + } + + sub mybestlink ($$) { + my $page=shift; + my $link=shift; + my $ret=$origbestlink->($page, $link); + if (! length $ret) { + $ret=$origbestlink->($page, deplural($link)); + } + return $ret; + } + +### Javascript + +Some plugins use javascript to make ikiwiki look a bit more web-2.0-ish. + +All javascript code should be put in `.js` files in the `javascript` +underlay, and plugins using those files can enable use of the underlay by +calling `add_underlay("javascript");` in their `import` function. + +You'll have to arrange for `<script>` tags to be added to the pages that +use your javascript. This can be done using a `format` hook. + +Ikiwiki provides some utility functions in `ikiwiki.js`, for use by other +javascript code. These include: + +#### `getElementsByClass(cls, node, tag)` + +Returns an array of elements with the given class. The node and tag are +optional and define what document node and element names to search. + +#### `hook(name, call)` + +The function `call` will be run as part of the hook named `name`. + +Note that to hook into `window.onload`, you can use the `onload' hook. + +#### `run_hooks(name)` + +Runs the hooks with the specified name. diff --git a/doc/plugins/write/discussion.mdwn b/doc/plugins/write/discussion.mdwn index 039775b79..24a556ffe 100644 --- a/doc/plugins/write/discussion.mdwn +++ b/doc/plugins/write/discussion.mdwn @@ -40,3 +40,7 @@ distributed wiki. > > OTOH, if something can be added to the documentation that encourages > good behavior, that'd be a good thing ... --[[Joey]] + +--- + +I would find this page clearer split up into sub-pages. Does anyone agree/disagree? -- [[users/Jon]] diff --git a/doc/plugins/write/external.mdwn b/doc/plugins/write/external.mdwn index 272f74a7c..e30bf2ff3 100644 --- a/doc/plugins/write/external.mdwn +++ b/doc/plugins/write/external.mdwn @@ -96,14 +96,13 @@ the sentinal. ## Function injection -Some parts of ikiwiki are extensible by adding functions. For example, the -RCS interface relies on plugins providing several IkiWiki::rcs_* functions. +Some parts of ikiwiki are extensible by adding or overriding functions. It's actually possible to do this from an external plugin too. -To make your external plugin provide an `IkiWiki::rcs_update` function, for +To make your external plugin override the `IkiWiki::formattime` function, for example, make an RPC call to `inject`. Pass it named parameters "name" and "call", where "name" is the name of the function to inject into perl (here -"Ikiwiki::rcs_update" and "call" is the RPC call ikiwiki will make whenever +"Ikiwiki::formattime" and "call" is the RPC call ikiwiki will make whenever that function is run. If the RPC call is memoizable, you can also pass a "memoize" parameter, set diff --git a/doc/plugins/write/tutorial.mdwn b/doc/plugins/write/tutorial.mdwn index e1b34b800..5345f71f2 100644 --- a/doc/plugins/write/tutorial.mdwn +++ b/doc/plugins/write/tutorial.mdwn @@ -27,7 +27,7 @@ important one is the IkiWiki module. use warnings; use strict; - use IkiWiki 2.00; + use IkiWiki 3.00; Ok, boilerplate is out of the way. Now to add the one function that ikiwiki expects to find in any module: `import`. The import function is called when |