response

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

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


@@ -135,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.
 
 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
 a new custom parameter to the template.
 
 ### sanitize


@@ -282,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
 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.
 
 will not override any existing hook with the same id. This is useful if
 the id can be controled by the user.
 


@@ -307,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
 
 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($)`
 
 
 #### `htmlpage($)`
 


@@ -434,9 +435,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`. 
 
 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
 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.
 
 
 See [[about_RCS_backends]] for some more info.
 


@@ -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.