X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/2c0d0109d8593dc20c1493e492d15ed225fae563..2d357696064233444a5777f787a3741dd85faae6:/doc/plugins/write.mdwn

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 8b0cdfdaa..a122845af 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -62,13 +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.
 
+### needsbuild
+
+	hook(type => "needsbuild", id => "foo", call => \&needsbuild);
+
+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.
+
 ### filter
 
 	hook(type => "filter", id => "foo", call => \&filter);
 
 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.
+make arbitrary changes. The function is passed named parameters "page",
+"destpage", and "content". It should return the filtered content.
 
 ### preprocess
 
@@ -119,17 +128,28 @@ return the htmlized content.
 
 	hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
 
-[[Templates]] are filled out for many different things in ikiwiki, like
-generating a page, or part of a blog page, or an rss feed, or a cgi. This
-hook allows modifying those templates. The function is passed named
-parameters. The "page" and "destpage" parameters are the same as for a
-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.
+[[Templates|wikitemplate]] are filled out for many different things in
+ikiwiki, like generating a page, or part of a blog page, or an rss feed, or
+a cgi. This hook allows modifying the variables available on those
+templates. The function is passed named parameters. The "page" and
+"destpage" parameters are the same as for a 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.
 
+### templatefile
+
+	hook(type => "templatefile", id => "foo", call => \&templatefile);
+
+This hook allows plugins to change the [[template|wikitemplate]] that is
+used for a page in the wiki. The hook is passed a "page" parameter, and
+should return the name of the template file to use, or undef if it doesn't
+want to change the default ("page.tmpl"). Template files are looked for in
+/usr/share/ikiwiki/templates by default.
+
 ### sanitize
 
 	hook(type => "sanitize", id => "foo", call => \&sanitize);
@@ -172,7 +192,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
@@ -274,7 +294,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.
 
@@ -299,7 +319,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($)`
 
@@ -380,7 +400,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
@@ -413,7 +433,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($$)`
 
@@ -426,9 +448,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.