mention that pagespec_match returns an overloaded value
authorJoey Hess <joey@gnu.kitenet.net>
Wed, 7 Oct 2009 22:06:49 +0000 (18:06 -0400)
committerJoey Hess <joey@gnu.kitenet.net>
Wed, 7 Oct 2009 22:06:49 +0000 (18:06 -0400)
doc/plugins/write.mdwn

index 668f8d8b69dff65acc0727fa5fa3233e516b132a..8e8c3311e4a1a23e8e9d1f36f5689e7adba55269 100644 (file)
@@ -609,15 +609,31 @@ page created from it. (Ie, it appends ".html".)
 Use this when constructing the filename of a html file. Use `urlto` when
 generating a link to a page.
 
-#### `add_depends($$)`
+#### `add_depends($$;@)`
 
 Makes the specified page depend on the specified [[ikiwiki/PageSpec]].
 
+By default, dependencies are full content dependencies, meaning that the
+page will be updated whenever anything matching the PageSpec is modified.
+This default can be overridden by additional named parameters, which can be
+used to indicate weaker types of dependencies:
+
+* `presence` if set to true, only the presence of a matching page triggers
+  the dependency.
+* `links` if set to true, any change to links on a matching page
+  triggers the dependency. This includes when a link is added, removed,
+  or changes what it points to due to other changes. It does not include
+  the addition or removal of a duplicate link.
+
 #### `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