X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/6f9c18f7cbbdc8305c6d4373a9d8a00d0c47af5f..e78883e07fc518cea2315b3765631d747550905a:/doc/plugins/write.mdwn

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index acf9a2cdd..d0f6a09e1 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -90,11 +90,6 @@ function is passed no values. It's ok for the function to call
 
 This hook is called just before ikiwiki scans the wiki for changed files.
 It's useful for plugins that need to create or modify a source page. The
-
-
-
-
-
 function is passed no values.
 
 ### needsbuild
@@ -103,7 +98,7 @@ function is passed no values.
 
 This allows a plugin to manipulate the list of files that need to be
 built when the wiki is refreshed. The function is passed a reference to an
-array of pages that will be rebuilt, and can modify the array, either
+array of files that will be rebuilt, and can modify the array, either
 adding or removing files from it.
 
 ### scan
@@ -112,8 +107,8 @@ adding or removing files from it.
 
 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|ikiwiki/WikiLink]], and add them to `%links`.
-Present in IkiWiki 2.40 and later.
+mostly used to scan the page for [[WikiLinks|ikiwiki/WikiLink]], and add
+them to `%links`. Present in IkiWiki 2.40 and later.
 
 The function is passed named parameters "page" and "content". Its return
 value is ignored.
@@ -156,11 +151,11 @@ parameter is set to a true value if the page is being previewed.
 If `hook` is passed an optional "scan" parameter, set to a true value, this
 makes the hook be called during the preliminary scan that ikiwiki makes of
 updated pages, before begining to render pages. This should be done if the
-hook modifies data in `%links`. Note that doing so will make the hook be
-run twice per page build, so avoid doing it for expensive hooks. (As an
-optimisation, if your preprocessor hook is called in a void context, you
-can assume it's being run in scan mode, and avoid doing expensive things at
-that point.)
+hook modifies data in `%links` (typically by calling `add_link`). Note that
+doing so will make the hook be run twice per page build, so avoid doing it
+for expensive hooks. (As an optimisation, if your preprocessor hook is
+called in a void context, you can assume it's being run in scan mode, and
+avoid doing expensive things at that point.)
 
 Note that if the [[htmlscrubber]] is enabled, html in
 preprocessor [[ikiwiki/directive]] output is sanitised, which may limit what
@@ -179,7 +174,8 @@ links. The function is passed named parameters "page", "destpage", and
 and later.
 
 Plugins that implement linkify must also implement a scan hook, that scans
-for the links on the page and adds them to `%links`.
+for the links on the page and adds them to `%links` (typically by calling
+`add_link`).
 
 ### htmlize
 
@@ -194,9 +190,17 @@ The function is passed named parameters: "page" and "content" and should
 return the htmlized content.
 
 If `hook` is passed an optional "keepextension" parameter, set to a true
-value, then this extension will not be stripped from the source filename when
+value, then the extension will not be stripped from the source filename when
 generating the page.
 
+If `hook` is passed an optional "noextension" parameter, set to a true
+value, then the id parameter specifies not a filename extension, but
+a whole filename that can be htmlized. This is useful for files
+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.
+
 ### pagetemplate
 
 	hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
@@ -572,6 +576,19 @@ The most often used is "location", which specifies the location the
 PageSpec should match against. If not passed, relative PageSpecs will match
 relative to the top of the wiki.
 
+#### `pagespec_match_list($$;@)`
+
+Passed a reference to a list of page names, and [[ikiwiki/PageSpec]],
+returns the set of pages that match the [[ikiwiki/PageSpec]].
+
+Additional named parameters can be passed, to further limit the match.
+The most often used is "location", which specifies the location the
+PageSpec should match against. If not passed, relative PageSpecs will match
+relative to the top of the wiki.
+
+Unlike pagespec_match, this may throw an error if there is an error in
+the pagespec.
+
 #### `bestlink($$)`
 
 Given a page and the text of a link on the page, determine which
@@ -740,6 +757,11 @@ 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`.
 
+#### `add_link($$)`
+
+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.
+
 ## Miscellaneous
 
 ### Internal use pages
@@ -890,9 +912,12 @@ It's also possible to write plugins that add new functions to
 IkiWiki::PageSpec package, that is named `match_foo`, where "foo()" is
 how it will be accessed in a [[ikiwiki/PageSpec]]. The function will be passed
 two parameters: The name of the page being matched, and the thing to match
-against. It may also be passed additional, named parameters. It should return
-a IkiWiki::SuccessReason object if the match succeeds, or an
-IkiWiki::FailReason object if the match fails.
+against. It may also be passed additional, named parameters.
+
+It should return a IkiWiki::SuccessReason object if the match succeeds, or
+an IkiWiki::FailReason object if the match fails. If the match cannot be
+attempted at all, for any page, it can instead return an
+IkiWiki::ErrorReason object explaining why.
 
 ### Setup plugins