(no commit message)

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 3976f9adf5a74b504b66efa8478e4d0acc2ebd6e..45f083b423ca5b88117ce604ba5248431d6b32a3 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -201,6 +201,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 +248,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);


@@ -496,6 +496,13 @@ describes the plugin as a whole. For example:
   and undef if a rebuild could be needed in some circumstances, but is not
   strictly required.
 
   and undef if a rebuild could be needed in some circumstances, but is not
   strictly required.
 

+### genwrapper
+
+       hook(type => "genwrapper", id => "foo", call => \&genwrapper);
+
+This hook is used to inject C code (which it returns) into the `main`
+function of the ikiwiki wrapper when it is being generated.
+

 ## Plugin interface
 
 To import the ikiwiki plugin interface:
 ## Plugin interface
 
 To import the ikiwiki plugin interface:


@@ -602,33 +609,75 @@ 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.
 
 Use this when constructing the filename of a html file. Use `urlto` when
 generating a link to a page.
 

-#### `add_depends($$)`
+### `deptype(@)`
+
+Use this function to generate ikiwiki's internal representation of a
+dependency type from one or more of these keywords:
+
+* `content` is the default. Any change to the content
+  of a page triggers the dependency.
+* `presence` is only triggered by a change to the presence
+  of a page.
+* `links` is only triggered by a change to the links of a page.
+  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.
+
+If multiple types are specified, they are combined.
+
+#### `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
+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.
+* `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.
+* `num` if nonzero, specifies the maximum number of matching pages that
+  will be returned.
+* `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]].
 
 
 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 can be overridden by passing a `deptype` value as the third parameter.
+

 #### `pagespec_match($$;@)`
 
 #### `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.
 
 [[ikiwiki/PageSpec]] matches 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
-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]].
+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
 relative to the top of the wiki.
 
 
 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


@@ -663,6 +712,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($;$)`
 


@@ -959,6 +1009,15 @@ 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.
 
 attempted at all, for any page, it can instead return an
 IkiWiki::ErrorReason object explaining why.
 

+When constructing these objects, you should also include information about
+of any pages whose contents or other metadata influenced the result of the
+match. Do this by passing a list of pages, followed by `deptype` values.
+
+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
 ### Setup plugins
 
 The ikiwiki setup file is loaded using a pluggable mechanism. If you look