Only unlink excess recentchanges from srcdir if not in transientdir

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 1930055658b93a245cecff2cf5114fe882a065d5..f0f79ebc7faf58013847674e5855e7a64ab0888d 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -1,4 +1,4 @@
-Ikiwiki's plugin interface allows all kinds of useful [[plugins]] to be
+lkiwiki's plugin interface allows all kinds of useful [[plugins]] to be

 written to extend ikiwiki in many ways. Despite the length of this page,
 it's not really hard. This page is a complete reference to everything a
 plugin might want to do. There is also a quick [[tutorial]].
 written to extend ikiwiki in many ways. Despite the length of this page,
 it's not really hard. This page is a complete reference to everything a
 plugin might want to do. There is also a quick [[tutorial]].


@@ -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


@@ -595,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
 


@@ -725,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


@@ -965,14 +982,22 @@ This is the standard gettext function, although slightly optimised.
 
 This is the standard ngettext function, although slightly optimised.
 
 
 This is the standard ngettext function, although slightly optimised.
 

-### `urlto($$;$)`
+### `urlto($;$$)`

 
 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`.
 
 
 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`.
 

-If the third parameter is passed and is true, an absolute url will be
-constructed instead of the default relative url.
+Provide a second parameter whenever possible, since this leads to better
+behaviour for the [[plugins/po]] plugin and `file:///` URLs.
+
+If the second parameter is not specified (or `undef`), the URL will be
+valid from any page on the wiki, or from the CGI; if possible it'll
+be a path starting with `/`, but an absolute URL will be used if
+the wiki and the CGI are on different domains.
+
+If the third parameter is passed and is true, the url will be a fully
+absolute url. This is useful when generating an url to publish elsewhere.

 
 ### `newpagefile($$)`
 
 
 ### `newpagefile($$)`
 


@@ -1051,16 +1076,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`.


@@ -1103,7 +1132,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 => [


@@ -1120,19 +1151,19 @@ The data structure returned for each change is:
                ],
        }
 
                ],
        }
 

-#### `rcs_diff($)`
+#### `rcs_diff($;$)`
+
+The first parameter is the rev from `rcs_recentchanges`.
+The optional second parameter is how many lines to return (default: all).

 
 

-The parameter is the rev from `rcs_recentchanges`.

 Should return a list of lines of the diff (including \n) in list
 Should return a list of lines of the diff (including \n) in list

-context, and the whole diff in scalar context.
+context, and a string containing the whole diff in scalar context.

 
 #### `rcs_getctime($)`
 
 This is used to get the page creation time for a file from the RCS, by looking
 it up in the history.
 
 
 #### `rcs_getctime($)`
 
 This is used to get the page creation time for a file from the RCS, by looking
 it up in the history.
 

-It's ok if this is not implemented, and throws an error.
-

 If the RCS cannot determine a ctime for the file, return 0.
 
 #### `rcs_getmtime($)`
 If the RCS cannot determine a ctime for the file, return 0.
 
 #### `rcs_getmtime($)`


@@ -1153,9 +1184,9 @@ sense to implement for all RCSs.
 
 It should examine the incoming changes, and do any sanity 
 checks that are appropriate for the RCS to limit changes to safe file adds,
 
 It should examine the incoming changes, and do any sanity 
 checks that are appropriate for the RCS to limit changes to safe file adds,

-removes, and changes. If something bad is found, it should exit
-nonzero, to abort the push. Otherwise, it should return a list of
-files that were changed, in the form:
+removes, and changes. If something bad is found, it should die, to abort
+the push. Otherwise, it should return a list of files that were changed,
+in the form:

 
        {
                file => # name of file that was changed
 
        {
                file => # name of file that was changed


@@ -1168,6 +1199,28 @@ files that were changed, in the form:
 The list will then be checked to make sure that each change is one that
 is allowed to be made via the web interface.
 
 The list will then be checked to make sure that each change is one that
 is allowed to be made via the web interface.
 

+#### `rcs_preprevert($)`
+
+This is called by the revert web interface. It is passed a RCS-specific
+change ID, and should determine what the effects would be of reverting
+that change, and return the same data structure as `rcs_receive`.
+
+Like `rcs_receive`, it should do whatever sanity checks are appropriate
+for the RCS to limit changes to safe changes, and die if a change would
+be unsafe to revert.
+
+#### `rcs_revert($)`
+
+This is called by the revert web interface. It is passed a named
+parameter rev that is the RCS-specific change ID to revert.
+
+It should try to revert the specified rev, and leave the reversion staged
+so `rcs_commit_staged` will complete it. It should return undef on _success_
+and an error message on failure.
+
+This hook and `rcs_preprevert` are optional, if not implemented, no revert
+web interface will be available.
+

 ### PageSpec plugins
 
 It's also possible to write plugins that add new functions to
 ### PageSpec plugins
 
 It's also possible to write plugins that add new functions to