inline already supports raw files though

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 5e7042c3b5d22c9a90a0c63a02a7d8b1615f81d2..d5bd1dd7648bf867b3dfe1f3a21f71038e40ee83 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -39,7 +39,7 @@ built.
 Now that it knows what pages it needs to build, ikiwiki runs two
 compile passes. First, it runs `scan` hooks, which collect metadata about
 the pages. Then it runs a page rendering pipeline, by calling in turn these
 Now that it knows what pages it needs to build, ikiwiki runs two
 compile passes. First, it runs `scan` hooks, which collect metadata about
 the pages. Then it runs a page rendering pipeline, by calling in turn these

-hooks: `filter`, `preprocess`, `linkify`, `htmlize`, `postscan`,
+hooks: `filter`, `preprocess`, `linkify`, `htmlize`, `indexhtml`,

 `pagetemplate`, `sanitize`, `format`.
 
 After all necessary pages are built, it calls the `change` hook. Finally,
 `pagetemplate`, `sanitize`, `format`.
 
 After all necessary pages are built, it calls the `change` hook. Finally,


@@ -177,10 +177,15 @@ function is passed no values.
 
        hook(type => "needsbuild", id => "foo", call => \&needsbuild);
 
 
        hook(type => "needsbuild", id => "foo", call => \&needsbuild);
 

-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.
+This allows a plugin to observe or even manipulate the list of files that
+need to be built when the wiki is refreshed. 
+
+As its first parameter, the function is passed a reference to an array of
+files that will be built. It should return an array reference that is a
+modified version of its input. It can add or remove files from it.
+
+The second parameter passed to the function is a reference to an array of
+files that have been deleted.

 
 ### scan
 
 
 ### scan
 


@@ -198,8 +203,8 @@ value is ignored.
 
        hook(type => "filter", id => "foo", call => \&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",
+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
 "destpage", and "content". It should return the filtered content.
 
 ### preprocess


@@ -282,16 +287,16 @@ like `Makefile` that have no extension.
 If `hook` is passed an optional "longname" parameter, this value is used
 when prompting a user to choose a page type on the edit page form.
 
 If `hook` is passed an optional "longname" parameter, this value is used
 when prompting a user to choose a page type on the edit page form.
 

-### postscan
+### indexhtml

 
 

-       hook(type => "postscan", id => "foo", call => \&postscan);
+       hook(type => "indexhtml", id => "foo", call => \&indexhtml);

 
 This hook is called once the page has been converted to html (but before
 the generated html is put in a template). The most common use is to
 update search indexes. Added in ikiwiki 2.54.
 
 
 This hook is called once the page has been converted to html (but before
 the generated html is put in a template). The most common use is to
 update search indexes. Added in ikiwiki 2.54.
 

-The function is passed named parameters "page" and "content". Its return
-value is ignored.
+The function is passed named parameters "page", "destpage", and "content".
+Its return value is ignored.

 
 ### pagetemplate
 
 
 ### pagetemplate
 


@@ -319,6 +324,15 @@ should return the name of the template file to use (relative to the
 template directory), or undef if it doesn't want to change the default
 ("page.tmpl").
 
 template directory), or undef if it doesn't want to change the default
 ("page.tmpl").
 

+### pageactions
+
+       hook(type => "pageactions", id => "foo", call => \&pageactions);
+
+This hook allows plugins to add arbitrary actions to the action bar on a
+page (next to Edit, RecentChanges, etc). The hook is passed a "page"
+parameter, and can return a list of html fragments to add to the action
+bar.
+

 ### sanitize
 
        hook(type => "sanitize", id => "foo", call => \&sanitize);
 ### sanitize
 
        hook(type => "sanitize", id => "foo", call => \&sanitize);


@@ -586,7 +600,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`
        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
 
 
 ## Exported variables
 


@@ -716,6 +740,8 @@ with no ".tmpl" extension. Template pages are normally looked for in
 the templates/ directory. If the page name starts with "/", a page
 elsewhere in the wiki can be used.
 
 the templates/ directory. If the page name starts with "/", a page
 elsewhere in the wiki can be used.
 

+If the template is not found, or contains a syntax error, an error is thrown.
+

 ### `template_depends($$;@)`
 
 Use this instead of `template()` if the content of a template is being
 ### `template_depends($$;@)`
 
 Use this instead of `template()` if the content of a template is being


@@ -1042,16 +1068,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.
 
 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.
 
 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`.
 
 Changes can be staged by calls to `rcs_add`, `rcs_remove`, and
 `rcs_rename`.


@@ -1094,7 +1124,9 @@ The data structure returned for each change is:
 
        {
                rev => # the RCSs id for this commit
 
        {
                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 => [
                committype => # either "web" or the name of the rcs,
                when => # time when the change was made,
                message => [