format plugin categorization

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index f6ea76c3607fca1104ae9d999799d8e693c598ca..68454d56c70ffd75970f4b70fb2942a389008cc0 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);


@@ -456,6 +457,12 @@ describing the option. There can also be an item named "plugin", which
 describes the plugin as a whole. For example:
 
                 return
 describes the plugin as a whole. For example:
 
                 return

+                       plugin => {
+                               description => "description of this plugin",
+                               safe => 1,
+                               rebuild => 1,
+                               section => "misc",
+                       },

                        option_foo => {
                                type => "boolean",
                                description => "enable foo?",
                        option_foo => {
                                type => "boolean",
                                description => "enable foo?",


@@ -470,11 +477,6 @@ describes the plugin as a whole. For example:
                                safe => 1,
                                rebuild => 0,
                        },
                                safe => 1,
                                rebuild => 0,
                        },

-                       plugin => {
-                               description => "description of this plugin",
-                               safe => 1,
-                               rebuild => 1,
-                       },

 
 * `type` can be "boolean", "string", "integer", "pagespec",
   or "internal" (used for values that are not user-visible). The type is
 
 * `type` can be "boolean", "string", "integer", "pagespec",
   or "internal" (used for values that are not user-visible). The type is


@@ -495,6 +497,8 @@ describes the plugin as a whole. For example:
   the plugin) will require a wiki rebuild, false if no rebuild is needed,
   and undef if a rebuild could be needed in some circumstances, but is not
   strictly required.
   the plugin) will require a wiki rebuild, false if no rebuild is needed,
   and undef if a rebuild could be needed in some circumstances, but is not
   strictly required.

+* `section` can optionally specify which section in the config file
+  the plugin fits in.

 
 ### genwrapper
 
 
 ### genwrapper
 


@@ -632,16 +636,19 @@ 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
 
 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` and
+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.
 
 `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,8 +657,8 @@ 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.
 

-Unlike pagespec_match, this may throw an error if there is an error in
-the pagespec.
+Any other named parameters are passed on to `pagespec_match`, to further
+limit the match.

 
 #### `add_depends($$;$)`
 
 
 #### `add_depends($$;$)`
 


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