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

Conflicts:
	debian/NEWS

4 files changed, 52 insertions, 3 deletions

diff --git a/doc/ikiwiki/directive/meta.mdwn b/doc/ikiwiki/directive/meta.mdwn
index 557441c0b..5a3919dea 100644
--- a/doc/ikiwiki/directive/meta.mdwn
+++ b/doc/ikiwiki/directive/meta.mdwn
@@ -23,6 +23,13 @@ Supported fields:
   be set to a true value in the template; this can be used to format things
   differently in this case.
 
+  An optional `sortas` parameter will be used preferentially when
+  [[ikiwiki/pagespec/sorting]] by `meta(title)`:
+
+	\[[!meta title="The Beatles" sortas="Beatles, The"]]
+
+	\[[!meta title="David Bowie" sortas="Bowie, David"]]
+
 * license
 
   Specifies a license for the page, for example, "GPL". Can contain
@@ -37,6 +44,11 @@ Supported fields:
 
   Specifies the author of a page.
 
+  An optional `sortas` parameter will be used preferentially when
+  [[ikiwiki/pagespec/sorting]] by `meta(author)`:
+
+	\[[!meta author="Joey Hess" sortas="Hess, Joey"]]
+
 * authorurl
 
   Specifies an url for the author of a page.
diff --git a/doc/ikiwiki/pagespec/sorting.mdwn b/doc/ikiwiki/pagespec/sorting.mdwn
index 697818a2a..5c6cfcc2b 100644
--- a/doc/ikiwiki/pagespec/sorting.mdwn
+++ b/doc/ikiwiki/pagespec/sorting.mdwn
@@ -5,9 +5,23 @@ orders can be specified.
 
 * `age` - List pages from the most recently created to the oldest.
 * `mtime` - List pages with the most recently modified first.
-* `title` - Order by title.
-* `title_natural` - Only available if [[!cpan Sort::Naturally]] is
-  installed. Orders by title, but numbers in the title are treated
+* `title` - Order by title (page name).
+[[!if test="enabled(sortnaturally)" then="""
+* `title_natural` - Orders by title, but numbers in the title are treated
   as such, ("1 2 9 10 20" instead of "1 10 2 20 9")
+"""]]
+[[!if test="enabled(meta)" then="""
+* `meta(title)` - Order according to the `\[[!meta title="foo" sortas="bar"]]`
+  or `\[[!meta title="foo"]]` [[ikiwiki/directive]], or the page name if no
+  full title was set. `meta(author)`, `meta(date)`, `meta(updated)`, etc.
+  also work.
+"""]]
+
+In addition, you can combine several sort orders and/or reverse the order of
+sorting, with a string like `age -title` (which would sort by age, then by
+title in reverse order if two pages have the same age).
+
+Plugins can add additional sort orders, so more might be available on this
+wiki.
 
 [[!meta robots="noindex, follow"]]
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