* Add no_override parameter to hook().

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index a78785e0286b900afbf97bc1a583d7789c1bc96a..1beafa3952f37d44b2e853e25fff6c21471bece5 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -105,13 +105,13 @@ return the htmlized content.
 
        hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
 
-Each time a page (or part of a blog page, or an rss feed) is rendered, a
-[[template|templates]] is filled out. This hook allows modifying that
-template. The function is passed named parameters. The "page" and
-"destpage" parameters are the same as for a preprocess hook. The "template"
-parameter is a `HTML::Template` object that is the template that will be
-used to generate the page. The function can manipulate that template
-object.
+[[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 `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
 a new custom parameter to the template.
@@ -197,15 +197,24 @@ use the following hashes, using a page name as the key:
 
 * `%links` lists the names of each page that a page links to, in an array
   reference.
-* `%renderedfiles` contains the name of the file rendered by a page.
+* `%renderedfiles` lists names of the files rendered by a page, in an array
+  reference.
 * `%pagesources` contains the name of the source file for a page.
 
+Also, the %IkiWiki::version variable contains the version number for the
+ikiwiki program.
+
 ### Library functions
 
 #### `hook(@)`
 
 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
+will not override any existing hook with the same id. This is useful if
+the id can be controled by the user.
+
 #### `debug($)`
 
 Logs a debugging message. These are supressed unless verbose mode is turned
@@ -293,6 +302,13 @@ 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($$)`
+
+Given a page name and a destination file name (not including the base
+destination directory), register that the page will result in that file
+being rendered. It's important to call this before writing to any file in
+the destination directory.
+
 #### `pagetype($)`
 
 Given the name of a source file, returns the type of page it is, if it's