]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blobdiff - doc/plugins/write.mdwn
wrappers option is not needed, obsolete
[git.ikiwiki.info.git] / doc / plugins / write.mdwn
index faf1643587078e1ae69ff421cb5510c2421073de..6d5056162a557144865d81516e36d3ded51e540b 100644 (file)
@@ -367,8 +367,8 @@ 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
 
 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.
+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:
 
 The data returned is a list of `%config` options, followed by a hash
 describing the option. For example:
@@ -376,7 +376,6 @@ describing the option. For example:
                 return
                        option_foo => {
                                type => "boolean",
                 return
                        option_foo => {
                                type => "boolean",
-                               default => 0,
                                description => "enable foo",
                                safe => 1,
                                rebuild => 1,
                                description => "enable foo",
                                safe => 1,
                                rebuild => 1,
@@ -390,11 +389,9 @@ describing the option. For example:
                        },
 
 * `type` can be "boolean", "string", "integer", "internal" (used for values
                        },
 
 * `type` can be "boolean", "string", "integer", "internal" (used for values
-  that are not user-visible) 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.
+  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.
 * `safe` should be false if the option should not be displayed in unsafe
   configuration methods, such as the web interface. Anything that specifies
 * `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
@@ -420,7 +417,7 @@ it's not exported, the wise choice is to not use it.
 
 A plugin can access the wiki's configuration via the `%config`
 hash. The best way to understand the contents of the hash is to look at
 
 A plugin can access the wiki's configuration via the `%config`
 hash. The best way to understand the contents of the hash is to look at
-[[ikiwiki.setup]], which sets the hash content to configure the wiki.
+your ikiwiki setup file, which sets the hash content to configure the wiki.
 
 ### %pagestate
 
 
 ### %pagestate
 
@@ -657,15 +654,107 @@ PageSpecs glob patterns, but instead only by a special `internal()`
 
 ### RCS plugins
 
 
 ### RCS plugins
 
-ikiwiki's support for [[revision_control_systems|rcs]] also uses pluggable
-perl modules. These are in the `IkiWiki::RCS` namespace, for example
-`IkiWiki::RCS::svn`. 
+ikiwiki's support for [[revision_control_systems|rcs]] is also done via
+plugins. See [[RCS_details|rcs/details]] for some more info.
 
 
-Each RCS plugin must support all the `IkiWiki::rcs_*` functions.
-See IkiWiki::RCS::Stub for the full list of functions. It's ok if
-`rcs_getctime` does nothing except for throwing an error.
+RCS plugins must register a number of hooks. Each hook has type 'rcs', 
+and the 'id' field is set to the name of the hook. For example:
+       
+       hook(type => "rcs", id => "rcs_update", call => \&rcs_update);
+       hook(type => "rcs", id => "rcs_prepedit", call => \&rcs_prepedit);
 
 
-See [[RCS_details|rcs/details]] for some more info.
+#### `rcs_update()`
+
+Updates the working directory with any remote changes.
+
+#### `rcs_prepedit($)`
+
+Is passed a file to prepare to edit. It can generate and return an arbitrary
+token, that will be passed into `rcs_commit` when committing. For example,
+it might return the current revision ID of the file, and use that
+information later when merging changes.
+
+#### `rcs_commit($$$;$$)`
+
+Passed a file, message, token (from `rcs_prepedit`), user, and ip address.
+Should try to commit the file. Returns `undef` on *success* and a version
+of the page with the rcs's conflict markers on failure.
+
+#### `rcs_commit_staged($$$)`
+
+Passed a message, user, and ip address. Should commit all staged changes.
+Returns undef on success, and an error message on failure.
+
+Changes can be staged by calls to `rcs_add, `rcs_remove`, and
+`rcs_rename`.
+
+#### `rcs_add($)`
+
+Adds the passed file to the archive. The filename is relative to the root
+of the srcdir.
+
+Note that this should not check the new file in, it should only
+prepare for it to be checked in when rcs_commit (or `rcs_commit_staged`) is
+called. Note that the file may be in a new subdir that is not yet in
+to version control; the subdir can be added if so.
+
+#### `rcs_remove($)`
+
+Remove a file. The filename is relative to the root of the srcdir.
+
+Note that this should not check the removal in, it should only prepare for it
+to be checked in when `rcs_commit` (or `rcs_commit_staged`) is called. Note
+that the new file may be in a new subdir that is not yet inversion
+control; the subdir can be added if so.
+
+#### `rcs_rename($$)`
+
+Rename a file. The filenames are relative to the root of the srcdir.
+
+Note that this should not commit the rename, it should only
+prepare it for when `rcs_commit` (or `rcs_commit_staged`) is called.
+The new filename may be in a new subdir, that is not yet added to
+version control. If so, the subdir will exist already, and should
+be added to revision control.
+
+#### `rcs_recentchanges($)`
+
+Examine the RCS history and generate a list of recent changes.
+The parameter is how many changes to return.
+
+The data structure returned for each change is:
+
+       {
+               rev => # the RCSs id for this commit
+               user => # name of user who made the change,
+               committype => # either "web" or the name of the rcs,
+               when => # time when the change was made,
+               message => [
+                       { line => "commit message line 1" },
+                       { line => "commit message line 2" },
+                       # etc,
+               ],
+               pages => [
+                       {
+                               page => # name of page changed,
+                               diffurl => # optional url to a diff of changes
+                       },
+                       # repeat for each page changed in this commit,
+               ],
+       }
+
+#### `rcs_diff($)`
+
+The parameter is the rev from `rcs_recentchanges`.
+Should return a list of lines of the diff (including \n) in list
+context, and the whole diff in scalar context.
+
+#### `rcs_getctime($)`
+
+This is used to get the page creation time for a file from the RCS, by looking
+it up in the history.
+
+It's ok if this is not implemented, and throws an error.
 
 ### PageSpec plugins
 
 
 ### PageSpec plugins
 
@@ -680,15 +769,15 @@ IkiWiki::FailReason object if the match fails.
 
 ### Setup plugins
 
 
 ### Setup plugins
 
-The ikiwiki setup file is loaded using a pluggable mechanism. If you
-look at the top of [[ikiwiki.setup]], it starts with 
-'use IkiWiki::Setup::Standard', and the rest of the file is passed to
-that module's import method.
+The ikiwiki setup file is loaded using a pluggable mechanism. If you look
+at the top of a setup file, it starts with 'use IkiWiki::Setup::Standard',
+and the rest of the file is passed to that module's import method.
 
 It's possible to write other modules in the `IkiWiki::Setup::` namespace that
 can be used to configure ikiwiki in different ways. These modules should,
 when imported, populate `$IkiWiki::Setup::raw_setup` with a reference
 
 It's possible to write other modules in the `IkiWiki::Setup::` namespace that
 can be used to configure ikiwiki in different ways. These modules should,
 when imported, populate `$IkiWiki::Setup::raw_setup` with a reference
-to a hash containing all the config items.
+to a hash containing all the config items. They should also implement a
+`gendump` function.
 
 By the way, to parse a ikiwiki setup file, a program just needs to
 do something like:
 
 By the way, to parse a ikiwiki setup file, a program just needs to
 do something like: