-## Documentation from sort-hooks branch
-
-### sort hook (added to [[plugins/write]])
-
- 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;
- }
+>>>>> Perhaps. I do like the simplicity of [[KathyrnAndersen]]'s syntax
+>>>>> from [[plugins/contrib/report]] (which I copied verbatim, except for
+>>>>> turning sort-by-`field` into a parameterized spec), and I can't really
+>>>>> think of any sensible way to combine sort specs other than "sort by a,
+>>>>> break ties by b, ...", possibly with some reversals thrown in.
+>>>>>
+>>>>> If no other combinations do make sense, is your proposal that "then"
+>>>>> is entirely redundant (easy, just make it a predefined sort spec that
+>>>>> returns 0!), or that it's mandatory "punctuation" (add an explicit
+>>>>> check, or make "then" expand to "||" and let Perl fail to compile
+>>>>> the generated code if it's omitted)?
+>>>>>
+>>>>> It is a little unfortunate that reversal has to move into the sort
+>>>>> spec - I prefer `reverse=yes` - but that's necessary for multi-level
+>>>>> sorting. I can see your point about ascending/descending being more
+>>>>> obvious to look at, but they're also considerably more verbose.
+>>>>>
+>>>>> Unfortunately, `sort="ascending mtime"` actually sorts by *descending*
+>>>>> timestamp (but`sort=age` is fine, because `age` could be defined as
+>>>>> now minus `ctime`). `sort=freshness` isn't right either, because
+>>>>> "sort by freshness" seems as though it ought to mean freshest first,
+>>>>> but "sort by ascending freshness" means put the least fresh first. If
+>>>>> we have ascending and descending keywords which are optional, I don't
+>>>>> think we really want different sort types to have different default
+>>>>> directions - it seems clearer to have `ascending` always be a no-op,
+>>>>> and `descending` always negate.
+>>>>>
+>>>>> Perhaps we could borrow from `meta updated` and use `update_age`?
+>>>>> `updateage` would perhaps be a more normal IkiWiki style - but that
+>>>>> makes me think that updateage is a quantity analagous to tonnage or
+>>>>> voltage, with more or less recently updated pages being said to have
+>>>>> more or less updateage. I don't know whether that's good or bad :-)
+>>>>>
+>>>>> I'm sure there's a much better word, but I can't see it. --s