Reimplement extensible sorting mechanisms, in the same way as pagespecs

1 files changed, 23 insertions, 30 deletions

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 1010e76e4..de2b47015 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -588,36 +588,6 @@ describes the plugin as a whole. For example:
 This hook is used to inject C code (which it returns) into the `main`
 function of the ikiwiki wrapper when it is being generated.
 
-### sort
-
-	hook(type => "sort", id => "foo", call => \&sort_by_foo);
-
-This hook adds an additional [[ikiwiki/pagespec/sorting]] order or overrides
-an existing one.
-
-The callback is given two page names followed by the parameter as arguments, and
-returns negative, zero or positive if the first page should come before,
-close to (i.e. undefined order), or after the second page.
-
-For instance, the built-in `title` sort order could be reimplemented as
-
-	sub sort_by_title {
-		pagetitle(basename($_[0])) cmp pagetitle(basename($_[1]));
-	}
-
-and to sort by an arbitrary `meta` value, you could use:
-
-	# usage: sort="meta(description)"
-	sub sort_by_meta {
-		my $param = $_[2];
-		error "sort=meta requires a parameter" unless defined $param;
-		my $left = $pagestate{$_[0]}{meta}{$param};
-		$left = "" unless defined $left;
-		my $right = $pagestate{$_[1]}{meta}{$param};
-		$right = "" unless defined $right;
-		return $left cmp $right;
-	}
-
 ## Exported variables
 
 Several variables are exported to your plugin when you `use IkiWiki;`
@@ -1140,6 +1110,29 @@ 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::PageSpec package named `cmp_foo`, which will be used when sorting
+by `foo` or `foo(...)` is requested.
+
+The function will be passed three or more parameters. The first two are
+page names, and the third is `undef` if invoked as `foo`, or the parameter
+`"bar"` if invoked as `foo(bar)`. It may also be passed additional, named
+parameters.
+
+It should return the same thing as Perl's `cmp` and `<=>` operators: negative
+if the first argument is less than the second, positive if the first argument
+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.
+
+You can also define a function called `check_cmp_foo` in the same package.
+If you do, it will be called while preparing to sort by `foo` or `foo(bar)`,
+with argument `undef` or `"bar"` respectively; it may raise an error using
+`error`, if sorting like that isn't going to work.
+
 ### Setup plugins
 
 The ikiwiki setup file is loaded using a pluggable mechanism. If you look