X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/06b955b84a0abec6d6baae9eb295793574cb76d7..a4b3300fde7a9e5695debcd4ee90cf173ef372d1:/doc/plugins/write.mdwn

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 4dd057074..870b3c451 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -20,6 +20,8 @@ being edited.
 ## Registering plugins
 
 All 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`
 
 Plugins should, when imported, call `hook()` to hook into ikiwiki's
 processing. The function uses named parameters, and use varies depending on
@@ -30,12 +32,6 @@ hook, a "id" paramter, which should be a unique string for this plugin, and
 a "call" parameter, which is a reference to a function to call for the
 hook.
 
-An optional "scan" parameter, if set to a true value, makes the hook be
-called during the preliminary scan that ikiwiki makes of updated pages,
-before begining to render pages. This parameter should be set to true if
-the hook modifies data in `%links`. Note that doing so will make the hook
-be run twice per page build, so avoid doing it for expensive hooks.
-
 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.
@@ -66,21 +62,22 @@ configuration. It's called early in the startup process. The
 function is passed no values. It's ok for the function to call
 `error()` if something isn't configured right.
 
-### filter
+### needsbuild
 
-	hook(type => "filter", id => "foo", call => \&filter);
+	hook(type => "needsbuild", id => "foo", call => \&needsbuild);
 
-Runs on the raw source of a page, before anything else touches it, and can
-make arbitrary changes. The function is passed named parameters `page` and
-`content` and should return the filtered content.
+This allows a plugin the manipulate the list of files that need to be
+built when the wiki is refreshed. The function is passed a reference to an
+array of pages that will be rebuilt, and can modify the array, either
+adding or removing files from it.
 
-### scan
+### filter
 
-	hook(type => "scan", id => "foo", call => \&scan);
+	hook(type => "filter", id => "foo", call => \&filter);
 
-This is identical to a preprocess hook (see below), except that it is
-called in the initial pass that scans pages for data that will be used in
-later passes. Scan hooks are the only hook that should modify `%links`.
+Runs on the raw source of a page, before anything else touches it, and can
+make arbitrary changes. The function is passed named parameters "page",
+"destpage", and "content". It should return the filtered content.
 
 ### preprocess
 
@@ -102,6 +99,12 @@ parameters included in the directive are included as named parameters as
 well. Whatever the function returns goes onto the page in place of the
 directive.
 
+An optional "scan" parameter, if set to a true value, makes the hook be
+called during the preliminary scan that ikiwiki makes of updated pages,
+before begining to render pages. This parameter should be set to true if
+the hook modifies data in `%links`. Note that doing so will make the hook
+be run twice per page build, so avoid doing it for expensive hooks.
+
 Note that if the [[htmlscrubber]] is enabled, html in
 [[PreProcessorDirective]] output is sanitised, which may limit what your
 plugin can do. Also, the rest of the page content is not in html format at
@@ -133,7 +136,7 @@ preprocess hook. The "template" parameter is a [[cpan HTML::Template]]
 object that is the template that will be used to generate the page. The
 function can manipulate that template object.
 
-The most common thing to do is probably to call $template->param() to add
+The most common thing to do is probably to call `$template->param()` to add
 a new custom parameter to the template.
 
 ### sanitize
@@ -178,7 +181,7 @@ source files that were rendered.
 
 Use this to hook into ikiwiki's cgi script. Each registered cgi hook is
 called in turn, and passed a CGI object. The hook should examine the
-parameters, and if it will handle this CGI request, output a page and
+parameters, and if it will handle this CGI request, output a page (including the http headers) and
 terminate the program.
 
 ### auth
@@ -280,7 +283,7 @@ ikiwiki program.
 Hook into ikiwiki's processing. See the discussion of hooks above.
 
 Note that in addition to the named parameters described above, a parameter
-named no_override is supported, If it's set to a true value, then this hook
+named `no_override` is supported, If it's set to a true value, then this hook
 will not override any existing hook with the same id. This is useful if
 the id can be controled by the user.
 
@@ -305,7 +308,7 @@ appear on the wiki page, rather than calling error().
 
 Creates and returns a [[cpan HTML::Template]] object. The first parameter
 is the name of the file in the template directory. The optional remaining
-parameters are passed to HTML::Template->new.
+parameters are passed to `HTML::Template->new`.
 
 #### `htmlpage($)`
 
@@ -316,12 +319,15 @@ page created from it. (Ie, it appends ".html".)
 
 Makes the specified page depend on the specified [[PageSpec]].
 
-#### `pagespec_match($$;$)`
+#### `pagespec_match($$;@)`
+
+Passed a page name, and [[PageSpec]], returns true if the [[PageSpec]]
+matches the page.
 
-Passed a page name, a [[PageSpec]], and the location the [[PageSpec]] should
-be matched against, returns true if the [[PageSpec]] matches the page. (If
-the third parameter is not passed, relative PageSpecs will match relative to
-the top of the wiki.)
+Additional named parameters can be passed, to further limit the match.
+The most often used is "location", which specifies the location the
+PageSpec should match against. If not passed, relative PageSpecs will match
+relative to the top of the wiki.
 
 #### `bestlink($$)`
 
@@ -383,7 +389,7 @@ 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.
 
-### `will_render($$)`
+#### `will_render($$)`
 
 Given a page name and a destination file name (not including the base
 destination directory), register that the page will result in that file
@@ -416,7 +422,9 @@ This is the standard gettext function, although slightly optimised.
 
 #### `urlto($$)`
 
-Construct a relative url to the first parameter from the second.
+Construct a relative url to the first parameter from the page named by the
+second. The first parameter can be either a page name, or some other
+destination file, as registered by `will_render`.
 
 #### `targetpage($$)`
 
@@ -429,9 +437,9 @@ ikiwiki's support for revision control systems also uses pluggable perl
 modules. These are in the `IkiWiki::RCS` namespace, for example
 `IkiWiki::RCS::svn`. 
 
-Each RCS plugin must support all the IkiWiki::rcs\_* functions.
+Each RCS plugin must support all the `IkiWiki::rcs_*` functions.
 See IkiWiki::RCS::Stub for the full list of functions. It's ok if
-rcs\_getctime does nothing except for throwing an error.
+`rcs_getctime` does nothing except for throwing an error.
 
 See [[about_RCS_backends]] for some more info.
 
@@ -441,6 +449,7 @@ It's also possible to write plugins that add new functions to
 [[PageSpecs|PageSpec]]. Such a plugin should add a function to the
 IkiWiki::PageSpec package, that is named `match_foo`, where "foo()" is
 how it will be accessed in a [[PageSpec]]. The function will be passed
-three parameters: The name of the page being matched, the thing to match
-against, and the page that the matching is occuring on. It should return
-true if the page matches.
+two parameters: The name of the page being matched, and the thing to match
+against. It may also be passed additional, named parameters. It should return
+a IkiWiki::SuccessReason object if the match succeeds, or an
+IkiWiki::FailReason object if the match fails.