fix transition call

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 9e27cc27f8103cecd315d506d4d3f6b2941ccd7a..b9d7c01c2367147b3c7771ca312e8a5b3193e82e 100644 (file)
--- 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);
@@ -151,11 +173,6 @@ specifies the filename extension that a file must have to be htmlized using
 this plugin. This is how you can add support for new and exciting markup
 languages to ikiwiki.
 
-Note that if you choose a filename extension that starts with "_",
-ikiwiki will not render the page, or allow the page to be edited with the
-web interface. This is useful for certian types of internal-use pages, but
-should generally be avoided.
-
 The function is passed named parameters: "page" and "content" and should
 return the htmlized content.
 
@@ -227,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
 
@@ -483,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($)`
@@ -536,6 +561,19 @@ destination file, as registered by `will_render`.
 Passed a page and an extension, returns the filename that page will be
 rendered to.
 
+## Internal use pages
+
+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,
+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
 
 ikiwiki's support for [[revision_control_systems|rcs]] also uses pluggable