standardising and documenting getsetup

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 22bd5d114872a62e80f29c7e3ab9d6bdf10f3a42..271d8d64167cf8e0c6e3e16e8e64977af061a5e3 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -348,6 +348,58 @@ 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.
 
 the state is saved. The function can save other state, modify values before
 they're saved, etc.
 

+## renamepage
+
+       hook(type => "renamepage", id => "foo", call => \&renamepage);
+
+This hook is called by the [[plugins/rename]] plugin when it renames
+something. The hook is passed named parameters: `page`, `oldpage`,
+`newpage`, and `content`, and should try to modify the content to reflect
+the name change. For example, by converting links to point to the new page.
+
+### getsetup
+
+       hook(type => "getsetup", id => "foo", call => \&getsetup);
+
+This hooks is not called during normal operation, but only when setting up 
+the wiki, or generating a setup file. Plugins can use this hook to add
+configuration options.
+
+The hook is passed no parameters. It returns data about the configuration
+options added by the plugin. It can also check if the plugin is usable, and
+die if the plugin is not available, 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:
+
+                return
+                       option_foo => {
+                               type => "boolean",
+                               default => 0,
+                               description => "enable foo",
+                               safe => 1,
+                               rebuild => 1,
+                       },
+                       option_bar => {
+                               type => "string",
+                               example => "hello",
+                               description => "what to say",
+                               safe => 1,
+                               rebuild => 0,
+                       },
+
+* `type` can be "boolean", "string", "integer", or `undef` (use for complex
+  types). Note that the type is the type of the leaf values; the `%config`
+  option may be an array or hash of these.
+* `default` should be set to the default value of the option, if any.
+* `example` can be set to an example value, which will not be used by default.
+* `description` is a short description of the option.
+* `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.
+

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


@@ -573,12 +625,15 @@ time.
 
 This is the standard gettext function, although slightly optimised.
 
 
 This is the standard gettext function, although slightly optimised.
 

-#### `urlto($$)`
+#### `urlto($$;$)`

 
 Construct a relative url to the first parameter from the page named by the
 second. The first parameter can be either a page name, or some other
 destination file, as registered by `will_render`.
 
 
 Construct a relative url to the first parameter from the page named by the
 second. The first parameter can be either a page name, or some other
 destination file, as registered by `will_render`.
 

+If the third parameter is passed and is true, an absolute url will be
+constructed instead of the default relative url.
+

 #### `targetpage($$)`
 
 Passed a page and an extension, returns the filename that page will be
 #### `targetpage($$)`
 
 Passed a page and an extension, returns the filename that page will be


@@ -635,4 +690,5 @@ when imported, populate `$IkiWiki::Setup::raw_setup` with a reference
 to a hash containing all the config items.
 
 By the way, to parse a ikiwiki setup file, a program just needs to
 to a hash containing all the config items.
 
 By the way, to parse a ikiwiki setup file, a program just needs to

-do something like `use IkiWiki::Setup; my %setup=IkiWiki::Setup::load($filename)`
+do something like:
+`use IkiWiki::Setup; my %setup=IkiWiki::Setup::load($filename)`