This extension should go into "todo", shouldn't it? (Also tagged the page.)

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index dcab041dc285b0ae9214a629c692d1f8e747b7d9..4c66e51f865dc4f0490a18d9426286909dfd2d5e 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -1,4 +1,4 @@
-lkiwiki's plugin interface allows all kinds of useful [[plugins]] to be
+Ikiwiki's plugin interface allows all kinds of useful [[plugins]] to be

 written to extend ikiwiki in many ways. Despite the length of this page,
 it's not really hard. This page is a complete reference to everything a
 plugin might want to do. There is also a quick [[tutorial]].
 written to extend ikiwiki in many ways. Despite the length of this page,
 it's not really hard. This page is a complete reference to everything a
 plugin might want to do. There is also a quick [[tutorial]].


@@ -356,21 +356,48 @@ when the page is being previewed.)
 The function is passed named parameters: "page" and "content", and 
 should return the formatted content.
 
 The function is passed named parameters: "page" and "content", and 
 should return the formatted content.
 

+### build_affected
+
+       hook(type => "build_affected", id => "foo", call => \&build_affected);
+
+This hook is called after the directly changed pages have been built,
+and can cause extra pages to be built. If links and backlinks were provided
+by a plugin, this would be where that plugin would rebuild pages whose
+backlinks have changed, for instance. The [[trail]] plugin uses this hook
+to rebuild pages whose next or previous page has changed.
+
+The function should currently ignore its parameters. It returns a list with
+an even number of items (a hash in list context), where the first item of
+each pair is a page name to be rebuilt (if it was not already rebuilt), and
+the second is a log message resembling
+`building plugins/write because the phase of the moon has changed`.
+

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

-Each time a page or pages is removed from the wiki, the referenced function
+After a page or pages is removed from the wiki, the referenced function

 is called, and passed the names of the source files that were removed.
 
 is called, and passed the names of the source files that were removed.
 

-### change
+### rendered

 
 

-       hook(type => "change", id => "foo", call => \&render);
+       hook(type => "rendered", id => "foo", call => \&rendered);

 
 

-Each time ikiwiki renders a change or addition (but not deletion) to the
+After ikiwiki renders a change or addition (but not deletion) to the

 wiki, the referenced function is called, and passed the names of the
 source files that were rendered.
 
 wiki, the referenced function is called, and passed the names of the
 source files that were rendered.
 

+(This hook used to be called "change", but that was not accurate.
+For now, plugins using the old hook name will still work.)
+
+### changes
+
+       hook(type => "changes", id => "foo", call => \&changes);
+
+After ikiwiki renders changes to the wiki, the referenced function is
+called, and passed the names of the source files that were added, modified,
+or deleted.
+

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