signature

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 62bebbeedf28bfe5124c6ff67b0b399cc4094ede..082f0e38f589d50d2fd14b5f6637d1ddf6b91869 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -68,20 +68,21 @@ In roughly the order they are called.
 
 This allows for plugins to perform their own processing of command-line
 options and so add options to the ikiwiki command line. It's called during
 
 This allows for plugins to perform their own processing of command-line
 options and so add options to the ikiwiki command line. It's called during

-command line processing, with @ARGV full of any options that ikiwiki was
+command line processing, with `@ARGV` full of any options that ikiwiki was

 not able to process on its own. The function should process any options it
 not able to process on its own. The function should process any options it

-can, removing them from @ARGV, and probably recording the configuration
-settings in %config. It should take care not to abort if it sees
+can, removing them from `@ARGV`, and probably recording the configuration
+settings in `%config`. It should take care not to abort if it sees

 an option it cannot process, and should just skip over those options and
 an option it cannot process, and should just skip over those options and

-leave them in @ARGV.
+leave them in `@ARGV`.

 
 ### checkconfig
 
        hook(type => "checkconfig", id => "foo", call => \&checkconfig);
 
 This is useful if the plugin needs to check for or modify ikiwiki's
 
 ### checkconfig
 
        hook(type => "checkconfig", id => "foo", call => \&checkconfig);
 
 This is useful if the plugin needs to check for or modify ikiwiki's

-configuration. It's called early in the startup process. The
-function is passed no values. It's ok for the function to call
+configuration. It's called early in the startup process. `%config`
+is populated at this point, but other state has not yet been loaded.
+The function is passed no values. It's ok for the function to call

 `error()` if something isn't configured right.
 
 ### refresh
 `error()` if something isn't configured right.
 
 ### refresh


@@ -201,6 +202,17 @@ 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.
 
 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.
 

+### postscan
+
+       hook(type => "postscan", id => "foo", call => \&postscan);
+
+This hook is called once the page has been converted to html (but before
+the generated html is put in a template). The most common use is to
+update search indexes. Added in ikiwiki 2.54.
+
+The function is passed named parameters "page" and "content". Its return
+value is ignored.
+

 ### pagetemplate
 
        hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
 ### pagetemplate
 
        hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);


@@ -237,17 +249,6 @@ modify the body of a page after it has been fully converted to html.
 The function is passed named parameters: "page", "destpage", and "content",
 and should return the sanitized content.
 
 The function is passed named parameters: "page", "destpage", and "content",
 and should return the sanitized content.
 

-### postscan
-
-       hook(type => "postscan", id => "foo", call => \&postscan);
-
-This hook is called once the full page body is available (but before the
-format hook). The most common use is to update search indexes. Added in
-ikiwiki 2.54.
-
-The function is passed named parameters "page" and "content". Its return
-value is ignored.
-

 ### format
 
        hook(type => "format", id => "foo", call => \&format);
 ### format
 
        hook(type => "format", id => "foo", call => \&format);


@@ -625,23 +626,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 often 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 +654,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 +679,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


@@ -719,6 +713,7 @@ control some options. These are:
 * anchor - set to make the link include an anchor
 * rel - set to add a rel attribute to the link
 * class - set to add a css class to the link
 * anchor - set to make the link include an anchor
 * rel - set to add a rel attribute to the link
 * class - set to add a css class to the link

+* title - set to add a title attribute to the link

 
 #### `readfile($;$)`
 
 
 #### `readfile($;$)`