X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/9bae90024229618c1bfd320f1513d1054af89e5a..55aae671ad28ea75263125baea2468641583744d:/doc/plugins/write.mdwn?ds=sidebyside

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index a78785e02..7c4da8d5f 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -30,6 +30,12 @@ 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.
+
 ## Types of hooks
 
 In roughly the order they are called.
@@ -64,6 +70,14 @@ 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.
 
+### scan
+
+	hook(type => "scan", id => "foo", call => \&scan);
+
+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 
+
 ### preprocess
 
 Adding a [[PreProcessorDirective]] is probably the most common use of a
@@ -77,7 +91,7 @@ the preprocessor directive.
 Each time the directive is processed, the referenced function (`preprocess`
 in the example above) is called, and is passed named parameters. A "page"
 parameter gives the name of the page that embedded the preprocessor
-directive, while a "destpage" parameter gices the name of the page the
+directive, while a "destpage" parameter gives the name of the page the
 content is going to (different for inlined pages). All 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.
@@ -105,13 +119,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.
@@ -161,6 +175,19 @@ 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
 terminate the program.
 
+### cgi
+
+	hook(type => "cgi", id => "foo", call => \&auth);
+
+This hook can be used to implement a different authentication method than
+the standard web form. When a user needs to be authenticated, each registered
+auth hook is called in turn, and passed a CGI object and a session object. 
+
+If the hook is able to authenticate the user, it should set the session
+object's "name" parameter to the authenticated user's name. Note that
+if the name is set to the name of a user who is not registered,
+a basic registration of the user will be automatically performed.
+
 ### savestate
 
 	hook(type => "savestate", id => "foo", call => \&savestate);
@@ -197,15 +224,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 +329,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