X-Git-Url: https://sipb.mit.edu/gitweb.cgi/ikiwiki.git/blobdiff_plain/20ba12802b3897bf48d8a7704a57e9cede2466bd..c99d26030e6ddd7a21932e98e40a8df7d896886d:/doc/plugins/write.mdwn

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index fbaabb6a0..8071f323e 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -3,8 +3,84 @@ 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]].
 
+[[!template id="note" text="""
+Ikiwiki is a compiler
+
+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
+are loaded. A plugin that inserts the current time into a page, for
+example, will insert the build time.
+
+Also, as a compiler, ikiwiki avoids rebuilding pages unless they have
+changed, so a plugin that prints some 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.
+
+The [[tutorial]] has some other examples of ways that ikiwiki being a
+compiler may trip up the unwary.
+"""]]
+
 [[!toc levels=2]]
 
+## Highlevel view of ikiwiki
+
+Ikiwiki mostly has two modes of operation. It can either be running
+as a compiler, building or updating a wiki; or as a cgi program, providing
+user interface for editing pages, etc. Almost everything ikiwiki does
+is accomplished by calling various hooks provided by plugins.
+
+### compiler
+
+As a compiler, ikiwiki starts by calling the `refresh` hook. Then it checks
+the wiki's source to find new or changed pages. The `needsbuild` hook is
+then called to allow manipulation of the list of pages that need to be
+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
+hooks: `filter`, `preprocess`, `linkify`, `htmlize`, `indexhtml`,
+`pagetemplate`, `sanitize`, `format`.
+
+After all necessary pages are built, it calls the `change` hook. Finally,
+if a page is was deleted, the `delete` hook is called, and the files that
+page had previously produced are removed.
+
+### cgi
+
+The flow between hooks when ikiwiki is run as a cgi is best illustrated by
+an example.
+
+Alice browses to a page and clicks Edit.
+
+* Ikiwiki is run as a cgi. It assigns Alice a session cookie, and,
+  by calling the `auth` hooks, sees that she is not yet logged in.
+* The `sessioncgi` hooks are then called, and one of them,
+  from the [[editpage]] plugin, notices that the cgi has been told "do=edit".
+* The [[editpage]] plugin calls the `canedit` hook to check if this
+  page edit is allowed. The [[signinedit]] plugin has a hook that says not:
+  Alice is not signed in.
+* The [[signinedit]] plugin then launches the signin process. A signin
+  page is built by calling the `formbuilder_setup` hook.
+
+Alice signs in with her openid.
+
+* The [[openid]] plugin's `formbuilder` hook sees that an openid was
+  entered in the signin form, and redirects to Alice's openid provider.
+* Alice's openid provider calls back to ikiwiki. The [[openid]] plugin
+  has an `auth` hook that finishes the openid signin process.
+* Signin complete, ikiwiki returns to what Alice was doing before; editing
+  a page.
+* Now all the `canedit` hooks are happy. The [[editpage]] plugin calls
+  `formbuilder_setup` to display the page editing form.
+
+Alice saves her change to the page.
+
+* The [[editpage]] plugin's `formbuilder` hook sees that the Save button
+  was pressed, and calls the `checkcontent` and `editcontent` hooks.
+  Then it saves the page to disk, and branches into the compiler part
+  of ikiwiki to refresh the wiki.
+
 ## Types of plugins
 
 Most ikiwiki [[plugins]] are written in perl, like ikiwiki. This gives the
@@ -31,16 +107,20 @@ 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
+## Plugin interface
 
-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
-are loaded. A plugin that inserts the current time into a page, for
-example, will insert the build time. Also, as a compiler, ikiwiki avoids
-rebuilding pages unless they have changed, so a plugin that prints some
-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.
+To import the ikiwiki plugin interface:
+
+	use IkiWiki '3.00';
+
+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.
 
 ## Registering plugins
 
@@ -120,7 +200,9 @@ value is ignored.
 
 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", and "content". It should return the filtered content.
+"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.
 
 ### preprocess
 
@@ -202,22 +284,22 @@ 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.
 
-### 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.
 
-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
 
 	hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
 
-[[Templates|wikitemplates]] are filled out for many different things in
+[[Templates]] 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
@@ -233,11 +315,20 @@ a new custom parameter to the template.
 
 	hook(type => "templatefile", id => "foo", call => \&templatefile);
 
-This hook allows plugins to change the [[template|wikitemplates]] that is
+This hook allows plugins to change the [[template|templates]] 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.
+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").
+
+### 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
 
@@ -456,7 +547,7 @@ The data returned is a list of `%config` options, followed by a hash
 describing the option. There can also be an item named "plugin", which
 describes the plugin as a whole. For example:
 
