X-Git-Url: https://sipb.mit.edu/gitweb.cgi/ikiwiki.git/blobdiff_plain/4a7558539cd9d0f1ed5c586c29811035f7c14d14..0fcbcc4815042531eb58de339844a3767fb5e707:/doc/plugins/write.mdwn

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index d94216e17..5190a26ed 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -31,7 +31,7 @@ is accomplished by calling various hooks provided by plugins.
 
 ### compiler
 
-As a compiler, starts by calling the `refresh` hook. Then it checks
+As a compiler, ikiwiki starts by calling the `refresh` hook. Then it checks
 the wiki's source to find new or changed pages. The `needsbuild` hook is
 then called to allow manipulation of the list of pages that need to be
 built. 
@@ -48,10 +48,11 @@ page had previously produced are removed.
 
 ### cgi
 
-The flow between hooks when ikiwiki is run as a cgi is best illistrated by
+The flow between hooks when ikiwiki is run as a cgi is best illustrated by
 an example.
 
-* *Alice browses to a page and clicks Edit.*
+Alice browses to a page and clicks Edit.
+
 * Ikiwiki is run as a cgi. It assigns Alice a session cookie, and,
   by calling the `auth` hooks, sees that she is not yet logged in.
 * The `sessioncgi` hooks are then called, and one of them,
@@ -61,7 +62,9 @@ an example.
   Alice is not signed in.
 * The [[signinedit]] plugin then launches the signin process. A signin
   page is built by calling the `formbuilder_setup` hook.
-* *Alice signs in with her openid.*
+
+Alice signs in with her openid.
+
 * The [[openid]] plugin's `formbuilder` hook sees that an openid was
   entered in the signin form, and redirects to Alice's openid provider.
 * Alice's openid provider calls back to ikiwiki. The [[openid]] plugin
@@ -70,7 +73,9 @@ an example.
   a page.
 * Now all the `canedit` hooks are happy. The [[editpage]] plugin calls
   `formbuilder_setup` to display the page editing form.
-* *Alice saves her change to the page.*
+
+Alice saves her change to the page.
+
 * The [[editpage]] plugin's `formbuilder` hook sees that the Save button
   was pressed, and calls the `checkcontent` and `editcontent` hooks.
   Then it saves the page to disk, and branches into the compiler part
@@ -531,7 +536,7 @@ The data returned is a list of `%config` options, followed by a hash
 describing the option. There can also be an item named "plugin", which
 describes the plugin as a whole. For example:
 
