Merge remote branch 'smcv/ready/sort-package'

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

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index a8c9de2d38719bd1c3b7d5da90432db0e5083483..05ddf2215de9872bbc891d5d288b5a16df55ae6c 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -633,6 +633,22 @@ reference. Do not modify this hash directly; call `add_link()`.
 
        $links{"foo"} = ["bar", "baz"];
 
 
        $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
 ### `%pagesources`
 
 The `%pagesources` has can be used to look up the source filename


@@ -911,6 +927,10 @@ time.
 
 This is the standard gettext function, although slightly optimised.
 
 
 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
 ### `urlto($$;$)`
 
 Construct a relative url to the first parameter from the page named by the


@@ -935,11 +955,14 @@ 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`.
 
 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.
 
 
 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]].
+

 ## Miscellaneous
 
 ### Internal use pages
 ## Miscellaneous
 
 ### Internal use pages


@@ -1106,6 +1129,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.
 
 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
 ### Setup plugins
 
 The ikiwiki setup file is loaded using a pluggable mechanism. If you look