doc update, add --exclude ikiwiki.cgi to examples

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 11ed312aebcfd73f8ec3b3f5cff463e98bfb6696..668f8d8b69dff65acc0727fa5fa3233e516b132a 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -107,8 +107,8 @@ adding or removing files from it.
 
 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
 
 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|ikiwiki/WikiLink]], and add them to `%links`.
-Present in IkiWiki 2.40 and later.
+mostly used to scan the page for [[WikiLinks|ikiwiki/WikiLink]], and add
+them to `%links`. Present in IkiWiki 2.40 and later.

 
 The function is passed named parameters "page" and "content". Its return
 value is ignored.
 
 The function is passed named parameters "page" and "content". Its return
 value is ignored.


@@ -151,11 +151,11 @@ parameter is set to a true value if the page is being previewed.
 If `hook` is passed an optional "scan" parameter, set to a true value, this
 makes the hook be called during the preliminary scan that ikiwiki makes of
 updated pages, before begining to render pages. This should be done if the
 If `hook` is passed an optional "scan" parameter, set to a true value, this
 makes the hook be called during the preliminary scan that ikiwiki makes of
 updated pages, before begining to render pages. This should be done 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 context, you
-can assume it's being run in scan mode, and avoid doing expensive things at
-that point.)
+hook modifies data in `%links` (typically by calling `add_link`). 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 context, you can assume it's being run in scan mode, and
+avoid doing expensive things at that point.)

 
 Note that if the [[htmlscrubber]] is enabled, html in
 preprocessor [[ikiwiki/directive]] output is sanitised, which may limit what
 
 Note that if the [[htmlscrubber]] is enabled, html in
 preprocessor [[ikiwiki/directive]] output is sanitised, which may limit what


@@ -174,7 +174,8 @@ links. The function is passed named parameters "page", "destpage", and
 and later.
 
 Plugins that implement linkify must also implement a scan hook, that scans
 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`.
+for the links on the page and adds them to `%links` (typically by calling
+`add_link`).

 
 ### htmlize
 
 
 ### htmlize
 


@@ -197,6 +198,9 @@ value, then the id parameter specifies not a filename extension, but
 a whole filename that can be htmlized. This is useful for files
 like `Makefile` that have no extension.
 
 a whole filename that can be htmlized. This is useful for files
 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.
+

 ### pagetemplate
 
        hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
 ### pagetemplate
 
        hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);


@@ -326,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.
 
 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);
 ### checkcontent
        
        hook(type => "checkcontent", id => "foo", call => \&checkcontent);


@@ -338,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.
 
 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
 
 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


@@ -390,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
        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
 
 
 ### getsetup
 


@@ -452,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.
 
   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:
 ## Plugin interface
 
 To import the ikiwiki plugin interface:


@@ -572,6 +623,19 @@ 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.
 
 PageSpec should match against. If not passed, relative PageSpecs will match
 relative to the top of the wiki.
 

+#### `pagespec_match_list($$;@)`
+
+Passed a reference to a list of page names, and [[ikiwiki/PageSpec]],
+returns the set of pages that match the [[ikiwiki/PageSpec]].
+
+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.
+
+Unlike pagespec_match, this may throw an error if there is an error in
+the pagespec.
+

 #### `bestlink($$)`
 
 Given a page and the text of a link on the page, determine which
 #### `bestlink($$)`
 
 Given a page and the text of a link on the page, determine which


@@ -584,7 +648,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
 
 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)
 
 
        htmllink($page, $page, $link)
 


@@ -740,6 +804,11 @@ 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`.
 
 filename of the page. For example, `targetpage("foo", "rss", "feed")`
 will yield something like `foo/feed.rss`.
 

+#### `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.
+

 ## Miscellaneous
 
 ### Internal use pages
 ## Miscellaneous
 
 ### Internal use pages


@@ -788,7 +857,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.
 
 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($)`
 `rcs_rename`.
 
 #### `rcs_add($)`


@@ -890,9 +959,12 @@ It's also possible to write plugins that add new functions to
 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
 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.
+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. If the match cannot be
+attempted at all, for any page, it can instead return an
+IkiWiki::ErrorReason object explaining why.

 
 ### Setup plugins
 
 
 ### Setup plugins