convert rcs_revert to only stage the reversion

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 15ed08d82b698baece572f1e845e13fe1808bc35..dbbe83851c0c5efbb2022d50b7b70e6d9798151a 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -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,11 +203,9 @@ 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",
-"destpage", "content" and "fullpage". "fullpage" is a true value if,
-and only if, a full page's content is being filtered, e.g. as opposed
-to a directive parameter. It should return the filtered content.
+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
 
 
 ### preprocess
 


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


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


@@ -1161,9 +1176,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


@@ -1176,6 +1191,25 @@ 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.
+

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