-                return
+		return
 			plugin => {
 				description => "description of this plugin",
 				safe => 1,
@@ -628,6 +633,22 @@ reference. Do not modify this hash directly; call `add_link()`.
 
 	$links{"foo"} = ["bar", "baz"];
 
+### `%typedlinks`
+
+The `%typedlinks` hash records links of specific types. Do not modify this
+hash directly; call `add_link()`. The keys are page names, and the values
+are hash references. In each page's hash reference, the keys are link types
+defined by plugins, and the values are hash references with link targets
+as keys, and 1 as a dummy value, something like this:
+
+	$typedlinks{"foo"} = {
+		tag => { short_word => 1, metasyntactic_variable => 1 },
+		next_page => { bar => 1 },
+	};
+
+Ordinary [[WikiLinks|ikiwiki/WikiLink]] appear in `%links`, but not in
+`%typedlinks`.
+
 ### `%pagesources`
 
 The `%pagesources` has can be used to look up the source filename
@@ -713,7 +734,10 @@ Additional named parameters can be specified:
 * `filter` is a reference to a function, that is called and passed a page,
   and returns true if the page should be filtered out of the list.
 * `sort` specifies a sort order for the list. See
-  [[ikiwiki/PageSpec/sorting]] for the avilable sort methods.
+  [[ikiwiki/PageSpec/sorting]] for the avilable sort methods. Note that
+  if a sort method is specified that depends on the
+  page content (such as 'meta(foo)'), the deptype needs to be set to
+  a content dependency.
 * `reverse` if true, sorts in reverse.
 * `num` if nonzero, specifies the maximum number of matching pages that
   will be returned.
@@ -731,7 +755,7 @@ By default, dependencies are full content dependencies, meaning that the
 page will be updated whenever anything matching the PageSpec is modified.
 This can be overridden by passing a `deptype` value as the third parameter.
 
-#### `pagespec_match($$;@)`
+### `pagespec_match($$;@)`
 
 Passed a page name, and [[ikiwiki/PageSpec]], returns a true value if the
 [[ikiwiki/PageSpec]] matches the page.
@@ -761,7 +785,7 @@ dependency type from one or more of these keywords:
 
 If multiple types are specified, they are combined.
 
-#### `bestlink($$)`
+### `bestlink($$)`
 
 Given a page and the text of a link on the page, determine which
 existing page that link best points to. Prefers pages under a
@@ -769,7 +793,7 @@ subdirectory with the same name as the source page, failing that
 goes down the directory tree to the base looking for matching
 pages, as described in [[ikiwiki/SubPage/LinkingRules]].
 
-#### `htmllink($$$;@)`
+### `htmllink($$$;@)`
 
 Many plugins need to generate html links and add them to a page. This is
 done by using the `htmllink` function. The usual way to call
@@ -906,6 +930,10 @@ time.
 
 This is the standard gettext function, although slightly optimised.
 
+### `ngettext`
+
+This is the standard ngettext function, although slightly optimised.
+
 ### `urlto($$;$)`
 
 Construct a relative url to the first parameter from the page named by the
@@ -930,11 +958,31 @@ Optionally, a third parameter can be passed, to specify the preferred
 filename of the page. For example, `targetpage("foo", "rss", "feed")`
 will yield something like `foo/feed.rss`.
 
-### `add_link($$)`
+### `add_link($$;$)`
 
 This adds a link to `%links`, ensuring that duplicate links are not
 added. Pass it the page that contains the link, and the link text.
 
+An optional third parameter sets the link type. If not specified,
+it is an ordinary [[ikiwiki/WikiLink]].
+
+### `add_autofile($$$)`
+
+Sometimes you may want to add a file to the `srcdir` as a result of content
+of other pages. For example, [[plugins/tag]] pages can be automatically
+created as needed. This function can be used to do that. 
+
+The three parameters are the filename to add, the name of the plugin,
+and a callback function. The callback will be called if it is appropriate
+to automatically add the file, and should then take care of creating it,
+and doing anything else it needs to (such as checking it into revision
+control). Note that the callback may not always be called. For example,
+if an automatically added file is deleted by the user, ikiwiki will avoid
+re-adding it again.
+
+This function needs to be called during the scan hook, or earlier in the
+build process, in order to add the file early enough for it to be built.
+
 ## Miscellaneous
 
 ### Internal use pages
@@ -1054,6 +1102,17 @@ 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($)`
+
+This is used to get the page modification 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 mtime for the file, return 0.
+
 #### `rcs_receive()`
 
 This is called when ikiwiki is running as a pre-receive hook (or
@@ -1101,6 +1160,24 @@ For example, "backlink(foo)" is influenced by the contents of page foo;
 they match; "created_before(foo)" is influenced by the metadata of foo;
 while "glob(*)" is not influenced by the contents of any page.
 
+### Sorting plugins
+
+Similarly, it's possible to write plugins that add new functions as
+[[ikiwiki/pagespec/sorting]] methods. To achieve this, add a function to
+the IkiWiki::SortSpec package named `cmp_foo`, which will be used when sorting
+by `foo` or `foo(...)` is requested.
+
+The names of pages to be compared are in the global variables `$a` and `$b`
+in the IkiWiki::SortSpec package. The function should return the same thing
+as Perl's `cmp` and `<=>` operators: negative if `$a` is less than `$b`,
+positive if `$a` is greater, or zero if they are considered equal. It may
+also raise an error using `error`, for instance if it needs a parameter but
+one isn't provided.
+
+The function will also be passed one or more parameters. The first is
+`undef` if invoked as `foo`, or the parameter `"bar"` if invoked as `foo(bar)`;
+it may also be passed additional, named parameters.
+
 ### Setup plugins
 
 The ikiwiki setup file is loaded using a pluggable mechanism. If you look