situation where rebuild needed

[git.ikiwiki.info.git] / doc / ikiwiki / pagespec.mdwn

diff --git a/doc/ikiwiki/pagespec.mdwn b/doc/ikiwiki/pagespec.mdwn
index d4dd265cc79a9e38701fedc12f787041754c4e48..59a0506d321295ab72bf3ae26feaab32dff15c17 100644 (file)
--- a/doc/ikiwiki/pagespec.mdwn
+++ b/doc/ikiwiki/pagespec.mdwn
@@ -24,29 +24,37 @@ match all pages except for Discussion pages and the SandBox:
 
 Some more elaborate limits can be added to what matches using these functions:
 
 
 Some more elaborate limits can be added to what matches using these functions:
 

-* "`link(page)`" - match only pages that link to a given page (or glob)
-* "`backlink(page)`" - match only pages that a given page links to
-* "`creation_month(month)`" - match only pages created on the given month
+* "`glob(someglob)`" - matches pages and other files that match the given glob.
+  Just writing the glob by itself is actually a shorthand for this function.
+* "`page(glob)`" - like `glob()`, but only matches pages, not other files
+* "`link(page)`" - matches only pages that link to a given page (or glob)
+* "`tagged(tag)`" - matches pages that are tagged or link to the given tag (or
+  tags matched by a glob)
+* "`backlink(page)`" - matches only pages that a given page links to
+* "`creation_month(month)`" - matches only files created on the given month
+  number

 * "`creation_day(mday)`" - or day of the month
 * "`creation_year(year)`" - or year
 * "`creation_day(mday)`" - or day of the month
 * "`creation_year(year)`" - or year

-* "`created_after(page)`" - match only pages created after the given page
+* "`created_after(page)`" - matches only files created after the given page

   was created
   was created

-* "`created_before(page)`" - match only pages created before the given page
+* "`created_before(page)`" - matches only files created before the given page

   was created
   was created

-* "`glob(someglob)`" - match pages that match the given glob. Just writing
-  the glob by itself is actually a shorthand for this function.

 * "`internal(glob)`" - like `glob()`, but matches even internal-use 
   pages that globs do not usually match.
 * "`title(glob)`", "`author(glob)`", "`authorurl(glob)`",
 * "`internal(glob)`" - like `glob()`, but matches even internal-use 
   pages that globs do not usually match.
 * "`title(glob)`", "`author(glob)`", "`authorurl(glob)`",

-  "`license(glob)`", "`copyright(glob)`" - match pages that have the given
-  metadata, matching the specified glob.
+  "`license(glob)`", "`copyright(glob)`", "`guid(glob)`" 
+  - match pages that have the given metadata, matching the specified glob.

 * "`user(username)`" - tests whether a modification is being made by a
   user with the specified username. If openid is enabled, an openid can also
 * "`user(username)`" - tests whether a modification is being made by a
   user with the specified username. If openid is enabled, an openid can also

-  be put here.
+  be put here. Glob patterns can be used in the username. For example, 
+  to match all openid users, use `user(*://*)`

 * "`admin()`" - tests whether a modification is being made by one of the
   wiki admins.
 * "`ip(address)`" - tests whether a modification is being made from the
 * "`admin()`" - tests whether a modification is being made by one of the
   wiki admins.
 * "`ip(address)`" - tests whether a modification is being made from the

-  specified IP address.
+  specified IP address. Glob patterns can be used in the address. For
+  example, `ip(127.0.0.*)`
+* "`comment(glob)`" - matches comments to a page matching the glob.
+* "`comment_pending(glob)`" - matches unmoderated, pending comments.

 * "`postcomment(glob)`" - matches only when comments are being 
   posted to a page matching the specified glob
 
 * "`postcomment(glob)`" - matches only when comments are being 
   posted to a page matching the specified glob
 


@@ -61,11 +69,15 @@ want to combine expression like that; "or" when it's enough for a page to
 match one expression. Note that it doesn't make sense to say "index and
 SandBox", since no page can match both expressions.
 
 match one expression. Note that it doesn't make sense to say "index and
 SandBox", since no page can match both expressions.
 

+If you want to include only one level of subpages, you can use
+
+    blog/* and !blog/*/*
+

 More complex expressions can also be created, by using parentheses for
 grouping. For example, to match pages in a blog that are tagged with either
 of two tags, use:
 
 More complex expressions can also be created, by using parentheses for
 grouping. For example, to match pages in a blog that are tagged with either
 of two tags, use:
 

-       blog/* and (link(tag/foo) or link(tag/bar))
+       blog/* and (tagged(foo) or tagged(bar))

 
 Note that page names in PageSpecs are matched against the absolute
 filenames of the pages in the wiki, so a pagespec "foo" used on page
 
 Note that page names in PageSpecs are matched against the absolute
 filenames of the pages in the wiki, so a pagespec "foo" used on page


@@ -73,21 +85,6 @@ filenames of the pages in the wiki, so a pagespec "foo" used on page
 relative to the directory of the page containing the pagespec, you can
 use "./". For example, "./foo" on page "a/b" matches page "a/foo".
 
 relative to the directory of the page containing the pagespec, you can
 use "./". For example, "./foo" on page "a/b" matches page "a/foo".
 

-## Old syntax
-
-The old PageSpec syntax was called a "GlobList", and worked differently in
-two ways:
-
-1. "and" and "or" were not used; any page matching any item from the list
-   matched.
-2. If an item was prefixed with "`!`", then no page matching that item
-   matched, even if it matched an earlier list item.
-
-For example, here is the old way to match all pages except for the SandBox
-and Discussion pages:
-
-       * !SandBox !*/Discussion
-
-Using this old syntax is still supported. However, the old syntax is
-deprecated and will be removed at some point, and using the new syntax is
-recommended.
+To indicate the name of the page the PageSpec is used in, you can
+use a single dot. For example, `link(.)` matches all the pages
+linking to the page containing the PageSpec.