move security to discussion

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 1a119b99b679498c5188620a56e9d7fce81c5bc6..cccfb9bbaab048e2d04631d13b3b0c740d95c421 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -107,7 +107,7 @@ 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, and add them to `%links`.
+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
 Present in IkiWiki 2.40 and later.
 
 The function is passed named parameters "page" and "content". Its return


@@ -168,7 +168,7 @@ htmlize the page) along with the rest of the page.
 
        hook(type => "linkify", id => "foo", call => \&linkify);
 
 
        hook(type => "linkify", id => "foo", call => \&linkify);
 

-This hook is called to convert [[WikiLinks|WikiLink]] on the page into html
+This hook is called to convert [[WikiLinks|ikiwiki/WikiLink]] on the page into html

 links. The function is passed named parameters "page", "destpage", and
 "content". It should return the linkified content.  Present in IkiWiki 2.40
 and later.
 links. The function is passed named parameters "page", "destpage", and
 "content". It should return the linkified content.  Present in IkiWiki 2.40
 and later.


@@ -189,9 +189,14 @@ The function is passed named parameters: "page" and "content" and should
 return the htmlized content.
 
 If `hook` is passed an optional "keepextension" parameter, set to a true
 return the htmlized content.
 
 If `hook` is passed an optional "keepextension" parameter, set to a true

-value, then this extension will not be stripped from the source filename when
+value, then the extension will not be stripped from the source filename when

 generating the page.
 
 generating the page.
 

+If `hook` is passed an optional "noextension" parameter, set to a true
+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.
+

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


@@ -321,6 +326,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);


@@ -333,8 +358,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


@@ -385,9 +411,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
 


@@ -434,7 +479,7 @@ describes the plugin as a whole. For example:
 * `example` can be set to an example value.
 * `description` is a short description of the option.
 * `link` is a link to further information about the option. This can either
 * `example` can be set to an example value.
 * `description` is a short description of the option.
 * `link` is a link to further information about the option. This can either

-  be a wikilink, or an url.
+  be a [[ikiwiki/WikiLink]], or an url.

 * `advanced` can be set to true if the option is more suitable for advanced
   users.
 * `safe` should be false if the option should not be displayed in unsafe
 * `advanced` can be set to true if the option is more suitable for advanced
   users.
 * `safe` should be false if the option should not be displayed in unsafe


@@ -680,7 +725,7 @@ a wiki page name.
 #### `linkpage($)`
 
 This converts text that could have been entered by the user as a
 #### `linkpage($)`
 
 This converts text that could have been entered by the user as a

-[[WikiLink]] into a wiki page name.
+[[ikiwiki/WikiLink]] into a wiki page name.

 
 #### `srcfile($;$)`
 
 
 #### `srcfile($;$)`
 


@@ -745,7 +790,7 @@ are collected together to form the RecentChanges page, for example.
 
 To make an internal use page, register a filename extension that starts
 with "_". Internal use pages cannot be edited with the web interface,
 
 To make an internal use page, register a filename extension that starts
 with "_". Internal use pages cannot be edited with the web interface,

-generally shouldn't contain wikilinks or preprocessor directives (use
+generally shouldn't contain [[WikiLinks|ikiwiki/WikiLink]] or preprocessor directives (use

 either on them with extreme caution), and are not matched by regular
 PageSpecs glob patterns, but instead only by a special `internal()`
 [[ikiwiki/PageSpec]].
 either on them with extreme caution), and are not matched by regular
 PageSpecs glob patterns, but instead only by a special `internal()`
 [[ikiwiki/PageSpec]].


@@ -914,7 +959,7 @@ or wrap one of the functions.
 For example, your plugin might want to override `displaytime`, to change
 the html markup used when displaying a date. Or it might want to override
 `IkiWiki::formattime`, to change how a date is formatted. Or perhaps you
 For example, your plugin might want to override `displaytime`, to change
 the html markup used when displaying a date. Or it might want to override
 `IkiWiki::formattime`, to change how a date is formatted. Or perhaps you

-want to override `bestlink` and change how ikiwiki deals with WikiLinks.
+want to override `bestlink` and change how ikiwiki deals with [[WikiLinks|ikiwiki/WikiLink]].

 
 By venturing into this territory, your plugin is becoming tightly tied to
 ikiwiki's internals. And it might break if those internals change. But
 
 By venturing into this territory, your plugin is becoming tightly tied to
 ikiwiki's internals. And it might break if those internals change. But