X-Git-Url: https://sipb.mit.edu/gitweb.cgi/ikiwiki.git/blobdiff_plain/912521ef0711204965aa2319d41c7741bd3f4f4c..fd8463c878d1fb9920ef6f10944f8522e7a48f69:/doc/plugins/write.mdwn

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 6c475024a..5bc3ad7ce 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -96,9 +96,11 @@ 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). 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.
+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.
 
 Note that if the [[htmlscrubber]] is enabled, html in
 [[PreProcessorDirective]] output is sanitised, which may limit what your
@@ -192,6 +194,20 @@ 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.
 
+### 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 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.
+If the hook has no opinion about whether the edit can proceed, return
+`undef`, and the next plugin will be asked to decide.
+
 ### formbuilder
 
 	hook(type => "formbuilder_setup", id => "foo", call => \&formbuilder_setup);
@@ -202,8 +218,8 @@ CGI::FormBuilder]] to generate web forms. These hooks are passed named
 parameters: `cgi`, `session`, and `form`. These are, respectively, the
 `CGI` object, the user's `CGI::Session`, and a `CGI::FormBuilder`.
 
-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
+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.
@@ -273,9 +289,11 @@ the id can be controled by the user.
 Logs a debugging message. These are supressed unless verbose mode is turned
 on.
 
-#### `error($)`
+#### `error($;$)`
 
-Aborts with an error message.
+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.
 
 Note that while any plugin can use this for a fatal error, plugins should
 try to avoid dying on bad input, as that will halt the entire wiki build
@@ -298,10 +316,12 @@ page created from it. (Ie, it appends ".html".)
 
 Makes the specified page depend on the specified [[PageSpec]].
 
-#### `pagespec_match($$)`
+#### `pagespec_match($$;$)`
 
-Passed a page name, and a [[PageSpec]], returns true if the [[PageSpec]]
-matches the page.
+Passed a page name, a [[PageSpec]], and the location the [[PageSpec]] should
+be matched against, returns true if the [[PageSpec]] matches the page. (If
+the third parameter is not passed, relative PageSpecs will match relative to
+the top of the wiki.)
 
 #### `bestlink($$)`
 
@@ -311,7 +331,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 [[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
@@ -328,11 +348,13 @@ 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.
 
-The remaining three optional parameters to `htmllink` are:
+After the three required parameters, named parameters can be used to
+control some options. These are:
 
-1. noimageinline - set to true to avoid turning links into inline html images
-1. forcesubpage  - set to force a link to a subpage
-1. linktext - set to force the link text to something
+* 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
 
 #### `readfile($;$)`
 
@@ -343,14 +365,20 @@ 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. 
 
-The optional second parameter, if set to a true value, makes the file be
+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.
@@ -386,6 +414,15 @@ Given a time, formats it for display.
 
 This is the standard gettext function, although slightly optimised.
 
+#### `urlto($$)`
+
+Construct a relative url to the first parameter from the second.
+
+#### `targetpage($$)`
+
+Passed a page and an extension, returns the filename that page will be
+rendered to.
+
 ## RCS plugins
 
 ikiwiki's support for revision control systems also uses pluggable perl
@@ -397,3 +434,13 @@ See IkiWiki::RCS::Stub for the full list of functions. It's ok if
 rcs\_getctime does nothing except for throwing an error.
 
 See [[about_RCS_backends]] for some more info.
+
+## PageSpec plugins
+
+It's also possible to write plugins that add new functions to
+[[PageSpecs|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 [[PageSpec]]. The function will be passed
+three parameters: The name of the page being matched, the thing to match
+against, and the page that the matching is occuring on. It should return
+true if the page matches.