po/todo: reflect current status of links-related work

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 82b377820c248ec946237529caf6c5f792469c38..d024a5dd47b6fe9066ece1413ad97e241536ba11 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -55,8 +55,8 @@ plugin, and a "call" parameter, which tells what function to call for the
 hook.
 
 An optional "last" parameter, if set to a true value, makes the hook run
-after all other hooks of its type. Useful if the hook depends on some other
-hook being run first.
+after all other hooks of its type, and an optional "first" parameter makes
+it run first. Useful if the hook depends on some other hook being run first.
 
 ## Types of hooks
 
@@ -360,14 +360,25 @@ This hook is called whenever ikiwiki normally saves its state, just before
 the state is saved. The function can save other state, modify values before
 they're saved, etc.
 
-### renamepage
+### renamelink
 
-       hook(type => "renamepage", id => "foo", call => \&renamepage);
+       hook(type => "renamelink", id => "foo", call => \&renamelink);
 
 This hook is called by the [[plugins/rename]] plugin when it renames
-something. The hook is passed named parameters: `page`, `oldpage`,
-`newpage`, and `content`, and should try to modify the content to reflect
-the name change. For example, by converting links to point to the new page.
+something, once per page linking to the renamed page's old location.
+The hook is passed named parameters: `page`, `oldpage`, `newpage`, and
+`content`, and should try to modify the content of `page` to reflect
+the name change. For example, by converting links to point to the
+new page.
+
+### rename
+
+       hook(type => "rename", id => "foo", call => \&renamepages);
+
+When a page or set of pages is renamed, the referenced function is
+called, and passed a reference to an array of hashes with keys:
+`src`, `srcfile`, `dest`, `destfile`, `required`. It can modify
+the array.
 
 ### getsetup
 
@@ -427,25 +438,6 @@ describes the plugin as a whole. For example:
   and undef if a rebuild could be needed in some circumstances, but is not
   strictly required.
 
-### targetpage
-
-       hook(type => "targetpage", id => "foo", call => \&targetpage);
-
-This hook can be used to override the name of the file a page should
-be compiled into. 
-
-It should return the target filename.
-
-### tweakurlpath
-
-       hook(type => "tweakurlpath", id => "foo", call => \&tweakurlpath);
-
-This hook can be used to modify the internal urls generated by
-ikiwiki; it is run just after ikiwiki has removed the trailing
-`index.html`, in case `usedirs` is enabled.
-
-It should return the modified url.
-
 ## Plugin interface
 
 To import the ikiwiki plugin interface:
@@ -715,11 +707,15 @@ This can be called when creating a new page, to determine what filename
 to save the page to. It's passed a page name, and its type, and returns
 the name of the file to create, relative to the srcdir.
 
-#### `targetpage($$)`
+#### `targetpage($$;$)`
 
 Passed a page and an extension, returns the filename that page will be
 rendered to.
 
+Optionally, a third parameter can be passed, to specify the preferred
+filename of the page. For example, `targetpage("foo", "rss", "feed")`
+will yield something like `foo/feed.rss`.
+
 ## Miscellaneous
 
 ### Internal use pages