From 9169c3247ffae04ae2fbc9ceda4176ffb5f263d3 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@kodama.kitenet.net>
Date: Sat, 26 Jul 2008 13:07:48 -0400
Subject: [PATCH] standardising and documenting getsetup
---
IkiWiki/Plugin/pinger.pm | 2 +-
IkiWiki/Plugin/recentchanges.pm | 2 +-
doc/plugins/write.mdwn | 43 +++++++++++++++++++++++++++++++++
3 files changed, 45 insertions(+), 2 deletions(-)
diff --git a/IkiWiki/Plugin/pinger.pm b/IkiWiki/Plugin/pinger.pm
index 89b4365ab..0aee17f8a 100644
--- a/IkiWiki/Plugin/pinger.pm
+++ b/IkiWiki/Plugin/pinger.pm
@@ -19,7 +19,7 @@ sub import { #{{{
sub getsetup () { #{{{
return
pinger_timeout => {
- type => "int",
+ type => "integer",
default => 15,
description => "how many seconds to try pinging before timing out",
safe => 1,
diff --git a/IkiWiki/Plugin/recentchanges.pm b/IkiWiki/Plugin/recentchanges.pm
index 04a878b20..6ab4f9d03 100644
--- a/IkiWiki/Plugin/recentchanges.pm
+++ b/IkiWiki/Plugin/recentchanges.pm
@@ -24,7 +24,7 @@ sub getsetup () { #{{{
rebuild => 1,
},
recentchangesnum => {
- type => "int",
+ type => "integer",
default => 100,
description => "number of changes to track",
safe => 1,
diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 7c28088de..271d8d641 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -357,6 +357,49 @@ 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:
--
2.39.5