X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/6551c1e5609967c0c7f947fa0e9d85d24e454d37..3d82d47e1896b8e64c1e22b09a05968fc481aebf:/doc/plugins/write.mdwn?ds=inline

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 5be90efdf..686f7e518 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -1,10 +1,37 @@
-ikiwiki [[plugins]] are written in perl. Each plugin is a perl module, in
-the `IkiWiki::Plugin` namespace. The name of the plugin is typically in
-lowercase, such as `IkiWiki::Plugin::inline`. Ikiwiki includes a
-`IkiWiki::Plugin::skeleton` that can be fleshed out to make a useful
-plugin. `IkiWiki::Plugin::pagecount` is another simple example.
+Ikiwiki'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]].
 
-# Note
+[[!toc levels=2]]
+
+## Types of plugins
+
+Most ikiwiki [[plugins]] are written in perl, like ikiwiki. This gives the
+plugin full access to ikiwiki's internals, and is the most efficient.
+However, plugins can actually be written in any language that supports XML
+RPC. These are called [[external]] plugins.
+
+A plugin written in perl is a perl module, in the `IkiWiki::Plugin`
+namespace. The name of the plugin is typically in lowercase, such as
+`IkiWiki::Plugin::inline`. Ikiwiki includes a `IkiWiki::Plugin::skeleton`
+that can be fleshed out to make a useful plugin.
+`IkiWiki::Plugin::pagecount` is another simple example. All perl plugins
+should `use IkiWiki` to import the ikiwiki plugin interface. It's a good
+idea to include the version number of the plugin interface that your plugin
+expects: `use IkiWiki 2.00`.
+
+An external plugin is an executable program. It can be written in any
+language. Its interface to ikiwiki is via XML RPC, which it reads from
+ikiwiki on its standard input, and writes to ikiwiki on its standard
+output. For more details on writing external plugins, see [[external]].
+
+Despite these two types of plugins having such different interfaces,
+they're the same as far as how they hook into ikiwiki. This document will
+explain how to write both sorts of plugins, albeit with an emphasis on perl
+plugins.
+
+## Considerations
 
 One thing to keep in mind when writing a plugin is that ikiwiki is a wiki
 *compiler*. So plugins influence pages when they are built, not when they
@@ -15,158 +42,651 @@ random or changing thing on a page will generate a static page that won't
 change until ikiwiki rebuilds the page for some other reason, like the page
 being edited.
 
-# Registering plugins
+## Registering plugins
 
