web commit by joey

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index c4f668373024d2a18fce28ed264c4c412e8e89a9..db1badb7c4efec5b759f4f0b549a5d88342f8c42 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -17,21 +17,45 @@ being edited.
 
 ## Registering plugins
 
-Plugins should, when imported, call IkiWiki::register_plugin to hook into
-ikiwiki. The function takes four parameters:
-
-1. A method type. Use "preprocess" to register a [[PreProcessorDirective]]
-2. A command name. This is the bit that will appear inside brackets in a
-   page.
-3. A reference to a subroutine that is run when the plugin is used.
+Plugins should, when imported, call IkiWiki::hook to hook into
+ikiwiki's processing. The function uses named parameters, and use varies depending on the type of plugin being registered. Note that a plugin can call the function more than once to register multiple hooks. All calls to IkiWiki::hook should be passed a "type" parameter, which gives the type of 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.
 
 ## Writing a [[PreProcessorDirective]]
 
-For preprocessor directives, the subroutine is passed named parameters. A
+This is probably the most common use of a plugin.
+
+        IkiWiki::hook(type => "preprocess", id => "foo", call => \&preprocess);
+
+Replace "foo" with the command name that will be used inside brackers for 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. All parameters included in the directive are included
-as named parameters as well. Whatever the subroutine returns goes onto the
+as named parameters as well. Whatever the function returns goes onto the
 page in place of the directive.
 
+## Other types of hooks
+
+Beyond PreProcessorDirectives, Other types of hooks that can be used by plugins include:
+
+### checkconfig
+
+        IkiWiki::hook(type => "delete", id => "foo", call => \&checkconfig);
+
+This is useful if the plugin needs to check for, or modify ikiwiki's configuration. It's called early in the ikiwiki startup process. It's ok for
+the function to call IkiWiki::error if something isn't configured right.
+
+### delete
+
+        IkiWiki::hook(type => "delete", id => "foo", call => \&dele);
+
+Each time a page or pages is removed from the wiki, the referenced function is called, and passed the names of the source files that were removed.
+
+### render
+
+        IkiWiki::hook(type => "render", id => "foo", call => \&render);
+
+Each time ikiwiki renders a change or addition (but not deletion) of a page to the wiki, the referenced function is called, and passed the name of the source file that was rendered.
+
 ## Error handing in plugins
 
 While a plugin can call ikiwiki's error routine for a fatal error, for
@@ -71,3 +95,13 @@ use the following hashes, using a page name as the key:
   Many plugins will need to add dependencies to this hash; the best way to do
   it is by using the IkiWiki::add_depends function, which takes as its
   parameters the page name and a [[GlobList]] of dependencies to add.
+
+## RCS plugins
+
+ikiwiki's support for revision control systems also uses pluggable perl
+modules. These are in the `IkiWiki::RCS` namespace, for example
+`IkiWiki::RCS::svn`. 
+
+Each RCS plugin must support all the IkiWiki::rcs_* functions.
+See IkiWiki::RCS::Stub for the full list of functions. It's ok if
+rcs_getctime does nothing except for throwing an error.