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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index fe7cf0183..9128c7f54 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -297,7 +297,7 @@ value is ignored.
 
 	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,11 @@ 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").
 
 ### sanitize
 
@@ -702,8 +702,25 @@ 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
-parameters are passed to `HTML::Template->new`.
+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($)`
 
@@ -734,7 +751,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.
@@ -960,8 +980,25 @@ will yield something like `foo/feed.rss`.
 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.
 
-An optional third parameter sets the link type (`undef` produces an ordinary
-[[ikiwiki/WikiLink]]).
+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
 
@@ -1082,6 +1119,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
@@ -1129,6 +1177,24 @@ For example, "backlink(foo)" is influenced by the contents of page foo;
 they match; "created_before(foo)" is influenced by the metadata of foo;
 while "glob(*)" is not influenced by the contents of any page.
 
+### Sorting plugins
+
+Similarly, it's possible to write plugins that add new functions as
+[[ikiwiki/pagespec/sorting]] methods. To achieve this, add a function to
+the IkiWiki::SortSpec package named `cmp_foo`, which will be used when sorting
+by `foo` or `foo(...)` is requested.
+
+The names of pages to be compared are in the global variables `$a` and `$b`
+in the IkiWiki::SortSpec package. The function should return the same thing
+as Perl's `cmp` and `<=>` operators: negative if `$a` is less than `$b`,
+positive if `$a` is greater, or zero if they are considered equal. It may
+also raise an error using `error`, for instance if it needs a parameter but
+one isn't provided.
+
+The function will also be passed one or more parameters. The first is
+`undef` if invoked as `foo`, or the parameter `"bar"` if invoked as `foo(bar)`;
+it may also be passed additional, named parameters.
+
 ### Setup plugins
 
 The ikiwiki setup file is loaded using a pluggable mechanism. If you look