-Plugins should, when imported, call IkiWiki::hook to hook into ikiwiki's
+Plugins should, when imported, call `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
+the type of hook being registered -- see below. A plugin can call
+the function more than once to register multiple hooks.
+
+All calls to `hook()` should be passed a "type" parameter, which gives the
+type of hook, a "id" parameter, which should be a unique string for this
+plugin, and a "call" parameter, which tells what function to call for the
 hook.
 
-# Writing a [[PreProcessorDirective]]
+An optional "last" parameter, if set to a true value, makes the hook run
+after all other hooks of its type. Useful if the hook depends on some other
+hook being run first.
 
-This is probably the most common use of a plugin.
+## Types of hooks
 
-        IkiWiki::hook(type => "preprocess", id => "foo", call => \&preprocess);
+In roughly the order they are called.
 
-Replace "foo" with the command name that will be used inside brackers for
-the preprocessor directive.
+### getopt
 
-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 function returns goes onto the page in
-place of the directive.
+	hook(type => "getopt", id => "foo", call => \&getopt);
 
-## Error handing
+This allows for plugins to perform their own processing of command-line
+options and so add options to the ikiwiki command line. It's called during
+command line processing, with @ARGV full of any options that ikiwiki was
+not able to process on its own. The function should process any options it
+can, removing them from @ARGV, and probably recording the configuration
+settings in %config. It should take care not to abort if it sees
+an option it cannot process, and should just skip over those options and
+leave them in @ARGV.
 
-While a plugin can call ikiwiki's error routine for a fatal error, for
-errors that aren't intended to halt the entire wiki build, including bad
-parameters passed to a [[PreProcessorDirective]], etc, it's better to just
-return the error message as the output of the plugin.
+### checkconfig
 
-## Html issues
+	hook(type => "checkconfig", id => "foo", call => \&checkconfig);
 
-Note that if the [[htmlscrubber]] is enabled, html in
-[[PreProcessorDirective]] output is sanitised, which may limit what your
-plugin can do. Also, the rest of the page content is not in html format at
-preprocessor time. Text output by a preprocessor directive will be passed
-through markdown (or whatever engine is used to htmlize the page) along
-with the rest of the page.
+This is useful if the plugin needs to check for or modify ikiwiki's
+configuration. It's called early in the startup process. The
+function is passed no values. It's ok for the function to call
+`error()` if something isn't configured right.
 
-# Other types of hooks
+### refresh
 
-Beyond PreProcessorDirectives, Other types of hooks that can be used by
-plugins include:
+	hook(type => "refresh", id => "foo", call => \&refresh);
 
-## checkconfig
+This hook is called just before ikiwiki scans the wiki for changed files.
+It's useful for plugins that need to create or modify a source page. The
+function is passed no values.
 
-	IkiWiki::hook(type => "checkconfig", id => "foo", call => \&checkconfig);
+### needsbuild
 
-This is useful if the plugin needs to check for, or modify ikiwiki's
-configuration. It's called early in the ikiwiki startup process. The
-function is passed no values. It's ok for the function to call
-IkiWiki::error if something isn't configured right.
+	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 pages that will be rebuilt, and can modify the array, either
+adding or removing files from it.
+
+### scan
+
+	hook(type => "scan", id => "foo", call => \&scan);
 
-## filter
+This hook is called early in the process of building the wiki, and is used
+as a first pass scan of the page, to collect metadata about the page. It's
+mostly used to scan the page for WikiLinks, and add them to `%links`.
+Present in IkiWiki 2.40 and later.
 
-	IkiWiki::hook(type => "filter", id => "foo", call => \&filter);
+The function is passed named parameters "page" and "content". Its return
+value is ignored.
+
+### 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` and
-`content` and should return the filtered content.
+make arbitrary changes. The function is passed named parameters "page",
+"destpage", and "content". It should return the filtered content.
+
+### preprocess
 
-## htmlize
+Adding a [[ikiwiki/PreProcessorDirective]] is probably the most common use
+of a plugin.
 
-	IkiWiki::hook(type => "htmlize", id => "ext", call => \&filter);
+        hook(type => "preprocess", id => "foo", call => \&preprocess);
+
+Replace "foo" with the command name that will be used inside brackets for
+the preprocessor directive.
 
