Merge commit 'origin/master' into prv/po

17 files changed, 198 insertions, 18 deletions

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/calendar/discussion.mdwn b/doc/plugins/calendar/discussion.mdwn
index 65c2459c6..148b83522 100644
--- a/doc/plugins/calendar/discussion.mdwn
+++ b/doc/plugins/calendar/discussion.mdwn
@@ -1,2 +1,4 @@
 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]]
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..3efc68418 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
@@ -27,7 +27,7 @@ Somewhat more detailed usage documentation would be appreciated. I tried to setu
 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/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..f60b8fbea
--- /dev/null
+++ b/doc/plugins/contrib/po.mdwn
@@ -0,0 +1,63 @@
+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](http://repo.or.cz/w/ikiwiki/intrigeri.git?a=shortlog;h=refs/heads/po): `git clone git://repo.or.cz/ikiwiki/intrigeri.git`
+* It involves adding three hooks to ikiwiki core.
+* 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]]
+>>
+>> 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]]
diff --git a/doc/plugins/contrib/sourcehighlight.mdwn b/doc/plugins/contrib/sourcehighlight.mdwn
index 2eb22e6ed..fb368945b 100644
--- a/doc/plugins/contrib/sourcehighlight.mdwn
+++ b/doc/plugins/contrib/sourcehighlight.mdwn
@@ -20,3 +20,8 @@ This problem with sourcehighlight needs to be fixed before it is very useful.
 - 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]]
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/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/relativedate.mdwn b/doc/plugins/relativedate.mdwn
index 121bce477..32f8c798b 100644
--- a/doc/plugins/relativedate.mdwn
+++ b/doc/plugins/relativedate.mdwn
@@ -10,7 +10,7 @@ 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 "date" class. For example, this will
-display as a relative date:
+wiki, by using html elements in the "relativedate" class. For example, this
+will display as a relative date:
 
-	<span class="date">Fri Oct 17 18:36:13 EDT 2008</span>
+	<span class="relativedate">Fri Oct 17 18:36:13 EDT 2008</span>
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/write.mdwn b/doc/plugins/write.mdwn
index 857d176d5..f147b0766 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -360,13 +360,6 @@ This hook is called whenever ikiwiki normally saves its state, just before
 the state is saved. The function can save other state, modify values before
 they're saved, etc.
 
-### displaytime
-
-	hook(type => "displaytime", id => "foo", call => \&display);
-
-This hook can be registered to override the regular `displaytime` function.
-Only the last displaytime hook will be used.
-
 ### renamepage
 
 	hook(type => "renamepage", id => "foo", call => \&renamepage);
@@ -857,6 +850,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
@@ -884,6 +901,56 @@ 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.
+
+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.
diff --git a/doc/plugins/write/discussion.mdwn b/doc/plugins/write/discussion.mdwn
index 039775b79..9a36d7b0b 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? -- [[JonDowland]]
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