X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/7e52cc90b21b100571324dad3060259eba66af88..abf90fcbaa014fefcacf98997a7f9465140e0ab9:/doc/plugins/write.mdwn

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 79da6a612..b9d7c01c2 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -142,6 +142,28 @@ format at preprocessor time. Text output by a preprocessor directive will
 be linkified and passed through markdown (or whatever engine is used to
 htmlize the page) along with the rest of the page.
 
+### linkify
+
+	hook(type => "linkify", id => "foo", call => \&linkify);
+
+This hook is called to convert [[WikiLinks|WikiLink]] on the page into html
+links. The function is passed named parameters "page", "destpage", and
+"content". It should return the linkified content.
+
+Plugins that implement linkify must also implement a scan hook, that scans
+for the links on the page and adds them to `%links`.
+
+### scan
+
+	hook(type => "scan", id => "foo", call => \&scan);
+
+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`.
+
+The function is passed named parameters "page" and "content". Its return
+value is ignored.
+
 ### htmlize
 
 	hook(type => "htmlize", id => "ext", call => \&htmlize);
@@ -222,8 +244,11 @@ source files that were rendered.
 
 Use this to hook into ikiwiki's cgi script. Each registered cgi hook is
 called in turn, and passed a CGI object. The hook should examine the
-parameters, and if it will handle this CGI request, output a page (including the http headers) and
-terminate the program.
+parameters, and if it will handle this CGI request, output a page
+(including the http headers) and terminate the program.
+
+Note that cgi hooks are called as early as possible, before any ikiwiki
+state is loaded, and with no session information.
 
 ### auth
 
@@ -478,11 +503,16 @@ If the destination directory doesn't exist, it will first be created.
 
 Given a page name and a destination file name (not including the base
 destination directory), register that the page will result in that file
-being rendered. It's important to call this before writing to any file in
-the destination directory.
+being rendered. 
+
+It's important to call this before writing to any file in the destination
+directory, and it's important to call it consistently every time, even if
+the file isn't really written this time -- unless you delete any old
+version of the file. In particular, in preview mode, this should still be
+called even if the file isn't going to be written to during the preview.
 
 Ikiwiki uses this information to automatically clean up rendered files when
-the page that rendered them goes away or is changes to no longer render
+the page that rendered them goes away or is changed to no longer render
 them. will_render also does a few important security checks.
 
 #### `pagetype($)`
@@ -533,18 +563,16 @@ rendered to.
 
 ## Internal use pages
 
-Sometimes it's useful to put pages in the wiki without having them be
-rendered to individual html files. Such internal use pages are collected
-together to form the RecentChanges page, for example.
+Sometimes it's useful to put pages in the wiki without the overhead of
+having them be rendered to individual html files. Such internal use pages
+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, are
-not scanned for wikilinks (though wikilinks and preprocessor directives can
-appear on them, this is rarely a good idea and should be done with caution),
-and are not matched by regular PageSpecs glob patterns, but instead only by a
-special `internal()` [[ikiwiki/PageSpec]].
-
-Ikiwiki is optimised to handle lots of internal use pages, very quickly.
+with "_". Internal use pages cannot be edited with the web interface,
+generally shouldn't contain wikilinks 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]].
 
 ## RCS plugins