rework dependency types code

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index d0f6a09e1ac9127efed521713c5b1be7182ba4d2..73db6f12abfc5432d132a1a77ba2023b05ee79b9 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -330,6 +330,26 @@ 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.
 
+### canremove
+
+       hook(type => "canremove", id => "foo", call => \&canremove);
+
+This hook can be used to implement arbitrary access methods to control
+when a page can be removed using the web interface (commits from
+revision control bypass it). It works exactly like the `canedit` hook,
+but is passed the named parameters `cgi` (a CGI object), `session`
+(a session object) and `page` (the page subject to deletion).
+
+### canrename
+
+       hook(type => "canrename", id => "foo", call => \&canrename);
+
+This hook can be used to implement arbitrary access methods to control when
+a page can be renamed using the web interface (commits from revision control
+bypass it). It works exactly like the `canedit` hook,
+but is passed the named parameters `cgi` (a CGI object), `session` (a
+session object), `src`, `srcfile`, `dest` and `destfile`.
+
 ### checkcontent
        
        hook(type => "checkcontent", id => "foo", call => \&checkcontent);
@@ -342,8 +362,9 @@ the content the user has entered is a comment, it may also be passed some
 additional parameters: `author`, `url`, and `subject`. The `subject`
 parameter may also be filled with the user's comment about the change.
 
-Note: When the user edits an existing wiki page, the passed `content` will
-include only the lines that they added to the page, or modified.
+Note: When the user edits an existing wiki page, this hook is also
+passed a `diff` named parameter, which will include only the lines
+that they added to the page, or modified.
 
 The hook should return `undef` on success. If the content is disallowed, it
 should return a message stating what the problem is, or a function
@@ -394,9 +415,28 @@ they're saved, etc.
        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.
+something, once per page linking to the renamed page's old location.
+The hook is passed named parameters: `page`, `oldpage`, `newpage`, and
+`content`, and should try to modify the content of `page` to reflect
+the name change. For example, by converting links to point to the
+new page.
+
+### rename
+
+       hook(type => "rename", id => "foo", call => \&rename);
+
+When a page or set of pages is renamed, the referenced function is
+called for every page, and is passed named parameters:
+
+* `torename`: a reference to a hash with keys: `src`, `srcfile`,
+  `dest`, `destfile`, `required`.
+* `cgi`: a CGI object
+* `session`: a session object.
+
+Such a hook function returns any additional rename hashes it wants to
+add. This hook is applied recursively to returned additional rename
+hashes, so that it handles the case where two plugins use the hook:
+plugin A would see when plugin B adds a new file to be renamed.
 
 ### getsetup
 
@@ -456,6 +496,13 @@ describes the plugin as a whole. For example:
   and undef if a rebuild could be needed in some circumstances, but is not
   strictly required.
 
+### genwrapper
+
+       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.
+
 ## Plugin interface
 
 To import the ikiwiki plugin interface:
@@ -562,10 +609,20 @@ page created from it. (Ie, it appends ".html".)
 Use this when constructing the filename of a html file. Use `urlto` when
 generating a link to a page.
 
-#### `add_depends($$)`
+#### `add_depends($$;@)`
 
 Makes the specified page depend on the specified [[ikiwiki/PageSpec]].
 
+By default, dependencies are full content dependencies, meaning that the
+page will be updated whenever anything matching the PageSpec is modified.
+This default can be overridden by additional named parameters, which can be
+used to indicate weaker types of dependencies:
+
+* `presence` if set to true, only the presence of a matching page triggers
+  the dependency.
+* `links` if set to true, any change in the text of links on a matching page
+  triggers the dependency
+
 #### `pagespec_match($$;@)`
 
 Passed a page name, and [[ikiwiki/PageSpec]], returns true if the
@@ -601,7 +658,7 @@ pages, as described in [[ikiwiki/SubPage/LinkingRules]].
 
 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` is:
 
        htmllink($page, $page, $link)
 
@@ -810,7 +867,7 @@ of the page with the rcs's conflict markers on failure.
 Passed a message, user, and ip address. 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
+Changes can be staged by calls to `rcs_add`, `rcs_remove`, and
 `rcs_rename`.
 
 #### `rcs_add($)`