-Runs on the raw source of a page and turns it into html. The id parameter
+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, while a "destpage" parameter gives the name of the page the
+content is going to (different for inlined pages), and a "preview"
+parameter is set to a true value if the page is being previewed. All
+parameters included in the directive are included as named parameters as
+well. Whatever the function returns goes onto the page in place of the
+directive.
+
+An optional "scan" parameter, if set to a true value, makes the hook be
+called during the preliminary scan that ikiwiki makes of updated pages,
+before begining to render pages. This parameter should be set to true if
+the hook modifies data in `%links`. Note that doing so will make the hook
+be run twice per page build, so avoid doing it for expensive hooks. (As an
+optimisation, if your preprocessor hook is called in a void contets, you
+can assume it's being run in scan mode.)
+
+Note that if the [[htmlscrubber]] is enabled, html in
+[[ikiwiki/PreProcessorDirective]] output is sanitised, which may limit what
+your plugin can do. Also, the rest of the page content is not in html
+format at preprocessor time. Text output by a preprocessor directive will
+be linkified and passed through markdown (or whatever engine is used to
+htmlize the page) along with the rest of the page.
+
+### linkify
+
+	hook(type => "linkify", id => "foo", call => \&linkify);
+
+This hook is called to convert [[WikiLinks|WikiLink]] on the page into html
+links. The function is passed named parameters "page", "destpage", and
+"content". It should return the linkified content.  Present in IkiWiki 2.40
+and later.
+
+Plugins that implement linkify must also implement a scan hook, that scans
+for the links on the page and adds them to `%links`.
+
+### htmlize
+
+	hook(type => "htmlize", id => "ext", call => \&htmlize);
+
+Runs on the source of a page and turns it into html. The id parameter
 specifies the filename extension that a file must have to be htmlized using
 this plugin. This is how you can add support for new and exciting markup
 languages to ikiwiki.
 
-## pagetemplate
+The function is passed named parameters: "page" and "content" and should
+return the htmlized content.
+
+### pagetemplate
+
+	hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
+
+[[Templates|wikitemplates]] are filled out for many different things in
+ikiwiki, like generating a page, or part of a blog page, or an rss feed, or
+a cgi. This hook allows modifying the variables available on those
+templates. The function is passed named parameters. The "page" and
+"destpage" parameters are the same as for a preprocess hook. The "template"
+parameter is a [[!cpan HTML::Template]] object that is the template that
+will be used to generate the page. The function can manipulate that
+template object.
+
+The most common thing to do is probably to call `$template->param()` to add
+a new custom parameter to the template.
 
-	IkiWiki::hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
+### templatefile
 
-Each time a page is rendered, a [[template|templates]] is filled out.
-This hook allows modifying that template. The function is passed the name
-of the page, and a `HTML::Template` object that is the template that will
-be used to generate the page. It can manipulate that template, the most
-common thing to do is probably to call $template->param() to add a new
-custom parameter to the template.
+	hook(type => "templatefile", id => "foo", call => \&templatefile);
 
-## sanitize
+This hook allows plugins to change the [[template|wikitemplates]] that is
+used for a page in the wiki. The hook is passed a "page" parameter, and
+should return the name of the template file to use, or undef if it doesn't
+want to change the default ("page.tmpl"). Template files are looked for in
+/usr/share/ikiwiki/templates by default.
 
-	IkiWiki::hook(type => "sanitize", id => "foo", call => \&sanitize);
+### sanitize
+
+	hook(type => "sanitize", id => "foo", call => \&sanitize);
 
 Use this to implement html sanitization or anything else that needs to
-modify the content of a page after it has been fully converted to html.
-The function is passed the page content and should return the sanitized
-content.
+modify the body of a page after it has been fully converted to html.
+
+The function is passed named parameters: "page", "destpage", and "content",
+and should return the sanitized content.
+
+### postscan
+
+	hook(type => "postscan", id => "foo", call => \&postscan);
+
+This hook is called once the full page body is available (but before the
+format hook). The most common use is to update search indexes. Added in
+ikiwiki 2.54.
 
-## delete
+The function is passed named parameters "page" and "content". Its return
+value is ignored.
 
-	IkiWiki::hook(type => "delete", id => "foo", call => \&dele);
+### format
+
+	hook(type => "format", id => "foo", call => \&format);
+
+The difference between format and sanitize is that sanitize only acts on
+the page body, while format can modify the entire html page including the
+header and footer inserted by ikiwiki, the html document type, etc. (It
+should not rely on always being passed the entire page, as it won't be
+when the page is being previewed.)
+
+The function is passed named parameters: "page" and "content", and 
+should return the formatted content.
+
+### delete
+
+	hook(type => "delete", id => "foo", call => \&delete);
 
 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.
 
-## change
+### change
 
-	IkiWiki::hook(type => "change", id => "foo", call => \&render);
+	hook(type => "change", id => "foo", call => \&render);
 
 Each time ikiwiki renders a change or addition (but not deletion) to the
 wiki, the referenced function is called, and passed the names of the
 source files that were rendered.
 
-## cgi
+### cgi
 
-	IkiWiki::hook(type => "cgi", id => "foo", call => \&cgi);
+	hook(type => "cgi", id => "foo", call => \&cgi);
 
 Use this to hook into ikiwiki's cgi script. Each registered cgi hook is
 called in turn, and passed a CGI object. The hook should examine the
-parameters, and if it will handle this CGI request, output a page and
-terminate the program.
+parameters, and if it will handle this CGI request, output a page
+(including the http headers) and terminate the program.
+
+Note that cgi hooks are called as early as possible, before any ikiwiki
+state is loaded, and with no session information.
+
+### auth
+
+	hook(type => "auth", id => "foo", call => \&auth);
+
+This hook can be used to implement an authentication method. When a user
+needs to be authenticated, each registered auth hook is called in turn, and
+passed a CGI object and a session object. 
+
+If the hook is able to authenticate the user, it should set the session
+object's "name" parameter to the authenticated user's name. Note that
+if the name is set to the name of a user who is not registered,
+a basic registration of the user will be automatically performed.
+
+### sessioncgi
+
+	hook(type => "sessioncgi", id => "foo", call => \&sessioncgi);
+
+Unlike the cgi hook, which is run as soon as possible, the sessioncgi hook
+is only run once a session object is available. It is passed both a CGI
+object and a session object. To check if the user is in fact signed in, you
+can check if the session object has a "name" parameter set.
+
+### canedit
+
+	hook(type => "canedit", id => "foo", call => \&pagelocked);
+
+This hook can be used to implement arbitrary access methods to control when
+a page can be edited using the web interface (commits from revision control
+bypass it). When a page is edited, each registered canedit hook is called
+in turn, and passed the page name, a CGI object, and a session object.
+
+If the hook has no opinion about whether the edit can proceed, return
+`undef`, and the next plugin will be asked to decide. If edit can proceed,
+the hook should return "". If the edit is not allowed by this hook, the
+hook should return an error message for the user to see, or a function 
+that can be run to log the user in or perform other action necessary for
+them to be able to edit the page.
+
+This hook should avoid directly redirecting the user to a signin page,
+since it's sometimes used to test to see which pages in a set of pages a
+user can edit.
+
+### editcontent
+
+	hook(type => "editcontent", id => "foo", call => \&editcontent);
+
+This hook is called when a page is saved (or previewed) using the web
+interface. It is passed named parameters: `content`, `page`, `cgi`, and
+`session`. These are, respectively, the new page content as entered by the
+user, the page name, a `CGI` object, and the user's `CGI::Session`. 
+
+It can modify the content as desired, and should return the content.
+
+### formbuilder
+
+	hook(type => "formbuilder_setup", id => "foo", call => \&formbuilder_setup);
+	hook(type => "formbuilder", id => "foo", call => \&formbuilder);
+
+These hooks allow tapping into the parts of ikiwiki that use [[!cpan
+CGI::FormBuilder]] to generate web forms. These hooks are passed named
+parameters: `cgi`, `session`, `form`, and `buttons`. These are, respectively,
+the `CGI` object, the user's `CGI::Session`, a `CGI::FormBuilder`, and a
+reference to an array of names of buttons to go on the form.
+
+Each time a form is set up, the `formbuilder_setup` hook is called.
+Typically the `formbuilder_setup` hook will check the form's title, and if
+it's a form that it needs to modify, will call various methods to
+add/remove/change fields, tweak the validation code for the fields, etc. It
+will not validate or display the form.
+
+Just before a form is displayed to the user, the `formbuilder` hook is
+called. It can be used to validate the form, but should not display it.
+
+### savestate
+
+	hook(type => "savestate", id => "foo", call => \&savestate);
+
+This hook is called whenever ikiwiki normally saves its state, just before
+the state is saved. The function can save other state, modify values before
+they're saved, etc.
+
+## renamepage
+
+	hook(type => "renamepage", id => "foo", call => \&renamepage);
+
+This hook is called by the [[plugins/rename]] plugin when it renames
+something. The hook is passed named parameters: `page`, `oldpage`,
+`newpage`, and `content`, and should try to modify the content to reflect
+the name change. For example, by converting links to point to the new page.
+
+### getsetup
+
+	hook(type => "getsetup", id => "foo", call => \&getsetup);
+
+This hooks is not called during normal operation, but only when setting up 
+the wiki, or generating a setup file. Plugins can use this hook to add
+configuration options.
+
+The hook is passed no parameters. It returns data about the configuration
+options added by the plugin. It can also check if the plugin is usable, and
+die if the plugin is not available, which will cause the plugin to not be
+offered in the configuration interface.
+
+The data returned is a list of `%config` options, followed by a hash
+describing the option. For example:
+
+                return
+			option_foo => {
+				type => "boolean",
+				description => "enable foo",
+				safe => 1,
+				rebuild => 1,
+	                },
+			option_bar => {
+				type => "string",
+				example => "hello",
+				description => "what to say",
+				safe => 1,
+				rebuild => 0,
+			},
+
+* `type` can be "boolean", "string", "integer", "internal" (used for values
+  that are not user-visible). The type is the type of the leaf values; 
+  the `%config` option may be an array or hash of these.
+* `example` can be set to an example value.
+* `description` is a short description of the option.
+* `safe` should be false if the option should not be displayed in unsafe
+  configuration methods, such as the web interface. Anything that specifies
+  a command to run, a path on disk, or a regexp should be marked as unsafe.
+* `rebuild` should be true if changing the option will require a wiki rebuild.
+
+## Plugin interface
+
+To import the ikiwiki plugin interface:
 
-# Wiki configuration
+	use IkiWiki '2.00';
 
-A plugin can access the wiki's configuration via the `%IkiWiki::config`
+This will import several variables and functions into your plugin's
+namespace. These variables and functions are the ones most plugins need,
+and a special effort will be made to avoid changing them in incompatible
+ways, and to document any changes that have to be made in the future.
+
+Note that IkiWiki also provides other variables and functions that are not
+exported by default. No guarantee is made about these in the future, so if
+it's not exported, the wise choice is to not use it.
+
+### %config
+
+A plugin can access the wiki's configuration via the `%config`
 hash. The best way to understand the contents of the hash is to look at
 [[ikiwiki.setup]], which sets the hash content to configure the wiki.
 
-# Wiki data
+### %pagestate
+
+The `%pagestate` hash can be used by plugins to save state that they will need
+next time ikiwiki is run. The hash holds per-page state, so to set a value,
+use `%pagestate{$page}{$id}{$key}=$value`, and to retrieve the value,
+use `%pagestate{$page}{$id}{$key}`.
+
+The `$value` can be anything that perl's Storable module is capable of
+serializing. `$key` can be any string you like, but `$id` must be the same
+as the "id" parameter passed to `hook()` when registering the plugin. This
+is so ikiwiki can know when to delete pagestate for plugins that are no
+longer used.
+
+When pages are deleted, ikiwiki automatically deletes their pagestate too.
+
+Note that page state does not persist across wiki rebuilds, only across
+wiki updates.
+
+### Other variables
 
 If your plugin needs to access data about other pages in the wiki. It can
 use the following hashes, using a page name as the key:
 
-* `%IkiWiki::links` lists the names of each page
-  that a page links to, in an array reference.
-* `%IkiWiki::pagemtime` contains the last modification time of each page
-* `%IkiWiki::pagectime` contains the creation time of each page
-* `%IkiWiki::renderedfiles` contains the name of the file rendered by a
-  page
-* `%IkiWiki::pagesources` contains the name of the source file for a page.
-* `%IkiWiki::depends` contains a [[GlobList]] that is used to specify other
-  pages that a page depends on. If one of its dependencies is updated, the
-  page will also get rebuilt. 
-  
-  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
+* `%links` lists the names of each page that a page links to, in an array
+  reference.
+* `%destsources` contains the name of the source file used to create each
+  destination file.
+* `%pagesources` contains the name of the source file for each page.
+
+Also, the %IkiWiki::version variable contains the version number for the
+ikiwiki program.
+
+### Library functions
+
+#### `hook(@)`
+
+Hook into ikiwiki's processing. See the discussion of hooks above.
+
+Note that in addition to the named parameters described above, a parameter
+named `no_override` is supported, If it's set to a true value, then this hook
+will not override any existing hook with the same id. This is useful if
+the id can be controled by the user.
+
+#### `debug($)`
+
+Logs a debugging message. These are supressed unless verbose mode is turned
+on.
+
+#### `error($;$)`
+
+Aborts with an error message. If the second parameter is passed, it is a
+function that is called after the error message is printed, to do any final
+cleanup.
+
+If called inside a preprocess hook, error() does not abort the entire
+wiki build, but instead replaces the [[ikiwiki/PreProcessorDirective]] with
+a version containing the error message.
+
+In other hooks, error() is a fatal error, so use with care. Try to avoid
+dying on bad input when building a page, as that will halt
+the entire wiki build and make the wiki unusable.
+
+#### `template($;@)`
+
+Creates and returns a [[!cpan HTML::Template]] object. The first parameter
+is the name of the file in the template directory. The optional remaining
+parameters are passed to `HTML::Template->new`.
+
+#### `htmlpage($)`
+
+Passed a page name, returns the base name that will be used for a the html
+page created from it. (Ie, it appends ".html".)
+
+#### `add_depends($$)`
+
+Makes the specified page depend on the specified [[ikiwiki/PageSpec]].
+
+#### `pagespec_match($$;@)`
+
+Passed a page name, and [[ikiwiki/PageSpec]], returns true if the
+[[ikiwiki/PageSpec]] matches the page.
+
+Additional named parameters can be passed, to further limit the match.
+The most often used is "location", which specifies the location the
+PageSpec should match against. If not passed, relative PageSpecs will match
+relative to the top of the wiki.
+
+#### `bestlink($$)`
+
+Given a page and the text of a link on the page, determine which
+existing page that link best points to. Prefers pages under a
+subdirectory with the same name as the source page, failing that
+goes down the directory tree to the base looking for matching
+pages, as described in [[ikiwiki/SubPage/LinkingRules]].
+
+#### `htmllink($$$;@)`
+
+Many plugins need to generate html links and add them to a page. This is
+done by using the `htmllink` function. The usual way to call
+`htmlllink` is:
+
+	htmllink($page, $page, $link)
+
+Why is `$page` repeated? Because if a page is inlined inside another, and a
+link is placed on it, the right way to make that link is actually:
+
+	htmllink($page, $destpage, $link)
+
+Here `$destpage` is the inlining page. A `destpage` parameter is passed to
+some of the hook functions above; the ones that are not passed it are not used
+during inlining and don't need to worry about this issue.
+
+After the three required parameters, named parameters can be used to
+control some options. These are:
+
+* noimageinline - set to true to avoid turning links into inline html images
+* forcesubpage  - set to force a link to a subpage
+* linktext - set to force the link text to something
+* anchor - set to make the link include an anchor
+* rel - set to add a rel attribute to the link
+* class - set to add a css class to the link
+
+#### `readfile($;$)`
+
+Given a filename, reads and returns the entire file.
+
+The optional second parameter, if set to a true value, makes the file be read
+in binary mode.
+
+A failure to read the file will result in it dying with an error.
+
+#### `writefile($$$;$$)`
+
+Given a filename, a directory to put it in, and the file's content,
+writes a file. 
+
+The optional fourth parameter, if set to a true value, makes the file be
+written in binary mode.
+
+The optional fifth parameter can be used to pass a function reference that
+will be called to handle writing to the file. The function will be called
+and passed a file descriptor it should write to, and an error recovery
+function it should call if the writing fails. (You will not normally need to
+use this interface.)
+
+A failure to write the file will result in it dying with an error.
+
+If the destination directory doesn't exist, it will first be created.
+
+#### `will_render($$)`
+
+Given a page name and a destination file name (not including the base
+destination directory), register that the page will result in that file
+being rendered. 
+
+It's important to call this before writing to any file in the destination
+directory, and it's important to call it consistently every time, even if
+the file isn't really written this time -- unless you delete any old
+version of the file. In particular, in preview mode, this should still be
+called even if the file isn't going to be written to during the preview.
+
+Ikiwiki uses this information to automatically clean up rendered files when
+the page that rendered them goes away or is changed to no longer render
+them. will_render also does a few important security checks.
+
+#### `pagetype($)`
+
+Given the name of a source file, returns the type of page it is, if it's
+a type that ikiwiki knowns how to htmlize. Otherwise, returns undef.
+
+#### `pagename($)`
+
+Given the name of a source file, returns the name of the wiki page
+that corresponds to that file.
+
+#### `srcfile($;$)`
+
+Given the name of a source file in the wiki, searches for the file in
+the source directory and the underlay directories (most recently added
+underlays first), and returns the full path to the first file found.
+
+Normally srcfile will fail with an error message if the source file cannot
+be found. The second parameter can be set to a true value to make it return
+undef instead.
+
+#### `add_underlay($)`
+
+Adds a directory to the set of underlay directories that ikiwiki will
+search for files.
+
+If the directory name is not absolute, ikiwiki will assume it is in
+the parent directory of the configured underlaydir.
+
+#### `displaytime($;$)`
+
+Given a time, formats it for display.
+
+The optional second parameter is a strftime format to use to format the
+time.
+
+#### `gettext`
+
+This is the standard gettext function, although slightly optimised.
+
+#### `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`.
+
+If the third parameter is passed and is true, an absolute url will be
+constructed instead of the default relative url.
+
+#### `targetpage($$)`
+
+Passed a page and an extension, returns the filename that page will be
+rendered to.
+
+## Miscellaneous
+
+### Internal use pages
+
+Sometimes it's useful to put pages in the wiki without the overhead of
+having them be rendered to individual html files. Such internal use pages
+are collected together to form the RecentChanges page, for example.
+
+To make an internal use page, register a filename extension that starts
+with "_". Internal use pages cannot be edited with the web interface,
+generally shouldn't contain wikilinks or preprocessor directives (use
+either on them with extreme caution), and are not matched by regular
+PageSpecs glob patterns, but instead only by a special `internal()`
+[[ikiwiki/PageSpec]].
+
+### RCS plugins
+
+ikiwiki's support for [[revision_control_systems|rcs]] 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.
+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.
+`rcs_getctime` does nothing except for throwing an error.
+
+See [[RCS_details|rcs/details]] for some more info.
+
+### PageSpec plugins
+
+It's also possible to write plugins that add new functions to
+[[PageSpecs|ikiwiki/PageSpec]]. Such a plugin should add a function to the
+IkiWiki::PageSpec package, that is named `match_foo`, where "foo()" is
+how it will be accessed in a [[ikiwiki/PageSpec]]. The function will be passed
+two parameters: The name of the page being matched, and the thing to match
+against. It may also be passed additional, named parameters. It should return
+a IkiWiki::SuccessReason object if the match succeeds, or an
+IkiWiki::FailReason object if the match fails.
+
+### Setup plugins
+
+The ikiwiki setup file is loaded using a pluggable mechanism. If you
+look at the top of [[ikiwiki.setup]], it starts with 
+'use IkiWiki::Setup::Standard', and the rest of the file is passed to
+that module's import method.
+
+It's possible to write other modules in the `IkiWiki::Setup::` namespace that
+can be used to configure ikiwiki in different ways. These modules should,
+when imported, populate `$IkiWiki::Setup::raw_setup` with a reference
+to a hash containing all the config items.
 
-See [[about_RCS_backends]] for some more info.
+By the way, to parse a ikiwiki setup file, a program just needs to
+do something like:
+`use IkiWiki::Setup; my %setup=IkiWiki::Setup::load($filename)`