web commit by https://perolofsson.myopenid.com/

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 1aaaf1d1e7ea7aa7e3e6371b7fbf987d735d5a9b..889057e699fc7436049324bc7c42eb8c8ab2c05e 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -287,9 +287,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
@@ -327,7 +329,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
@@ -344,11 +346,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($;$)`
 
@@ -359,14 +363,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.
@@ -413,3 +423,12 @@ 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 two
+parameters: The name of the page being matched, and the thing to match
+against. It should return true if the page matches.