Merge branch 'ready/tag-test' into transient-tag

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 10b4df835f9fde4eac70f6980727fbad8a7aa562..f0f79ebc7faf58013847674e5855e7a64ab0888d 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -1,4 +1,4 @@
-Ikiwiki's plugin interface allows all kinds of useful [[plugins]] to be
+lkiwiki's plugin interface allows all kinds of useful [[plugins]] to be

 written to extend ikiwiki in many ways. Despite the length of this page,
 it's not really hard. This page is a complete reference to everything a
 plugin might want to do. There is also a quick [[tutorial]].
 written to extend ikiwiki in many ways. Despite the length of this page,
 it's not really hard. This page is a complete reference to everything a
 plugin might want to do. There is also a quick [[tutorial]].


@@ -177,10 +177,15 @@ function is passed no values.
 
        hook(type => "needsbuild", id => "foo", call => \&needsbuild);
 
 
        hook(type => "needsbuild", id => "foo", call => \&needsbuild);
 

-This allows a plugin to manipulate the list of files that need to be
-built when the wiki is refreshed. The function is passed a reference to an
-array of files that will be rebuilt, and can modify the array, either
-adding or removing files from it.
+This allows a plugin to observe or even manipulate the list of files that
+need to be built when the wiki is refreshed. 
+
+As its first parameter, the function is passed a reference to an array of
+files that will be built. It should return an array reference that is a
+modified version of its input. It can add or remove files from it.
+
+The second parameter passed to the function is a reference to an array of
+files that have been deleted.

 
 ### scan
 
 
 ### scan
 


@@ -735,6 +740,8 @@ with no ".tmpl" extension. Template pages are normally looked for in
 the templates/ directory. If the page name starts with "/", a page
 elsewhere in the wiki can be used.
 
 the templates/ directory. If the page name starts with "/", a page
 elsewhere in the wiki can be used.
 

+If the template is not found, or contains a syntax error, an error is thrown.
+

 ### `template_depends($$;@)`
 
 Use this instead of `template()` if the content of a template is being
 ### `template_depends($$;@)`
 
 Use this instead of `template()` if the content of a template is being


@@ -975,14 +982,22 @@ This is the standard gettext function, although slightly optimised.
 
 This is the standard ngettext function, although slightly optimised.
 
 
 This is the standard ngettext 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.
+Provide a second parameter whenever possible, since this leads to better
+behaviour for the [[plugins/po]] plugin and `file:///` URLs.
+
+If the second parameter is not specified (or `undef`), the URL will be
+valid from any page on the wiki, or from the CGI; if possible it'll
+be a path starting with `/`, but an absolute URL will be used if
+the wiki and the CGI are on different domains.
+
+If the third parameter is passed and is true, the url will be a fully
+absolute url. This is useful when generating an url to publish elsewhere.

 
 ### `newpagefile($$)`
 
 
 ### `newpagefile($$)`
 


@@ -1136,19 +1151,19 @@ The data structure returned for each change is:
                ],
        }
 
                ],
        }
 

-#### `rcs_diff($)`
+#### `rcs_diff($;$)`
+
+The first parameter is the rev from `rcs_recentchanges`.
+The optional second parameter is how many lines to return (default: all).

 
 

-The parameter is the rev from `rcs_recentchanges`.

 Should return a list of lines of the diff (including \n) in list
 Should return a list of lines of the diff (including \n) in list

-context, and the whole diff in scalar context.
+context, and a string containing 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.
 
 
 #### `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.
-

 If the RCS cannot determine a ctime for the file, return 0.
 
 #### `rcs_getmtime($)`
 If the RCS cannot determine a ctime for the file, return 0.
 
 #### `rcs_getmtime($)`


@@ -1169,9 +1184,9 @@ sense to implement for all RCSs.
 
 It should examine the incoming changes, and do any sanity 
 checks that are appropriate for the RCS to limit changes to safe file adds,
 
 It should examine the incoming changes, and do any sanity 
 checks that are appropriate for the RCS to limit changes to safe file adds,

-removes, and changes. If something bad is found, it should exit
-nonzero, to abort the push. Otherwise, it should return a list of
-files that were changed, in the form:
+removes, and changes. If something bad is found, it should die, to abort
+the push. Otherwise, it should return a list of files that were changed,
+in the form:

 
        {
                file => # name of file that was changed
 
        {
                file => # name of file that was changed


@@ -1184,6 +1199,28 @@ files that were changed, in the form:
 The list will then be checked to make sure that each change is one that
 is allowed to be made via the web interface.
 
 The list will then be checked to make sure that each change is one that
 is allowed to be made via the web interface.
 

+#### `rcs_preprevert($)`
+
+This is called by the revert web interface. It is passed a RCS-specific
+change ID, and should determine what the effects would be of reverting
+that change, and return the same data structure as `rcs_receive`.
+
+Like `rcs_receive`, it should do whatever sanity checks are appropriate
+for the RCS to limit changes to safe changes, and die if a change would
+be unsafe to revert.
+
+#### `rcs_revert($)`
+
+This is called by the revert web interface. It is passed a named
+parameter rev that is the RCS-specific change ID to revert.
+
+It should try to revert the specified rev, and leave the reversion staged
+so `rcs_commit_staged` will complete it. It should return undef on _success_
+and an error message on failure.
+
+This hook and `rcs_preprevert` are optional, if not implemented, no revert
+web interface will be available.
+

 ### PageSpec plugins
 
 It's also possible to write plugins that add new functions to
 ### PageSpec plugins
 
 It's also possible to write plugins that add new functions to