response

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index d9f25641d9d1ae82e888543902e5d61d91293a96..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.
 
 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.
 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.
 
 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
 
 
 ### 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.
 
 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
 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


@@ -448,4 +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
 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 page matches.
+a IkiWiki::SuccessReason object if the match succeeds, or an
+IkiWiki::FailReason object if the match fails.