* Add a destpage parameter to the filter hook.

[ikiwiki.git] / doc / plugins / write.mdwn

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index ef9d412e5081070eb65aba70f316ce95414068e1..6593ab018573db50e7f275263e12ba3a824312f9 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -32,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.
@@ -68,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
 
@@ -104,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
@@ -328,10 +329,6 @@ 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.
 
-If the PageSpec fails to match, it may return a IkiWiki::FailReason object,
-which evaluates to false in a boolean context, but in a string context,
-evaulates to the reason the PageSpec failed to match.
-
 #### `bestlink($$)`
 
 Given a page and the text of a link on the page, determine which
@@ -452,5 +449,5 @@ IkiWiki::PageSpec package, that is named `match_foo`, where "foo()" is
 how it will be accessed in a [[PageSpec]]. The function will be passed
 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
-true if the match succeeds, and either false or a IkiWiki::FailReason object
-if the match fails.
+a IkiWiki::SuccessReason object if the match succeeds, or an
+IkiWiki::FailReason object if the match fails.