X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/bab8fec52468b780485bdf96a37a593bd033c7e3..c9f8fef594e3d820ce4251737e3152e4ffaae528:/doc/plugins/write.mdwn?ds=sidebyside

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 05ddf2215..193005565 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -39,7 +39,7 @@ built.
 Now that it knows what pages it needs to build, ikiwiki runs two
 compile passes. First, it runs `scan` hooks, which collect metadata about
 the pages. Then it runs a page rendering pipeline, by calling in turn these
-hooks: `filter`, `preprocess`, `linkify`, `htmlize`, `postscan`,
+hooks: `filter`, `preprocess`, `linkify`, `htmlize`, `indexhtml`,
 `pagetemplate`, `sanitize`, `format`.
 
 After all necessary pages are built, it calls the `change` hook. Finally,
@@ -282,22 +282,22 @@ 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.
 
-### postscan
+### indexhtml
 
-	hook(type => "postscan", id => "foo", call => \&postscan);
+	hook(type => "indexhtml", id => "foo", call => \&indexhtml);
 
 This hook is called once the page has been converted to html (but before
 the generated html is put in a template). The most common use is to
 update search indexes. Added in ikiwiki 2.54.
 
-The function is passed named parameters "page" and "content". Its return
-value is ignored.
+The function is passed named parameters "page", "destpage", and "content".
+Its return value is ignored.
 
 ### pagetemplate
 
 	hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
 
-[[Templates|wikitemplates]] are filled out for many different things in
+[[Templates]] are filled out for many different things in
 ikiwiki, like generating a page, or part of a blog page, or an rss feed, or
 a cgi. This hook allows modifying the variables available on those
 templates. The function is passed named parameters. The "page" and
@@ -313,11 +313,20 @@ a new custom parameter to the template.
 
 	hook(type => "templatefile", id => "foo", call => \&templatefile);
 
-This hook allows plugins to change the [[template|wikitemplates]] that is
+This hook allows plugins to change the [[template|templates]] that is
 used for a page in the wiki. The hook is passed a "page" parameter, and
-should return the name of the template file to use, or undef if it doesn't
-want to change the default ("page.tmpl"). Template files are looked for in
-/usr/share/ikiwiki/templates by default.
+should return the name of the template file to use (relative to the
+template directory), or undef if it doesn't want to change the default
+("page.tmpl").
+
+### pageactions
+
+	hook(type => "pageactions", id => "foo", call => \&pageactions);
+
+This hook allows plugins to add arbitrary actions to the action bar on a
+page (next to Edit, RecentChanges, etc). The hook is passed a "page"
+parameter, and can return a list of html fragments to add to the action
+bar.
 
 ### sanitize
 
@@ -701,10 +710,29 @@ the entire wiki build and make the wiki unusable.
 
 ### `template($;@)`
 
-Creates and returns a [[!cpan HTML::Template]] object. The first parameter
-is the name of the file in the template directory. The optional remaining
+Creates and returns a [[!cpan HTML::Template]] object. (In a list context,
+returns the parameters needed to construct the obhect.) 
+
+The first parameter is the name of the template file. The optional remaining
 parameters are passed to `HTML::Template->new`.
 
+Normally, the template file is first looked for in the templates/ subdirectory
+of the srcdir. Failing that, it is looked for in the templatedir.
+
+Wiki pages can be used as templates. This should be done only for templates
+which it is safe to let wiki users edit. Enable it by passing a filename
+with no ".tmpl" extension. Template pages are normally looked for in
+the templates/ directory. If the page name starts with "/", a page
+elsewhere in the wiki can be used.
+
+### `template_depends($$;@)`
+
+Use this instead of `template()` if the content of a template is being
+included into a page. This causes the page to depend on the template,
+so it will be updated if the template is modified.
+
+Like `template()`, except the second parameter is the page.
+
 ### `htmlpage($)`
 
 Passed a page name, returns the base name that will be used for a the html
@@ -734,7 +762,10 @@ Additional named parameters can be specified:
 * `filter` is a reference to a function, that is called and passed a page,
   and returns true if the page should be filtered out of the list.
 * `sort` specifies a sort order for the list. See
-  [[ikiwiki/PageSpec/sorting]] for the avilable sort methods.
+  [[ikiwiki/PageSpec/sorting]] for the avilable sort methods. Note that
+  if a sort method is specified that depends on the
+  page content (such as 'meta(foo)'), the deptype needs to be set to
+  a content dependency.
 * `reverse` if true, sorts in reverse.
 * `num` if nonzero, specifies the maximum number of matching pages that
   will be returned.
@@ -916,13 +947,16 @@ search for files.
 If the directory name is not absolute, ikiwiki will assume it is in
 the parent directory of the configured underlaydir.
 
-### `displaytime($;$)`
+### `displaytime($;$$)`
 
 Given a time, formats it for display.
 
 The optional second parameter is a strftime format to use to format the
 time.
 
+If the third parameter is true, this is the publication time of a page.
+(Ie, set the html5 pubdate attribute.)
+
 ### `gettext`
 
 This is the standard gettext function, although slightly optimised.
@@ -963,6 +997,23 @@ added. Pass it the page that contains the link, and the link text.
 An optional third parameter sets the link type. If not specified,
 it is an ordinary [[ikiwiki/WikiLink]].
 
+### `add_autofile($$$)`
+
+Sometimes you may want to add a file to the `srcdir` as a result of content
+of other pages. For example, [[plugins/tag]] pages can be automatically
+created as needed. This function can be used to do that. 
+
+The three parameters are the filename to create (relative to the `srcdir`),
+the name of the plugin, and a callback function. The callback will be
+called if it is appropriate to automatically add the file, and should then
+take care of creating it, and doing anything else it needs to (such as
+checking it into revision control). Note that the callback may not always
+be called. For example, if an automatically added file is deleted by the
+user, ikiwiki will avoid re-adding it again.
+
+This function needs to be called during the scan hook, or earlier in the
+build process, in order to add the file early enough for it to be built.
+
 ## Miscellaneous
 
 ### Internal use pages
@@ -1082,6 +1133,17 @@ it up in the history.
 
 It's ok if this is not implemented, and throws an error.
 
+If the RCS cannot determine a ctime for the file, return 0.
+
+#### `rcs_getmtime($)`
+
+This is used to get the page modification time for a file from the RCS, by
+looking it up in the history.
+
+It's ok if this is not implemented, and throws an error.
+
+If the RCS cannot determine a mtime for the file, return 0.
+
 #### `rcs_receive()`
 
 This is called when ikiwiki is running as a pre-receive hook (or