-                return
+		return
 			plugin => {
 				description => "description of this plugin",
 				safe => 1,
@@ -506,30 +597,22 @@ 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`
-function of the ikiwiki wrapper when it is being generated.
+function of the ikiwiki wrapper when it is being generated. 
 
-## Plugin interface
+The code runs before anything else -- in particular it runs before
+the suid wrapper has sanitized its environment.
 
-To import the ikiwiki plugin interface:
+## Exported variables
 
-	use IkiWiki '3.00';
+Several variables are exported to your plugin when you `use IkiWiki;`
 
-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
+### `%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
 your ikiwiki setup file, which sets the hash content to configure the wiki.
 
-### %pagestate
+### `%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,
@@ -547,7 +630,7 @@ When pages are deleted, ikiwiki automatically deletes their pagestate too.
 Note that page state does not persist across wiki rebuilds, only across
 wiki updates.
 
-### %wikistate
+### `%wikistate`
 
 The `%wikistate` hash can be used by a plugin to store persistant state
 that is not bound to any one page. To set a value, use
@@ -556,23 +639,53 @@ serialize, `$key` is any string you like, and `$id` must be the same as the
 "id" parameter passed to `hook()` when registering the plugin, so that the
 state can be dropped if the plugin is no longer used.
 
-### Other variables
+### `%links`
 
-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:
+The `%links` hash can be used to look up the names of each page that
+a page links to. The name of the page is the key; the value is an array
+reference. Do not modify this hash directly; call `add_link()`.
 
-* `%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.
+	$links{"foo"} = ["bar", "baz"];
 
-Also, the `%IkiWiki::version` variable contains the version number for the
-ikiwiki program.
+### `%typedlinks`
 
-### Library functions
+The `%typedlinks` hash records links of specific types. Do not modify this
+hash directly; call `add_link()`. The keys are page names, and the values
+are hash references. In each page's hash reference, the keys are link types
+defined by plugins, and the values are hash references with link targets
+as keys, and 1 as a dummy value, something like this:
 
-#### `hook(@)`
+	$typedlinks{"foo"} = {
+		tag => { short_word => 1, metasyntactic_variable => 1 },
+		next_page => { bar => 1 },
+	};
+
+Ordinary [[WikiLinks|ikiwiki/WikiLink]] appear in `%links`, but not in
+`%typedlinks`.
+
+### `%pagesources`
+
+The `%pagesources` has can be used to look up the source filename
+of a page. So the key is the page name, and the value is the source
+filename. Do not modify this hash.
+
+	$pagesources{"foo"} = "foo.mdwn";
+
+### `%destsources`
+
+The `%destsources` hash records the name of the source file used to
+create each destination file. The key is the output filename (ie,
+"foo/index.html"), and the value is the source filename that it was built
+from (eg, "foo.mdwn"). Note that a single source file may create multiple
+destination files. Do not modify this hash directly; call `will_render()`.
+	
+	$destsources{"foo/index.html"} = "foo.mdwn";
+
+## Library functions
+
+Several functions are exported to your plugin when you `use IkiWiki;`
+
+### `hook(@)`
 
 Hook into ikiwiki's processing. See the discussion of hooks above.
 
@@ -581,12 +694,12 @@ 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($)`
+### `debug($)`
 
 Logs a debugging message. These are supressed unless verbose mode is turned
 on.
 
-#### `error($;$)`
+### `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
@@ -600,37 +713,40 @@ 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($;@)`
+### `template($;@)`
+
+Creates and returns a [[!cpan HTML::Template]] object. (In a list context,
+returns the parameters needed to construct the obhect.) 
 
-Creates and returns a [[!cpan HTML::Template]] object. The first parameter
-is the name of the file in the template directory. The optional remaining
+The first parameter is the name of the template file. The optional remaining
 parameters are passed to `HTML::Template->new`.
 
-#### `htmlpage($)`
+Normally, the template file is first looked for in the templates/ subdirectory
+of the srcdir. Failing that, it is looked for in the templatedir.
 
-Passed a page name, returns the base name that will be used for a the html
-page created from it. (Ie, it appends ".html".)
+Wiki pages can be used as templates. This should be done only for templates
+which it is safe to let wiki users edit. Enable it by passing a filename
+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.
 
-Use this when constructing the filename of a html file. Use `urlto` when
-generating a link to a page.
+### `template_depends($$;@)`
 
-### `deptype(@)`
+Use this instead of `template()` if the content of a template is being
+included into a page. This causes the page to depend on the template,
+so it will be updated if the template is modified.
 
-Use this function to generate ikiwiki's internal representation of a
-dependency type from one or more of these keywords:
+Like `template()`, except the second parameter is the page.
 
-* `content` is the default. Any change to the content
-  of a page triggers the dependency.
-* `presence` is only triggered by a change to the presence
-  of a page.
-* `links` is only triggered by a change to the links of a page.
-  This includes when a link is added, removed, or changes what
-  it points to due to other changes. It does not include the
-  addition or removal of a duplicate link.
+### `htmlpage($)`
 
-If multiple types are specified, they are combined.
+Passed a page name, returns the base name that will be used for a the html
+page created from it. (Ie, it appends ".html".)
 
-#### `pagespec_match_list($$;@)`
+Use this when constructing the filename of a html file. Use `urlto` when
+generating a link to a page.
+
+### `pagespec_match_list($$;@)`
 
 Passed a page name, and [[ikiwiki/PageSpec]], returns a list of pages
 in the wiki that match the [[ikiwiki/PageSpec]]. 
@@ -651,7 +767,10 @@ Additional named parameters can be specified:
 * `filter` is a reference to a function, that is called and passed a page,
   and returns true if the page should be filtered out of the list.
 * `sort` specifies a sort order for the list. See
-  [[ikiwiki/PageSpec/sorting]] for the avilable sort methods.
+  [[ikiwiki/PageSpec/sorting]] for the avilable sort methods. Note that
+  if a sort method is specified that depends on the
+  page content (such as 'meta(foo)'), the deptype needs to be set to
+  a content dependency.
 * `reverse` if true, sorts in reverse.
 * `num` if nonzero, specifies the maximum number of matching pages that
   will be returned.
@@ -661,7 +780,7 @@ Additional named parameters can be specified:
 Any other named parameters are passed on to `pagespec_match`, to further
 limit the match.
 
-#### `add_depends($$;$)`
+### `add_depends($$;$)`
 
 Makes the specified page depend on the specified [[ikiwiki/PageSpec]].
 
@@ -669,7 +788,7 @@ By default, dependencies are full content dependencies, meaning that the
 page will be updated whenever anything matching the PageSpec is modified.
 This can be overridden by passing a `deptype` value as the third parameter.
 
-#### `pagespec_match($$;@)`
+### `pagespec_match($$;@)`
 
 Passed a page name, and [[ikiwiki/PageSpec]], returns a true value if the
 [[ikiwiki/PageSpec]] matches the page.
@@ -683,7 +802,23 @@ 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($$)`
+### `deptype(@)`
+
+Use this function to generate ikiwiki's internal representation of a
+dependency type from one or more of these keywords:
+
+* `content` is the default. Any change to the content
+  of a page triggers the dependency.
+* `presence` is only triggered by a change to the presence
+  of a page.
+* `links` is only triggered by a change to the links of a page.
+  This includes when a link is added, removed, or changes what
+  it points to due to other changes. It does not include the
+  addition or removal of a duplicate link.
+
+If multiple types are specified, they are combined.
+
+### `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
@@ -691,7 +826,7 @@ 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($$$;@)`
+### `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
@@ -719,7 +854,7 @@ control some options. These are:
 * class - set to add a css class to the link
 * title - set to add a title attribute to the link
 
-#### `readfile($;$)`
+### `readfile($;$)`
 
 Given a filename, reads and returns the entire file.
 
@@ -728,7 +863,7 @@ in binary mode.
 
 A failure to read the file will result in it dying with an error.
 
-#### `writefile($$$;$$)`
+### `writefile($$$;$$)`
 
 Given a filename, a directory to put it in, and the file's content,
 writes a file. 
@@ -756,7 +891,7 @@ generally the directory parameter is a trusted toplevel directory like
 the srcdir or destdir, and any subdirectories of this are included in the
 filename parameter.
 
-#### `will_render($$)`
+### `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
@@ -772,34 +907,34 @@ 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($)`
+### `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($)`
+### `pagename($)`
 
 Given the name of a source file, returns the name of the wiki page
 that corresponds to that file.
 
-#### `pagetitle($)`
+### `pagetitle($)`
 
 Give the name of a wiki page, returns a version suitable to be displayed as
 the page's title. This is accomplished by de-escaping escaped characters in
 the page name. "_" is replaced with a space, and '__NN__' is replaced by 
 the UTF character with code NN.
 
-#### `titlepage($)`
+### `titlepage($)`
 
 This performs the inverse of `pagetitle`, ie, it converts a page title into
 a wiki page name.
 
-#### `linkpage($)`
+### `linkpage($)`
 
 This converts text that could have been entered by the user as a
 [[ikiwiki/WikiLink]] into a wiki page name.
 
-#### `srcfile($;$)`
+### `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
@@ -809,7 +944,7 @@ 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($)`
+### `add_underlay($)`
 
 Adds a directory to the set of underlay directories that ikiwiki will
 search for files.
@@ -817,18 +952,25 @@ search for files.
 If the directory name is not absolute, ikiwiki will assume it is in
 the parent directory of the configured underlaydir.
 
-#### `displaytime($;$)`
+### `displaytime($;$$)`
 
 Given a time, formats it for display.
 
 The optional second parameter is a strftime format to use to format the
 time.
 
-#### `gettext`
+If the third parameter is true, this is the publication time of a page.
+(Ie, set the html5 pubdate attribute.)
+
+### `gettext`
 
 This is the standard gettext function, although slightly optimised.
 
-#### `urlto($$;$)`
+### `ngettext`
+
+This is the standard ngettext 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
@@ -837,13 +979,13 @@ 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.
 
-#### `newpagefile($$)`
+### `newpagefile($$)`
 
 This can be called when creating a new page, to determine what filename
 to save the page to. It's passed a page name, and its type, and returns
 the name of the file to create, relative to the srcdir.
 
-#### `targetpage($$;$)`
+### `targetpage($$;$)`
 
 Passed a page and an extension, returns the filename that page will be
 rendered to.
@@ -852,11 +994,31 @@ Optionally, a third parameter can be passed, to specify the preferred
 filename of the page. For example, `targetpage("foo", "rss", "feed")`
 will yield something like `foo/feed.rss`.
 
-#### `add_link($$)`
+### `add_link($$;$)`
 
 This adds a link to `%links`, ensuring that duplicate links are not
 added. Pass it the page that contains the link, and the link text.
 
+An optional third parameter sets the link type. If not specified,
+it is an ordinary [[ikiwiki/WikiLink]].
+
+### `add_autofile($$$)`
+
+Sometimes you may want to add a file to the `srcdir` as a result of content
+of other pages. For example, [[plugins/tag]] pages can be automatically
+created as needed. This function can be used to do that. 
+
+The three parameters are the filename to create (relative to the `srcdir`),
+the name of the plugin, and a callback function. The callback will be
+called if it is appropriate to automatically add the file, and should then
+take care of creating it, and doing anything else it needs to (such as
+checking it into revision control). Note that the callback may not always
+be called. For example, if an automatically added file is deleted by the
+user, ikiwiki will avoid re-adding it again.
+
+This function needs to be called during the scan hook, or earlier in the
+build process, in order to add the file early enough for it to be built.
+
 ## Miscellaneous
 
 ### Internal use pages
@@ -894,16 +1056,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.
 
-#### `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.
 
-#### `rcs_commit_staged($$$)`
+#### `rcs_commit_staged(@)`
 
-Passed a message, user, and ip address. Should commit all staged changes.
-Returns undef on success, and an error message on failure.
+Passed named parameters: `message`, and `session` (optional).
+
+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`.
@@ -946,7 +1112,9 @@ The data structure returned for each change is:
 
 	{
 		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 => [
@@ -976,6 +1144,17 @@ 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($)`
+
+This is used to get the page modification 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 mtime for the file, return 0.
+
 #### `rcs_receive()`
 
 This is called when ikiwiki is running as a pre-receive hook (or
@@ -1023,6 +1202,24 @@ For example, "backlink(foo)" is influenced by the contents of page foo;
 they match; "created_before(foo)" is influenced by the metadata of foo;
 while "glob(*)" is not influenced by the contents of any page.
 
+### Sorting plugins
+
+Similarly, it's possible to write plugins that add new functions as
+[[ikiwiki/pagespec/sorting]] methods. To achieve this, add a function to
+the IkiWiki::SortSpec package named `cmp_foo`, which will be used when sorting
+by `foo` or `foo(...)` is requested.
+
+The names of pages to be compared are in the global variables `$a` and `$b`
+in the IkiWiki::SortSpec package. The function should return the same thing
+as Perl's `cmp` and `<=>` operators: negative if `$a` is less than `$b`,
+positive if `$a` is greater, or zero if they are considered equal. It may
+also raise an error using `error`, for instance if it needs a parameter but
+one isn't provided.
+
+The function will also be passed one or more parameters. The first is
+`undef` if invoked as `foo`, or the parameter `"bar"` if invoked as `foo(bar)`;
+it may also be passed additional, named parameters.
+
 ### Setup plugins
 
 The ikiwiki setup file is loaded using a pluggable mechanism. If you look