filecheck: New plugin factoring out the PageSpec additions that were originally part...

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 77210d35cb8bd8731b42e921f0e5f289546a4f3c..cde0b50fd523302b6d74f8a77064b74d7d813515 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -123,7 +123,7 @@ make arbitrary changes. The function is passed named parameters "page",
 
 ### preprocess
 
-Adding a [[ikiwiki/PreProcessorDirective]] is probably the most common use
+Adding a preprocessor [[ikiwiki/directive]] is probably the most common use
 of a plugin.
 
         hook(type => "preprocess", id => "foo", call => \&preprocess);
@@ -158,7 +158,7 @@ can assume it's being run in scan mode, and avoid doing expensive things at
 that point.)
 
 Note that if the [[htmlscrubber]] is enabled, html in
-[[ikiwiki/PreProcessorDirective]] output is sanitised, which may limit what
+preprocessor [[ikiwiki/directive]] output is sanitised, which may limit what
 your plugin can do. Also, the rest of the page content is not in html
 format at preprocessor time. Text output by a preprocessor directive will
 be linkified and passed through markdown (or whatever engine is used to
@@ -192,6 +192,7 @@ return the htmlized content.
 
        hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
 
+
 [[Templates|wikitemplates]] are filled out for many different things in
 ikiwiki, like generating a page, or part of a blog page, or an rss feed, or
 a cgi. This hook allows modifying the variables available on those
@@ -356,7 +357,7 @@ This hook is called whenever ikiwiki normally saves its state, just before
 the state is saved. The function can save other state, modify values before
 they're saved, etc.
 
-## renamepage
+### renamepage
 
        hook(type => "renamepage", id => "foo", call => \&renamepage);
 
@@ -379,32 +380,49 @@ die if not, which will cause the plugin to not be offered in the configuration
 interface.
 
 The data returned is a list of `%config` options, followed by a hash
-describing the option. For example:
+describing the option. There can also be an item named "plugin", which
+describes the plugin as a whole. For example:
 
                 return
                        option_foo => {
                                type => "boolean",
-                               description => "enable foo",
+                               description => "enable foo?",
+                               advanced => 1,
                                safe => 1,
                                rebuild => 1,
                        },
                        option_bar => {
                                type => "string",
                                example => "hello",
-                               description => "what to say",
+                               description => "option bar",
                                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 the type of
-  the leaf values;  the `%config` option may be an array or hash of these.
+* `type` can be "boolean", "string", "integer", "pagespec",
+  or "internal" (used for values that are not user-visible). The type is
+  the type of the leaf values;  the `%config` option may be an array or
+  hash of these.
 * `example` can be set to an example value.
 * `description` is a short description of the option.
+* `link` is a link to further information about the option. This can either
+  be a wikilink, or an url.
+* `advanced` can be set to true if the option is more suitable for advanced
+  users.
 * `safe` should be false if the option should not be displayed in unsafe
   configuration methods, such as the web interface. Anything that specifies
   a command to run, a path on disk, or a regexp should be marked as unsafe.
-* `rebuild` should be true if changing the option will require a wiki rebuild.
+  If a plugin is marked as unsafe, that prevents it from being
+  enabled/disabled.
+* `rebuild` should be true if changing the option (or enabling/disabling
+  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.
 
 ## Plugin interface
 
@@ -482,7 +500,7 @@ function that is called after the error message is printed, to do any final
 cleanup.
 
 If called inside a preprocess hook, error() does not abort the entire
-wiki build, but instead replaces the [[ikiwiki/PreProcessorDirective]] with
+wiki build, but instead replaces the preprocessor [[ikiwiki/directive]] with
 a version containing the error message.
 
 In other hooks, error() is a fatal error, so use with care. Try to avoid