summaryrefslogtreecommitdiff
path: root/doc/plugins
diff options
context:
space:
mode:
authorJoey Hess <joey@gnu.kitenet.net>2010-04-06 23:15:33 -0400
committerJoey Hess <joey@gnu.kitenet.net>2010-04-06 23:15:33 -0400
commitbab8fec52468b780485bdf96a37a593bd033c7e3 (patch)
tree5f292e4e6205bd4fcde1be249c1fe646dc75a26c /doc/plugins
parent9dc220711dff12fd45274c4e2fd2645a33d3de5c (diff)
parenta2dc8c9373b36f7cc8da239b823b5839788a743d (diff)
Merge remote branch 'smcv/ready/sort-package'
Conflicts: debian/NEWS
Diffstat (limited to 'doc/plugins')
-rw-r--r--doc/plugins/sortnaturally.mdwn5
-rw-r--r--doc/plugins/write.mdwn18
2 files changed, 23 insertions, 0 deletions
diff --git a/doc/plugins/sortnaturally.mdwn b/doc/plugins/sortnaturally.mdwn
new file mode 100644
index 000000000..91f373f6b
--- /dev/null
+++ b/doc/plugins/sortnaturally.mdwn
@@ -0,0 +1,5 @@
+[[!template id=plugin name=sortnaturally core=1 author="[[chrysn]], [[smcv]]"]]
+[[!tag type/meta]]
+
+This plugin provides the `title_natural` [[ikiwiki/pagespec/sorting]] order,
+which uses Sort::Naturally to sort numbered pages in a more natural order.
diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 71ff1fd29..05ddf2215 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -1129,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.
+### 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