needsbuild hook interface changed; the hooks should now return the modified array...

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 1930055658b93a245cecff2cf5114fe882a065d5..31bb64e68a258eccf046e0900f36fecd15c66034 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -179,8 +179,8 @@ function is passed no values.
 
 This allows a plugin to 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 files that will be rebuilt, and can modify the array, either
-adding or removing files from it.
+array of files that will be rebuilt. It should return an array reference
+that is a modified version of its input. It can add or remove files from it.
 
 ### scan
 
@@ -198,8 +198,8 @@ value is ignored.
 
        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",
+Runs on the full 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
@@ -595,7 +595,17 @@ describes the plugin as a whole. For example:
        hook(type => "genwrapper", id => "foo", call => \&genwrapper);
 
 This hook is used to inject C code (which it returns) into the `main`
-function of the ikiwiki wrapper when it is being generated.
+function of the ikiwiki wrapper when it is being generated. 
+
+The code runs before anything else -- in particular it runs before
+the suid wrapper has sanitized its environment.
+
+### disable
+
+       hook(type => "disable", id => "foo", call => \&disable);
+
+This hook is only run when a previously enabled plugin gets disabled
+during ikiwiki setup. Plugins can use this to perform cleanups.
 
 ## Exported variables
 
@@ -1051,16 +1061,20 @@ token, that will be passed into `rcs_commit` when committing. For example,
 it might return the current revision ID of the file, and use that
 information later when merging changes.
 
-#### `rcs_commit($$$;$$)`
+#### `rcs_commit(@)`
+
+Passed named parameters: `file`, `message`, `token` (from `rcs_prepedit`),
+and `session` (optional).
 
-Passed a file, message, token (from `rcs_prepedit`), user, and ip address.
 Should try to commit the file. Returns `undef` on *success* and a version
 of the page with the rcs's conflict markers on failure.
 
-#### `rcs_commit_staged($$$)`
+#### `rcs_commit_staged(@)`
+
+Passed named parameters: `message`, and `session` (optional).
 
-Passed a message, user, and ip address. Should commit all staged changes.
-Returns undef on success, and an error message on failure.
+Should commit all staged changes. Returns undef on success, and an
+error message on failure.
 
 Changes can be staged by calls to `rcs_add`, `rcs_remove`, and
 `rcs_rename`.
@@ -1103,7 +1117,9 @@ The data structure returned for each change is:
 
        {
                rev => # the RCSs id for this commit
-               user => # name of user who made the change,
+               user => # user who made the change (may be an openid),
+               nickname => # short name for user (optional; not an openid),
+               
                committype => # either "web" or the name of the rcs,
                when => # time when the change was made,
                message => [