pagespec_match_list: change limit to filter

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 62bebbeedf28bfe5124c6ff67b0b399cc4094ede..2254d70257dbeb17b58a4a5df6da2d42eea6901a 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -625,23 +625,26 @@ dependency type from one or more of these keywords:
 
 If multiple types are specified, they are combined.
 
 
 If multiple types are specified, they are combined.
 

-#### `use_pagespec($$;@)`
+#### `pagespec_match_list($$;@)`

 
 Passed a page name, and [[ikiwiki/PageSpec]], returns a list of pages
 in the wiki that match the [[ikiwiki/PageSpec]]. 
 
 The page will automatically be made to depend on the specified
 [[ikiwiki/PageSpec]], so `add_depends` does not need to be called. This
 
 Passed a page name, and [[ikiwiki/PageSpec]], returns a list of pages
 in the wiki that match the [[ikiwiki/PageSpec]]. 
 
 The page will automatically be made to depend on the specified
 [[ikiwiki/PageSpec]], so `add_depends` does not need to be called. This

-is significantly more efficient than calling `add_depends`
-followed by `pagespec_match_list`. You should use this anytime a plugin
-needs to match a set of pages and generate something based on that list.
+is significantly more efficient than calling `add_depends` and
+`pagespec_match` in a loop. You should use this anytime a plugin
+needs to match a set of pages and do something based on that list.
+
+Unlike pagespec_match, this may throw an error if there is an error in
+the pagespec.

 
 Additional named parameters can be specified:
 
 * `deptype` optionally specifies the type of dependency to add. Use the
   `deptype` function to generate a dependency type.
 
 Additional named parameters can be specified:
 
 * `deptype` optionally specifies the type of dependency to add. Use the
   `deptype` function to generate a dependency type.

-* `limit` is a reference to a function, that is called and passed a page,
-  and must return true for the page to be included.
+* `filter` is a reference to a function, that is called and passed a page,
+  and returns true if the page should be filtered out of the list.

 * `sort` specifies a sort order for the list. See
   [[ikiwiki/PageSpec/sorting]] for the avilable sort methods.
 * `reverse` if true, sorts in reverse.
 * `sort` specifies a sort order for the list. See
   [[ikiwiki/PageSpec/sorting]] for the avilable sort methods.
 * `reverse` if true, sorts in reverse.


@@ -650,6 +653,9 @@ Additional named parameters can be specified:
 * `list` makes it only match amoung the specified list of pages.
   Default is to match amoung all pages in the wiki.
 
 * `list` makes it only match amoung the specified list of pages.
   Default is to match amoung all pages in the wiki.
 

+Any other named parameters are passed on to `pagespec_match`, to further
+limit the match.
+

 #### `add_depends($$;$)`
 
 Makes the specified page depend on the specified [[ikiwiki/PageSpec]].
 #### `add_depends($$;$)`
 
 Makes the specified page depend on the specified [[ikiwiki/PageSpec]].


@@ -672,19 +678,6 @@ 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 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
 #### `bestlink($$)`
 
 Given a page and the text of a link on the page, determine which