add influence info to match_*

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 133030f08fc5bef55dc7dcf2fbca03add189a2db..6b47033e5c5b18c1415241c6328d19e793797d4e 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -627,9 +627,13 @@ used to indicate weaker types of dependencies:
 
 #### `pagespec_match($$;@)`
 
-Passed a page name, and [[ikiwiki/PageSpec]], returns true if the
+Passed a page name, and [[ikiwiki/PageSpec]], returns a true value if the
 [[ikiwiki/PageSpec]] matches the page.
 
+Note that the return value is overloaded. If stringified, it will be a
+message indicating why the PageSpec succeeded, or failed, to match the
+page.
+
 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
@@ -978,6 +982,13 @@ 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.
 
+When constructing these objects, you should also include a list of any
+pages whose contents or other metadata influenced the result of the match.
+For example, "backlink(foo)" is influenced by the contents of page foo;
+"link(foo)" and "title(bar)" are influenced by the contents of any
+page they match; "created_before(foo)" is influenced by the metadata of
+foo; while "glob(*)" is not influenced by the contents of any page.
+
 ### Setup plugins
 
 The ikiwiki setup file is loaded using a pluggable mechanism. If you look