From 156f70912213b6520e9056050a8827de66e80176 Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@debian.org>
Date: Fri, 4 Nov 2011 19:32:41 +0000
Subject: trail: new plugin (3rd attempt)

---
 IkiWiki/Plugin/trail.pm     | 486 ++++++++++++++++++++++++++++++++++++++++++++
 doc/style.css               |  35 ++++
 doc/templates.mdwn          |   2 +
 t/trail.t                   | 159 +++++++++++++++
 templates/page.tmpl         |  11 +
 templates/trails.tmpl       |  23 +++
 themes/actiontabs/style.css |   5 +
 themes/blueview/style.css   |   9 +-
 8 files changed, 728 insertions(+), 2 deletions(-)
 create mode 100644 IkiWiki/Plugin/trail.pm
 create mode 100755 t/trail.t
 create mode 100644 templates/trails.tmpl

diff --git a/IkiWiki/Plugin/trail.pm b/IkiWiki/Plugin/trail.pm
new file mode 100644
index 000000000..e9b4d9cd4
--- /dev/null
+++ b/IkiWiki/Plugin/trail.pm
@@ -0,0 +1,486 @@
+#!/usr/bin/perl
+# Copyright © 2008-2011 Joey Hess
+# Copyright © 2009-2011 Simon McVittie <http://smcv.pseudorandom.co.uk/>
+# Licensed under the GNU GPL, version 2, or any later version published by the
+# Free Software Foundation
+package IkiWiki::Plugin::trail;
+
+use warnings;
+use strict;
+use IkiWiki 3.00;
+
+sub import {
+	hook(type => "getsetup", id => "trail", call => \&getsetup);
+	hook(type => "needsbuild", id => "trail", call => \&needsbuild);
+	hook(type => "preprocess", id => "trail", call => \&preprocess_trail, scan => 1);
+	hook(type => "preprocess", id => "trailinline", call => \&preprocess_trailinline, scan => 1);
+	hook(type => "preprocess", id => "trailitem", call => \&preprocess_trailitem, scan => 1);
+	hook(type => "preprocess", id => "traillink", call => \&preprocess_traillink, scan => 1);
+	hook(type => "pagetemplate", id => "trail", call => \&pagetemplate);
+}
+
+=head1 Page state
+
+If a page C<$T> is a trail, then it can have
+
+=over
+
+=item * C<$pagestate{$T}{trail}{contents}>
+
+Reference to an array of pagespecs or links in the trail.
+
+=item * C<$pagestate{$T}{trail}{sort}>
+
+A [[ikiwiki/pagespec/sorting]] order; if absent or undef, the trail is in
+the order given by the links that form it
+
+=item * C<$pagestate{$T}{trail}{circular}>
+
+True if this trail is circular (i.e. going "next" from the last item is
+allowed, and takes you back to the first)
+
+=item * C<$pagestate{$T}{trail}{reverse}>
+
+True if C<sort> is to be reversed.
+
+=back
+
+If a page C<$M> is a member of a trail C<$T>, then it has
+
+=over
+
+=item * C<$pagestate{$M}{trail}{item}{$T}[0]>
+
+The page before this one in C<$T> at the last rebuild, or undef.
+
+=item * C<$pagestate{$M}{trail}{item}{$T}[1]>
+
+The page after this one in C<$T> at the last refresh, or undef.
+
+=back
+
+=cut
+
+sub getsetup () {
+	return
+		plugin => {
+			safe => 1,
+			rebuild => undef,
+		},
+}
+
+sub needsbuild (@) {
+	my $needsbuild=shift;
+	foreach my $page (keys %pagestate) {
+		if (exists $pagestate{$page}{trail}) {
+			if (exists $pagesources{$page} &&
+			    grep { $_ eq $pagesources{$page} } @$needsbuild) {
+				# Remove state, it will be re-added
+				# if the preprocessor directive is still
+				# there during the rebuild. {item} is the
+				# only thing that's added for items, not
+				# trails, and it's harmless to delete that -
+				# the item is being rebuilt anyway.
+				delete $pagestate{$page}{trail};
+			}
+		}
+	}
+	return $needsbuild;
+}
+
+=for wiki
+
+The `trail` directive is supplied by the [[plugins/contrib/trail]]
+plugin. It sets options for the trail represented by this page. Example usage:
+
+    \[[!trail sort="meta(date)" circular="no" pages="blog/posts/*"]]
+
+The available options are:
+
+* `sort`: sets a [[ikiwiki/pagespec/sorting]] order; if not specified, the
+  items of the trail are ordered according to the first link to each item
+  found on the trail page
+
+* `circular`: if set to `yes` or `1`, the trail is made into a loop by
+  making the last page's "next" link point to the first page, and the first
+  page's "previous" link point to the last page
+
+* `pages`: add the given pages to the trail
+
+=cut
+
+sub preprocess_trail (@) {
+	my %params = @_;
+
+	if (exists $params{circular}) {
+		$pagestate{$params{page}}{trail}{circular} =
+			IkiWiki::yesno($params{circular});
+	}
+
+	if (exists $params{sort}) {
+		$pagestate{$params{page}}{trail}{sort} = $params{sort};
+	}
+
+	if (exists $params{reverse}) {
+		$pagestate{$params{page}}{trail}{reverse} = $params{reverse};
+	}
+
+	if (exists $params{pages}) {
+		push @{$pagestate{$params{page}}{trail}{contents}}, "pagespec $params{pages}";
+	}
+
+	if (exists $params{pagenames}) {
+		my @list = map { "link $_" } split ' ', $params{pagenames};
+		push @{$pagestate{$params{page}}{trail}{contents}}, @list;
+	}
+
+	return "";
+}
+
+=for wiki
+
+The `trailinline` directive is supplied by the [[plugins/contrib/trail]]
+plugin. It behaves like the [[trail]] and [[inline]] directives combined.
+Like [[inline]], it includes the selected pages into the page with the
+directive and/or an RSS or Atom feed; like [[trail]], it turns the
+included pages into a "trail" in which each page has a link to the
+previous and next pages.
+
+    \[[!inline sort="meta(date)" circular="no" pages="blog/posts/*"]]
+
+All the options for the [[inline]] and [[trail]] directives are valid.
+
+The `show`, `skip` and `feedshow` options from [[inline]] do not apply
+to the trail.
+
+* `sort`: sets a [[ikiwiki/pagespec/sorting]] order; if not specified, the
+  items of the trail are ordered according to the first link to each item
+  found on the trail page
+
+* `circular`: if set to `yes` or `1`, the trail is made into a loop by
+  making the last page's "next" link point to the first page, and the first
+  page's "previous" link point to the last page
+
+* `pages`: add the given pages to the trail
+
+=cut
+
+sub preprocess_trailinline (@) {
+	preprocess_trail(@_);
+	return unless defined wantarray;
+
+	if (IkiWiki->can("preprocess_inline")) {
+		return IkiWiki::preprocess_inline(@_);
+	}
+	else {
+		error("trailinline directive requires the inline plugin");
+	}
+}
+
+=for wiki
+
+The `trailitem` directive is supplied by the [[plugins/contrib/trail]] plugin.
+It is used like this:
+
+    \[[!trailitem some_other_page]]
+
+to add `some_other_page` to the trail represented by this page, without
+generating a visible hyperlink.
+
+=cut
+
+sub preprocess_trailitem (@) {
+	my $link = shift;
+	shift;
+
+	my %params = @_;
+	my $trail = $params{page};
+
+	$link = linkpage($link);
+
+	add_link($params{page}, $link, 'trail');
+	push @{$pagestate{$params{page}}{trail}{contents}}, "link $link";
+
+	return "";
+}
+
+=for wiki
+
+The `traillink` directive is supplied by the [[plugins/contrib/trail]] plugin.
+It generates a visible [[ikiwiki/WikiLink]], and also adds the linked page to
+the trail represented by the page containing the directive.
+
+In its simplest form, the first parameter is like the content of a WikiLink:
+
+    \[[!traillink some_other_page]]
+
+The displayed text can also be overridden, either with a `|` symbol or with
+a `text` parameter:
+
+    \[[!traillink Click_here_to_start_the_trail|some_other_page]]
+    \[[!traillink some_other_page text="Click here to start the trail"]]
+
+=cut
+
+sub preprocess_traillink (@) {
+	my $link = shift;
+	shift;
+
+	my %params = @_;
+	my $trail = $params{page};
+
+	$link =~ qr{
+			(?:
+				([^\|]+)	# 1: link text
+				\|		# followed by |
+			)?			# optional
+
+			(.+)			# 2: page to link to
+		}x;
+
+	my $linktext = $1;
+	$link = linkpage($2);
+
+	add_link($params{page}, $link, 'trail');
+	push @{$pagestate{$params{page}}{trail}{contents}}, "link $link";
+
+	if (defined $linktext) {
+		$linktext = pagetitle($linktext);
+	}
+
+	if (exists $params{text}) {
+		$linktext = $params{text};
+	}
+
+	if (defined $linktext) {
+		return htmllink($trail, $params{destpage},
+			$link, linktext => $linktext);
+	}
+
+	return htmllink($trail, $params{destpage}, $link);
+}
+
+# trail => [member1, member2]
+my %trail_to_members;
+# member => { trail => [prev, next] }
+# e.g. if %trail_to_members = (
+#	trail1 => ["member1", "member2"],
+#	trail2 => ["member0", "member1"],
+# )
+#
+# then $member_to_trails{member1} = {
+#	trail1 => [undef, "member2"],
+#	trail2 => ["member0", undef],
+# }
+my %member_to_trails;
+
+# member => 1
+my %rebuild_trail_members;
+
+sub trails_differ {
+	my ($old, $new) = @_;
+
+	foreach my $trail (keys %$old) {
+		if (! exists $new->{$trail}) {
+			return 1;
+		}
+		my ($old_p, $old_n) = @{$old->{$trail}};
+		my ($new_p, $new_n) = @{$new->{$trail}};
+		$old_p = "" unless defined $old_p;
+		$old_n = "" unless defined $old_n;
+		$new_p = "" unless defined $new_p;
+		$new_n = "" unless defined $new_n;
+		if ($old_p ne $new_p) {
+			return 1;
+		}
+		if ($old_n ne $new_n) {
+			return 1;
+		}
+	}
+
+	foreach my $trail (keys %$new) {
+		if (! exists $old->{$trail}) {
+			return 1;
+		}
+	}
+
+	return 0;
+}
+
+my $done_prerender = 0;
+
+my %origsubs;
+
+sub prerender {
+	return if $done_prerender;
+
+	$origsubs{render_backlinks} = \&IkiWiki::render_backlinks;
+	inject(name => "IkiWiki::render_backlinks", call => \&render_backlinks);
+
+	%trail_to_members = ();
+	%member_to_trails = ();
+
+	foreach my $trail (keys %pagestate) {
+		next unless exists $pagestate{$trail}{trail}{contents};
+
+		my $members = [];
+		my @contents = @{$pagestate{$trail}{trail}{contents}};
+
+
+		foreach my $c (@contents) {
+			if ($c =~ m/^pagespec (.*)$/) {
+				push @$members, pagespec_match_list($trail, $1);
+			}
+			elsif ($c =~ m/^link (.*)$/) {
+				my $best = bestlink($trail, $1);
+				push @$members, $best if length $best;
+			}
+		}
+
+		if (defined $pagestate{$trail}{trail}{sort}) {
+			# re-sort
+			@$members = pagespec_match_list($trail, 'internal(*)',
+				list => $members,
+				sort => $pagestate{$trail}{trail}{sort});
+		}
+
+		if (IkiWiki::yesno $pagestate{$trail}{trail}{reverse}) {
+			@$members = reverse @$members;
+		}
+
+		# uniquify
+		my %seen;
+		my @tmp;
+		foreach my $member (@$members) {
+			push @tmp, $member unless $seen{$member};
+			$seen{$member} = 1;
+		}
+		$members = [@tmp];
+
+		for (my $i = 0; $i <= $#$members; $i++) {
+			my $member = $members->[$i];
+			my $prev;
+			$prev = $members->[$i - 1] if $i > 0;
+			my $next = $members->[$i + 1];
+
+			add_depends($member, $trail);
+
+			$member_to_trails{$member}{$trail} = [$prev, $next];
+		}
+
+		if ((scalar @$members) > 1 && $pagestate{$trail}{trail}{circular}) {
+			$member_to_trails{$members->[0]}{$trail}[0] = $members->[$#$members];
+			$member_to_trails{$members->[$#$members]}{$trail}[1] = $members->[0];
+		}
+
+		$trail_to_members{$trail} = $members;
+	}
+
+	foreach my $member (keys %pagestate) {
+		if (exists $pagestate{$member}{trail}{item} &&
+			! exists $member_to_trails{$member}) {
+			$rebuild_trail_members{$member} = 1;
+			delete $pagestate{$member}{trailitem};
+		}
+	}
+
+	foreach my $member (keys %member_to_trails) {
+		if (! exists $pagestate{$member}{trail}{item}) {
+			$rebuild_trail_members{$member} = 1;
+		}
+		else {
+			if (trails_differ($pagestate{$member}{trail}{item},
+					$member_to_trails{$member})) {
+				$rebuild_trail_members{$member} = 1;
+			}
+		}
+
+		$pagestate{$member}{trail}{item} = $member_to_trails{$member};
+	}
+
+	$done_prerender = 1;
+}
+
+# This is called at about the right time that we can hijack it to render
+# extra pages.
+sub render_backlinks ($) {
+	my $blc = shift;
+
+	foreach my $member (keys %rebuild_trail_members) {
+		next unless exists $pagesources{$member};
+
+		IkiWiki::render($pagesources{$member}, sprintf(gettext("building %s, its previous or next page has changed"), $member));
+	}
+
+	$origsubs{render_backlinks}($blc);
+}
+
+sub title_of ($) {
+	my $page = shift;
+	if (defined ($pagestate{$page}{meta}{title})) {
+		return $pagestate{$page}{meta}{title};
+	}
+	return pagetitle(IkiWiki::basename($page));
+}
+
+my $recursive = 0;
+
+sub pagetemplate (@) {
+	my %params = @_;
+	my $page = $params{page};
+	my $template = $params{template};
+
+	if ($template->query(name => 'trails') && ! $recursive) {
+		prerender();
+
+		$recursive = 1;
+		my $inner = template("trails.tmpl", blind_cache => 1);
+		IkiWiki::run_hooks(pagetemplate => sub {
+				shift->(%params, template => $inner)
+			});
+		$template->param(trails => $inner->output);
+		$recursive = 0;
+	}
+
+	if ($template->query(name => 'trailloop')) {
+		prerender();
+
+		my @trails;
+
+		# sort backlinks by page name to have a consistent order
+		foreach my $trail (sort keys %{$member_to_trails{$page}}) {
+
+			my $members = $trail_to_members{$trail};
+			my ($prev, $next) = @{$member_to_trails{$page}{$trail}};
+			my ($prevurl, $nexturl, $prevtitle, $nexttitle);
+
+			if (defined $prev) {
+				add_depends($params{destpage}, $prev);
+				$prevurl = urlto($prev, $page);
+				$prevtitle = title_of($prev);
+			}
+
+			if (defined $next) {
+				add_depends($params{destpage}, $next);
+				$nexturl = urlto($next, $page);
+				$nexttitle = title_of($next);
+			}
+
+			push @trails, {
+				prevpage => $prev,
+				prevtitle => $prevtitle,
+				prevurl => $prevurl,
+				nextpage => $next,
+				nexttitle => $nexttitle,
+				nexturl => $nexturl,
+				trailpage => $trail,
+				trailtitle => title_of($trail),
+				trailurl => urlto($trail, $page),
+			};
+		}
+
+		$template->param(trailloop => \@trails);
+	}
+}
+
+1;
diff --git a/doc/style.css b/doc/style.css
index 7bbfe5d2a..35a133198 100644
--- a/doc/style.css
+++ b/doc/style.css
@@ -501,3 +501,38 @@ a.openid_large_btn:focus {
 .fileupload-content .ui-progressbar-value {
 	background: url(ikiwiki/images/pbar-ani.gif);
 }
+
+.trail {
+	display: block;
+	clear: both;
+	position: relative;
+}
+
+.trailprev {
+	display: block;
+	text-align: left;
+	position: absolute;
+	top: 0%;
+	left: 3%;
+	width: 30%;
+}
+
+.trailup {
+	display: block;
+	text-align: center;
+	margin-left: 35%;
+	margin-right: 35%;
+}
+
+.trailnext {
+	display: block;
+	text-align: right;
+	position: absolute;
+	top: 0%;
+	width: 30%;
+	right: 3%;
+}
+
+.trailsep {
+	display: none;
+}
diff --git a/doc/templates.mdwn b/doc/templates.mdwn
index d189fa073..43bf9ee51 100644
--- a/doc/templates.mdwn
+++ b/doc/templates.mdwn
@@ -80,6 +80,8 @@ Here is a full list of the template files used:
 * `autotag.tmpl` - Filled in by the tag plugin to make tag pages.
 * `calendarmonth.tmpl`, `calendaryear.tmpl` - Used by ikiwiki-calendar to
   make calendar archive pages.
+* `trails.tmpl` - Used by the trail plugin to generate links on each page
+  that is a member of a trail.
 * `editpage.tmpl`, `editconflict.tmpl`, `editcreationconflict.tmpl`,
   `editfailedsave.tmpl`, `editpagegone.tmpl`, `pocreatepage.tmpl`,
   `editcomment.tmpl` `commentmoderation.tmpl`, `renamesummary.tmpl`,
diff --git a/t/trail.t b/t/trail.t
new file mode 100755
index 000000000..ce7d92048
--- /dev/null
+++ b/t/trail.t
@@ -0,0 +1,159 @@
+#!/usr/bin/perl
+use warnings;
+use strict;
+use Test::More 'no_plan';
+use IkiWiki;
+
+my $blob;
+
+ok(! system("rm -rf t/tmp"));
+ok(! system("mkdir t/tmp"));
+
+# Use a rather stylized template to override the default rendering, to make
+# it easy to search for the desired results
+writefile("templates/trails.tmpl", "t/tmp/in", <<EOF
+<TMPL_LOOP TRAILLOOP>
+<TMPL_IF __FIRST__><nav></TMPL_IF>
+<div>
+trail=<TMPL_VAR TRAILPAGE> n=<TMPL_VAR NEXTPAGE> p=<TMPL_VAR PREVPAGE>
+</div>
+<div>
+<TMPL_IF PREVURL>
+<a href="<TMPL_VAR PREVURL>">&lt; <TMPL_VAR PREVTITLE></a>
+</TMPL_IF> |
+<a href="<TMPL_VAR TRAILURL>">^ <TMPL_VAR TRAILTITLE> ^</a>
+| <TMPL_IF NEXTURL>
+<a href="<TMPL_VAR NEXTURL>"><TMPL_VAR NEXTTITLE> &gt;</a>
+</TMPL_IF>
+</div>
+<TMPL_IF __LAST__></nav></TMPL_IF>
+</TMPL_LOOP>
+EOF
+);
+writefile("badger.mdwn", "t/tmp/in", "[[!meta title=\"The Breezy Badger\"]]\ncontent of badger");
+writefile("mushroom.mdwn", "t/tmp/in", "content of mushroom");
+writefile("snake.mdwn", "t/tmp/in", "content of snake");
+writefile("ratty.mdwn", "t/tmp/in", "content of ratty");
+writefile("mr_toad.mdwn", "t/tmp/in", "content of mr toad");
+writefile("add.mdwn", "t/tmp/in", '[[!trail pagenames="add/a add/b add/c add/d add/e"]]');
+writefile("add/b.mdwn", "t/tmp/in", "b");
+writefile("add/d.mdwn", "t/tmp/in", "d");
+writefile("del.mdwn", "t/tmp/in", '[[!trail pages="del/*" sort=title]]');
+writefile("del/a.mdwn", "t/tmp/in", "a");
+writefile("del/b.mdwn", "t/tmp/in", "b");
+writefile("del/c.mdwn", "t/tmp/in", "c");
+writefile("del/d.mdwn", "t/tmp/in", "d");
+writefile("del/e.mdwn", "t/tmp/in", "e");
+writefile("self_referential.mdwn", "t/tmp/in", '[[!trail pagenames="self_referential" circular=yes]]');
+
+writefile("meme.mdwn", "t/tmp/in", <<EOF
+[[!trail]]
+* [[!traillink badger]]
+* [[!traillink badger text="This is a link to badger, with a title"]]
+* [[!traillink That_is_the_badger|badger]]
+* [[!traillink badger]]
+* [[!traillink mushroom]]
+* [[!traillink mushroom]]
+* [[!traillink snake]]
+* [[!traillink snake]]
+EOF
+);
+
+writefile("wind_in_the_willows.mdwn", "t/tmp/in", <<EOF
+[[!trail circular=yes sort=title pages="ratty or badger or mr_toad"]]
+[[!trailitem moley]]
+EOF
+);
+
+ok(! system("make -s ikiwiki.out"));
+
+my $command = "perl -I. ./ikiwiki.out -set usedirs=0 -plugin trail -plugin inline -url=http://example.com -cgiurl=http://example.com/ikiwiki.cgi -rss -atom -underlaydir=underlays/basewiki -set underlaydirbase=underlays -templatedir=templates t/tmp/in t/tmp/out -verbose";
+
+ok(! system($command));
+
+ok(! system("$command -refresh"));
+
+$blob = readfile("t/tmp/out/meme.html");
+ok($blob =~ /<a href="(\.\/)?badger.html">badger<\/a>/m);
+ok($blob =~ /<a href="(\.\/)?badger.html">This is a link to badger, with a title<\/a>/m);
+ok($blob =~ /<a href="(\.\/)?badger.html">That is the badger<\/a>/m);
+
+$blob = readfile("t/tmp/out/badger.html");
+ok($blob =~ /^trail=meme n=mushroom p=$/m);
+ok($blob =~ /^trail=wind_in_the_willows n=mr_toad p=ratty$/m);
+
+ok(! -f "t/tmp/out/moley.html");
+
+$blob = readfile("t/tmp/out/mr_toad.html");
+ok($blob !~ /^trail=meme/m);
+ok($blob =~ /^trail=wind_in_the_willows n=ratty p=badger$/m);
+# meta title is respected for pages that have one
+ok($blob =~ /">&lt; The Breezy Badger<\/a>/m);
+# pagetitle for pages that don't
+ok($blob =~ /">ratty &gt;<\/a>/m);
+
+$blob = readfile("t/tmp/out/ratty.html");
+ok($blob !~ /^trail=meme/m);
+ok($blob =~ /^trail=wind_in_the_willows n=badger p=mr_toad$/m);
+
+$blob = readfile("t/tmp/out/mushroom.html");
+ok($blob =~ /^trail=meme n=snake p=badger$/m);
+ok($blob !~ /^trail=wind_in_the_willows/m);
+
+$blob = readfile("t/tmp/out/snake.html");
+ok($blob =~ /^trail=meme n= p=mushroom$/m);
+ok($blob !~ /^trail=wind_in_the_willows/m);
+
+$blob = readfile("t/tmp/out/self_referential.html");
+ok($blob =~ /^trail=self_referential n= p=$/m);
+
+$blob = readfile("t/tmp/out/add/b.html");
+ok($blob =~ /^trail=add n=add\/d p=$/m);
+$blob = readfile("t/tmp/out/add/d.html");
+ok($blob =~ /^trail=add n= p=add\/b$/m);
+ok(! -f "t/tmp/out/add/a.html");
+ok(! -f "t/tmp/out/add/c.html");
+ok(! -f "t/tmp/out/add/e.html");
+
+$blob = readfile("t/tmp/out/del/a.html");
+ok($blob =~ /^trail=del n=del\/b p=$/m);
+$blob = readfile("t/tmp/out/del/b.html");
+ok($blob =~ /^trail=del n=del\/c p=del\/a$/m);
+$blob = readfile("t/tmp/out/del/c.html");
+ok($blob =~ /^trail=del n=del\/d p=del\/b$/m);
+$blob = readfile("t/tmp/out/del/d.html");
+ok($blob =~ /^trail=del n=del\/e p=del\/c$/m);
+$blob = readfile("t/tmp/out/del/e.html");
+ok($blob =~ /^trail=del n= p=del\/d$/m);
+
+# Make some changes and refresh
+
+writefile("add/a.mdwn", "t/tmp/in", "a");
+writefile("add/c.mdwn", "t/tmp/in", "c");
+writefile("add/e.mdwn", "t/tmp/in", "e");
+ok(unlink("t/tmp/in/del/a.mdwn"));
+ok(unlink("t/tmp/in/del/c.mdwn"));
+ok(unlink("t/tmp/in/del/e.mdwn"));
+
+ok(! system("$command -refresh"));
+
+$blob = readfile("t/tmp/out/add/a.html");
+ok($blob =~ /^trail=add n=add\/b p=$/m);
+$blob = readfile("t/tmp/out/add/b.html");
+ok($blob =~ /^trail=add n=add\/c p=add\/a$/m);
+$blob = readfile("t/tmp/out/add/c.html");
+ok($blob =~ /^trail=add n=add\/d p=add\/b$/m);
+$blob = readfile("t/tmp/out/add/d.html");
+ok($blob =~ /^trail=add n=add\/e p=add\/c$/m);
+$blob = readfile("t/tmp/out/add/e.html");
+ok($blob =~ /^trail=add n= p=add\/d$/m);
+
+$blob = readfile("t/tmp/out/del/b.html");
+ok($blob =~ /^trail=del n=del\/d p=$/m);
+$blob = readfile("t/tmp/out/del/d.html");
+ok($blob =~ /^trail=del n= p=del\/b$/m);
+ok(! -f "t/tmp/out/del/a.html");
+ok(! -f "t/tmp/out/del/c.html");
+ok(! -f "t/tmp/out/del/e.html");
+
+#ok(! system("rm -rf t/tmp"));
diff --git a/templates/page.tmpl b/templates/page.tmpl
index 8659018a0..770ac2399 100644
--- a/templates/page.tmpl
+++ b/templates/page.tmpl
@@ -27,6 +27,15 @@
 <TMPL_IF FEEDLINKS><TMPL_VAR FEEDLINKS></TMPL_IF>
 <TMPL_IF RELVCS><TMPL_VAR RELVCS></TMPL_IF>
 <TMPL_IF META><TMPL_VAR META></TMPL_IF>
+<TMPL_LOOP TRAILLOOP>
+<TMPL_IF PREVPAGE>
+<link rel="prev" href="<TMPL_VAR PREVURL>" title="<TMPL_VAR PREVTITLE>" />
+</TMPL_IF>
+<link rel="up" href="<TMPL_VAR TRAILURL>" title="<TMPL_VAR TRAILTITLE>" />
+<TMPL_IF NEXTPAGE>
+<link rel="next" href="<TMPL_VAR NEXTURL>" title="<TMPL_VAR NEXTTITLE>" />
+</TMPL_IF>
+</TMPL_LOOP>
 </head>
 <body>
 
@@ -103,6 +112,8 @@
 <TMPL_IF HTML5></nav><TMPL_ELSE></div></TMPL_IF>
 </TMPL_IF>
 
+<TMPL_VAR TRAILS>
+
 <TMPL_IF HTML5></section><TMPL_ELSE></div></TMPL_IF>
 
 <TMPL_IF SIDEBAR>
diff --git a/templates/trails.tmpl b/templates/trails.tmpl
new file mode 100644
index 000000000..54c046043
--- /dev/null
+++ b/templates/trails.tmpl
@@ -0,0 +1,23 @@
+<TMPL_LOOP TRAILLOOP>
+<TMPL_IF __FIRST__><TMPL_IF HTML5><nav class="trails"><TMPL_ELSE><div class="trails"></TMPL_IF></TMPL_IF>
+<div class="trail">
+<TMPL_IF PREVPAGE>
+<span class="trailprev">
+<span class="trailarrow">←</span>
+<a href="<TMPL_VAR PREVURL>"><TMPL_VAR PREVTITLE></a>
+<span class="trailsep">|</span>
+</span>
+</TMPL_IF>
+<span class="trailup">
+<a href="<TMPL_VAR TRAILURL>"><TMPL_VAR TRAILTITLE></a>
+</span>
+<TMPL_IF NEXTPAGE>
+<span class="trailnext">
+<span class="trailsep">|</span>
+<a href="<TMPL_VAR NEXTURL>"><TMPL_VAR NEXTTITLE></a>
+<span class="trailarrow">→</span>
+</span>
+</TMPL_IF>
+</div>
+<TMPL_IF __LAST__><TMPL_IF HTML5></nav><TMPL_ELSE></div></TMPL_IF></TMPL_IF>
+</TMPL_LOOP>
diff --git a/themes/actiontabs/style.css b/themes/actiontabs/style.css
index 749d9b21e..26cdc1e86 100644
--- a/themes/actiontabs/style.css
+++ b/themes/actiontabs/style.css
@@ -142,3 +142,8 @@ div.recentchanges {
 	padding: 0 0 0 2ex;
 	border-color: #999;
 }
+
+.trails {
+	/* allow space for the action tabs */
+	margin-bottom: 2em;
+}
diff --git a/themes/blueview/style.css b/themes/blueview/style.css
index c07d1cdfa..32f4b32ea 100644
--- a/themes/blueview/style.css
+++ b/themes/blueview/style.css
@@ -197,18 +197,23 @@ body {
 	font-weight: bold;
 }
 
-.pageheader .header .title, .pageheader .header .parentlinks, .pageheader .actions ul li, .pageheader .header span, .pageheader #otherlanguages ul li {
+.pageheader .header .title, .pageheader .header .parentlinks, .pageheader .actions ul li, .pageheader .header span, .pageheader #otherlanguages ul li, .trailprev, .trailnext, .trailup {
 	padding: 0.25em 0.25em 0.25em 0.25em;
 	background-image: url('background_darkness.png');
 	background-repeat: repeat;
 	color: white;
 }
 
-.pageheader .header span a, .pageheader .actions ul li a, .pageheader .header .parentlinks a, .pageheader #otherlanguages ul li a {
+.pageheader .header span a, .pageheader .actions ul li a, .pageheader .header .parentlinks a, .pageheader #otherlanguages ul li a, .pageheader a {
+	font-weight: bold;
 	color: white;
 	text-decoration: none;
 }
 
+.trailprev, .trailnext, .trailup {
+	margin-top: 0.5em;
+}
+
 .pageheader .actions {
 	text-align: right;
 	vertical-align: bottom;
-- 
cgit v1.2.3


From e0c9837566ceaa716639a11fa2e4734be7c74f62 Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@debian.org>
Date: Wed, 9 Nov 2011 22:48:20 +0000
Subject: use trailinline for the example blog so it gets next/prev links

---
 auto-blog.setup              | 2 +-
 doc/examples/blog/posts.mdwn | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/auto-blog.setup b/auto-blog.setup
index 0eb83ded6..5617daf9e 100644
--- a/auto-blog.setup
+++ b/auto-blog.setup
@@ -36,7 +36,7 @@ IkiWiki::Setup::Automator->import(
 	cgiurl => "http://$domain/~$ENV{USER}/$wikiname_short/ikiwiki.cgi",
 	cgi_wrapper => "$ENV{HOME}/public_html/$wikiname_short/ikiwiki.cgi",
 	adminemail => "$ENV{USER}\@$domain",
-	add_plugins => [qw{goodstuff websetup comments blogspam calendar sidebar}],
+	add_plugins => [qw{goodstuff websetup comments blogspam calendar sidebar trail}],
 	disable_plugins => [qw{}],
 	libdir => "$ENV{HOME}/.ikiwiki",
 	rss => 1,
diff --git a/doc/examples/blog/posts.mdwn b/doc/examples/blog/posts.mdwn
index 08e014838..6e9a3f001 100644
--- a/doc/examples/blog/posts.mdwn
+++ b/doc/examples/blog/posts.mdwn
@@ -1,3 +1,3 @@
 Here is a full list of posts to the [[blog|index]].
 
-[[!inline pages="page(./posts/*) and !*/Discussion" archive=yes feedshow=10 quick=yes]]
+[[!trailinline pages="page(./posts/*) and !*/Discussion" archive=yes feedshow=10 quick=yes]]
-- 
cgit v1.2.3


From 272e0b2f17c33c625b494b07f581da400066a216 Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@debian.org>
Date: Sat, 12 Nov 2011 15:11:02 +0000
Subject: Add path and path_natural sort orders

---
 IkiWiki.pm                        | 1 +
 IkiWiki/Plugin/sortnaturally.pm   | 5 +++++
 doc/ikiwiki/pagespec/sorting.mdwn | 6 +++++-
 3 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/IkiWiki.pm b/IkiWiki.pm
index 637d56c73..3d13cb106 100644
--- a/IkiWiki.pm
+++ b/IkiWiki.pm
@@ -2792,6 +2792,7 @@ sub cmp_title {
 	IkiWiki::pagetitle(IkiWiki::basename($b))
 }
 
+sub cmp_path { IkiWiki::pagetitle($a) cmp IkiWiki::pagetitle($b) }
 sub cmp_mtime { $IkiWiki::pagemtime{$b} <=> $IkiWiki::pagemtime{$a} }
 sub cmp_age { $IkiWiki::pagectime{$b} <=> $IkiWiki::pagectime{$a} }
 
diff --git a/IkiWiki/Plugin/sortnaturally.pm b/IkiWiki/Plugin/sortnaturally.pm
index b038b2f9a..108b489f8 100644
--- a/IkiWiki/Plugin/sortnaturally.pm
+++ b/IkiWiki/Plugin/sortnaturally.pm
@@ -30,4 +30,9 @@ sub cmp_title_natural {
 		IkiWiki::pagetitle(IkiWiki::basename($b)))
 }
 
+sub cmp_path_natural {
+	Sort::Naturally::ncmp(IkiWiki::pagetitle($a),
+		IkiWiki::pagetitle($b))
+}
+
 1;
diff --git a/doc/ikiwiki/pagespec/sorting.mdwn b/doc/ikiwiki/pagespec/sorting.mdwn
index ccd7f7eaa..0c6cc74c7 100644
--- a/doc/ikiwiki/pagespec/sorting.mdwn
+++ b/doc/ikiwiki/pagespec/sorting.mdwn
@@ -7,10 +7,14 @@ orders can be specified.
 
 * `mtime` - List pages with the most recently modified first.
 
-* `title` - Order by title (page name).
+* `title` - Order by title (page name), e.g. "z/a a/b a/c"
+
+* `path` - Order by page name including parents, e.g. "a/b a/c z/a"
 [[!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")
+
+* `path_natural` - Like `path`, but numbers in the title are treated as such
 """]]
 [[!if test="enabled(meta)" then="""
 * `meta(title)` - Order according to the `\[[!meta title="foo" sortas="bar"]]`
-- 
cgit v1.2.3


From 903a5a314f1f5d833dbc208ce128f24195b40e4b Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@debian.org>
Date: Sat, 12 Nov 2011 16:02:20 +0000
Subject: Add path and path_natural sort orders

These correspond to title and title_natural, but compare the entire
path: a < a/b < a/z < ab < b.
---
 t/cmp_path.t            | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 t/pagespec_match_list.t |  4 ++--
 2 files changed, 50 insertions(+), 2 deletions(-)
 create mode 100755 t/cmp_path.t

diff --git a/t/cmp_path.t b/t/cmp_path.t
new file mode 100755
index 000000000..9de79f49b
--- /dev/null
+++ b/t/cmp_path.t
@@ -0,0 +1,48 @@
+#!/usr/bin/perl
+use warnings;
+use strict;
+use Test::More tests => 25;
+
+BEGIN { use_ok("IkiWiki"); }
+
+%config=IkiWiki::defaultconfig();
+$config{srcdir}=$config{destdir}="/dev/null";
+IkiWiki::checkconfig();
+
+sub test {
+	my ($before, $after) = @_;
+
+	$IkiWiki::SortSpec::a = $before;
+	$IkiWiki::SortSpec::b = $after;
+	my $r = IkiWiki::SortSpec::cmp_path();
+
+	if ($before eq $after) {
+		is($r, 0);
+	}
+	else {
+		is($r, -1);
+	}
+
+	$IkiWiki::SortSpec::a = $after;
+	$IkiWiki::SortSpec::b = $before;
+	$r = IkiWiki::SortSpec::cmp_path();
+
+	if ($before eq $after) {
+		is($r, 0);
+	}
+	else {
+		is($r, 1);
+	}
+
+	is_deeply([IkiWiki::SortSpec::sort_pages(\&IkiWiki::SortSpec::cmp_path, $before, $after)],
+		[$before, $after]);
+	is_deeply([IkiWiki::SortSpec::sort_pages(\&IkiWiki::SortSpec::cmp_path, $after, $before)],
+		[$before, $after]);
+}
+
+test("a/b/c", "a/b/c");
+test("a/b", "a/c");
+test("a/z", "z/a");
+test("a", "a/b");
+test("a", "a/b");
+test("a/z", "ab");
diff --git a/t/pagespec_match_list.t b/t/pagespec_match_list.t
index 244ad9159..7ff178aad 100755
--- a/t/pagespec_match_list.t
+++ b/t/pagespec_match_list.t
@@ -12,7 +12,7 @@ IkiWiki::checkconfig();
 {
 	package IkiWiki::SortSpec;
 
-	sub cmp_path { $a cmp $b }
+	sub cmp_raw_path { $a cmp $b }
 }
 
 %pagesources=(
@@ -53,7 +53,7 @@ is_deeply([pagespec_match_list("foo", "post/*", sort => "title", num => 50, reve
 is_deeply([pagespec_match_list("foo", "post/*", sort => "title",
                          filter => sub { $_[0] =~ /3/}) ],
 	["post/1", "post/2"]);
-is_deeply([pagespec_match_list("foo", "*", sort => "path", num => 2)],
+is_deeply([pagespec_match_list("foo", "*", sort => "raw_path", num => 2)],
 	["bar", "foo"]);
 is_deeply([pagespec_match_list("foo", "foo* or bar*",
 		sort => "-age title")], # oldest first, break ties by title
-- 
cgit v1.2.3


From 0394a49e67485414591e041aa3dbf3b3eb0b1854 Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@debian.org>
Date: Sat, 12 Nov 2011 16:57:27 +0000
Subject: trail: avoid collecting trail members twice

---
 IkiWiki/Plugin/trail.pm | 49 +++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 43 insertions(+), 6 deletions(-)

diff --git a/IkiWiki/Plugin/trail.pm b/IkiWiki/Plugin/trail.pm
index e9b4d9cd4..e6e55bbdb 100644
--- a/IkiWiki/Plugin/trail.pm
+++ b/IkiWiki/Plugin/trail.pm
@@ -88,6 +88,8 @@ sub needsbuild (@) {
 	return $needsbuild;
 }
 
+my $scanned = 0;
+
 =for wiki
 
 The `trail` directive is supplied by the [[plugins/contrib/trail]]
@@ -112,6 +114,15 @@ The available options are:
 sub preprocess_trail (@) {
 	my %params = @_;
 
+	# avoid collecting everything in the preprocess stage if we already
+	# did in the scan stage
+	if (defined wantarray) {
+		return "" if $scanned;
+	}
+	else {
+		$scanned = 1;
+	}
+
 	if (exists $params{circular}) {
 		$pagestate{$params{page}}{trail}{circular} =
 			IkiWiki::yesno($params{circular});
@@ -166,14 +177,20 @@ to the trail.
 =cut
 
 sub preprocess_trailinline (@) {
-	preprocess_trail(@_);
-	return unless defined wantarray;
+	my %params = @_;
+
+	if (defined wantarray) {
+		scalar preprocess_trail(%params);
 
-	if (IkiWiki->can("preprocess_inline")) {
-		return IkiWiki::preprocess_inline(@_);
+		if (IkiWiki->can("preprocess_inline")) {
+			return IkiWiki::preprocess_inline(@_);
+		}
+		else {
+			error("trailinline directive requires the inline plugin");
+		}
 	}
 	else {
-		error("trailinline directive requires the inline plugin");
+		preprocess_trail(%params);
 	}
 }
 
@@ -193,6 +210,15 @@ sub preprocess_trailitem (@) {
 	my $link = shift;
 	shift;
 
+	# avoid collecting everything in the preprocess stage if we already
+	# did in the scan stage
+	if (defined wantarray) {
+		return "" if $scanned;
+	}
+	else {
+		$scanned = 1;
+	}
+
 	my %params = @_;
 	my $trail = $params{page};
 
@@ -242,7 +268,18 @@ sub preprocess_traillink (@) {
 	$link = linkpage($2);
 
 	add_link($params{page}, $link, 'trail');
-	push @{$pagestate{$params{page}}{trail}{contents}}, "link $link";
+
+	# avoid collecting everything in the preprocess stage if we already
+	# did in the scan stage
+	my $already;
+	if (defined wantarray) {
+		$already = $scanned;
+	}
+	else {
+		$scanned = 1;
+	}
+
+	push @{$pagestate{$params{page}}{trail}{contents}}, [link => $link] unless $already;
 
 	if (defined $linktext) {
 		$linktext = pagetitle($linktext);
-- 
cgit v1.2.3


From e0bfd0cafda6a44a826cdfe07b99299cc96dfdf3 Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@debian.org>
Date: Sat, 12 Nov 2011 16:57:54 +0000
Subject: trail: improve and test sorting

---
 IkiWiki/Plugin/trail.pm | 46 ++++++++++++++++++++++++------
 t/trail.t               | 75 ++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 112 insertions(+), 9 deletions(-)

diff --git a/IkiWiki/Plugin/trail.pm b/IkiWiki/Plugin/trail.pm
index e6e55bbdb..87d99dd3d 100644
--- a/IkiWiki/Plugin/trail.pm
+++ b/IkiWiki/Plugin/trail.pm
@@ -123,6 +123,11 @@ sub preprocess_trail (@) {
 		$scanned = 1;
 	}
 
+	# trail members from a pagespec ought to be in some sort of order,
+	# and path is a nice obvious default
+	$params{sortthese} = 'path' unless exists $params{sortthese};
+	$params{reversethese} = 'no' unless exists $params{reversethese};
+
 	if (exists $params{circular}) {
 		$pagestate{$params{page}}{trail}{circular} =
 			IkiWiki::yesno($params{circular});
@@ -137,11 +142,13 @@ sub preprocess_trail (@) {
 	}
 
 	if (exists $params{pages}) {
-		push @{$pagestate{$params{page}}{trail}{contents}}, "pagespec $params{pages}";
+		push @{$pagestate{$params{page}}{trail}{contents}},
+			["pagespec" => $params{pages}, $params{sortthese},
+				IkiWiki::yesno($params{reversethese})];
 	}
 
 	if (exists $params{pagenames}) {
-		my @list = map { "link $_" } split ' ', $params{pagenames};
+		my @list = map { [link =>  $_] } split ' ', $params{pagenames};
 		push @{$pagestate{$params{page}}{trail}{contents}}, @list;
 	}
 
@@ -179,6 +186,28 @@ to the trail.
 sub preprocess_trailinline (@) {
 	my %params = @_;
 
+	if (exists $params{sort}) {
+		$params{sortthese} = $params{sort};
+		delete $params{sort};
+	}
+	else {
+		# sort in the same order as [[plugins/inline]]'s default
+		$params{sortthese} = 'age';
+	}
+
+	if (exists $params{reverse}) {
+		$params{reversethese} = $params{reverse};
+		delete $params{reverse};
+	}
+
+	if (exists $params{trailsort}) {
+		$params{sort} = $params{trailsort};
+	}
+
+	if (exists $params{trailreverse}) {
+		$params{reverse} = $params{trailreverse};
+	}
+
 	if (defined wantarray) {
 		scalar preprocess_trail(%params);
 
@@ -225,7 +254,7 @@ sub preprocess_trailitem (@) {
 	$link = linkpage($link);
 
 	add_link($params{page}, $link, 'trail');
-	push @{$pagestate{$params{page}}{trail}{contents}}, "link $link";
+	push @{$pagestate{$params{page}}{trail}{contents}}, [link => $link];
 
 	return "";
 }
@@ -363,13 +392,14 @@ sub prerender {
 		my $members = [];
 		my @contents = @{$pagestate{$trail}{trail}{contents}};
 
-
 		foreach my $c (@contents) {
-			if ($c =~ m/^pagespec (.*)$/) {
-				push @$members, pagespec_match_list($trail, $1);
+			if ($c->[0] eq 'pagespec') {
+				push @$members, pagespec_match_list($trail,
+					$c->[1], sort => $c->[2],
+					reverse => $c->[3]);
 			}
-			elsif ($c =~ m/^link (.*)$/) {
-				my $best = bestlink($trail, $1);
+			elsif ($c->[0] eq 'link') {
+				my $best = bestlink($trail, $c->[1]);
 				push @$members, $best if length $best;
 			}
 		}
diff --git a/t/trail.t b/t/trail.t
index ce7d92048..28aa1c09d 100755
--- a/t/trail.t
+++ b/t/trail.t
@@ -45,6 +45,29 @@ writefile("del/c.mdwn", "t/tmp/in", "c");
 writefile("del/d.mdwn", "t/tmp/in", "d");
 writefile("del/e.mdwn", "t/tmp/in", "e");
 writefile("self_referential.mdwn", "t/tmp/in", '[[!trail pagenames="self_referential" circular=yes]]');
+writefile("sorting/linked.mdwn", "t/tmp/in", "linked");
+writefile("sorting/a/b.mdwn", "t/tmp/in", "a/b");
+writefile("sorting/a/c.mdwn", "t/tmp/in", "a/c");
+writefile("sorting/z/a.mdwn", "t/tmp/in", "z/a");
+writefile("sorting/beginning.mdwn", "t/tmp/in", "beginning");
+writefile("sorting/middle.mdwn", "t/tmp/in", "middle");
+writefile("sorting/end.mdwn", "t/tmp/in", "end");
+writefile("sorting/new.mdwn", "t/tmp/in", "new");
+writefile("sorting/old.mdwn", "t/tmp/in", "old");
+writefile("sorting/ancient.mdwn", "t/tmp/in", "ancient");
+# These three need to be in the appropriate age order
+ok(utime(333333333, 333333333, "t/tmp/in/sorting/new.mdwn"));
+ok(utime(222222222, 222222222, "t/tmp/in/sorting/old.mdwn"));
+ok(utime(111111111, 111111111, "t/tmp/in/sorting/ancient.mdwn"));
+writefile("sorting/linked2.mdwn", "t/tmp/in", "linked2");
+# This initially uses the default sort order: age for trailinline, and path
+# for trail. We change it later.
+writefile("sorting.mdwn", "t/tmp/in",
+	'[[!traillink linked]] ' .
+	'[[!trail pages="sorting/z/a or sorting/a/b or sorting/a/c"]] ' .
+	'[[!trail pagenames="beginning middle end"]] ' .
+	'[[!trailinline pages="sorting/old or sorting/ancient or sorting/new"]] ' .
+	'[[!traillink linked2]]');
 
 writefile("meme.mdwn", "t/tmp/in", <<EOF
 [[!trail]]
@@ -126,6 +149,29 @@ ok($blob =~ /^trail=del n=del\/e p=del\/c$/m);
 $blob = readfile("t/tmp/out/del/e.html");
 ok($blob =~ /^trail=del n= p=del\/d$/m);
 
+$blob = readfile("t/tmp/out/sorting/linked.html");
+ok($blob =~ m{^trail=sorting n=sorting/a/b p=$}m);
+$blob = readfile("t/tmp/out/sorting/a/b.html");
+ok($blob =~ m{^trail=sorting n=sorting/a/c p=sorting/linked$}m);
+$blob = readfile("t/tmp/out/sorting/a/c.html");
+ok($blob =~ m{^trail=sorting n=sorting/z/a p=sorting/a/b$}m);
+$blob = readfile("t/tmp/out/sorting/z/a.html");
+ok($blob =~ m{^trail=sorting n=sorting/beginning p=sorting/a/c$}m);
+$blob = readfile("t/tmp/out/sorting/beginning.html");
+ok($blob =~ m{^trail=sorting n=sorting/middle p=sorting/z/a$}m);
+$blob = readfile("t/tmp/out/sorting/middle.html");
+ok($blob =~ m{^trail=sorting n=sorting/end p=sorting/beginning$}m);
+$blob = readfile("t/tmp/out/sorting/end.html");
+ok($blob =~ m{^trail=sorting n=sorting/new p=sorting/middle$}m);
+$blob = readfile("t/tmp/out/sorting/new.html");
+ok($blob =~ m{^trail=sorting n=sorting/old p=sorting/end$}m);
+$blob = readfile("t/tmp/out/sorting/old.html");
+ok($blob =~ m{^trail=sorting n=sorting/ancient p=sorting/new$}m);
+$blob = readfile("t/tmp/out/sorting/ancient.html");
+ok($blob =~ m{^trail=sorting n=sorting/linked2 p=sorting/old$}m);
+$blob = readfile("t/tmp/out/sorting/linked2.html");
+ok($blob =~ m{^trail=sorting n= p=sorting/ancient$}m);
+
 # Make some changes and refresh
 
 writefile("add/a.mdwn", "t/tmp/in", "a");
@@ -135,6 +181,10 @@ ok(unlink("t/tmp/in/del/a.mdwn"));
 ok(unlink("t/tmp/in/del/c.mdwn"));
 ok(unlink("t/tmp/in/del/e.mdwn"));
 
+writefile("sorting.mdwn", "t/tmp/in",
+	readfile("t/tmp/in/sorting.mdwn") .
+	'[[!trailinline pages="doesnt_exist" trailsort="title" trailreverse="yes"]]'); 
+
 ok(! system("$command -refresh"));
 
 $blob = readfile("t/tmp/out/add/a.html");
@@ -156,4 +206,27 @@ ok(! -f "t/tmp/out/del/a.html");
 ok(! -f "t/tmp/out/del/c.html");
 ok(! -f "t/tmp/out/del/e.html");
 
-#ok(! system("rm -rf t/tmp"));
+$blob = readfile("t/tmp/out/sorting/old.html");
+ok($blob =~ m{^trail=sorting n=sorting/new p=$}m);
+$blob = readfile("t/tmp/out/sorting/new.html");
+ok($blob =~ m{^trail=sorting n=sorting/middle p=sorting/old$}m);
+$blob = readfile("t/tmp/out/sorting/middle.html");
+ok($blob =~ m{^trail=sorting n=sorting/linked2 p=sorting/new$}m);
+$blob = readfile("t/tmp/out/sorting/linked2.html");
+ok($blob =~ m{^trail=sorting n=sorting/linked p=sorting/middle$}m);
+$blob = readfile("t/tmp/out/sorting/linked.html");
+ok($blob =~ m{^trail=sorting n=sorting/end p=sorting/linked2$}m);
+$blob = readfile("t/tmp/out/sorting/end.html");
+ok($blob =~ m{^trail=sorting n=sorting/a/c p=sorting/linked$}m);
+$blob = readfile("t/tmp/out/sorting/a/c.html");
+ok($blob =~ m{^trail=sorting n=sorting/beginning p=sorting/end$}m);
+$blob = readfile("t/tmp/out/sorting/beginning.html");
+ok($blob =~ m{^trail=sorting n=sorting/a/b p=sorting/a/c$}m);
+$blob = readfile("t/tmp/out/sorting/a/b.html");
+ok($blob =~ m{^trail=sorting n=sorting/ancient p=sorting/beginning$}m);
+$blob = readfile("t/tmp/out/sorting/ancient.html");
+ok($blob =~ m{^trail=sorting n=sorting/z/a p=sorting/a/b$}m);
+$blob = readfile("t/tmp/out/sorting/z/a.html");
+ok($blob =~ m{^trail=sorting n= p=sorting/ancient$}m);
+
+ok(! system("rm -rf t/tmp"));
-- 
cgit v1.2.3


From 74b1b2761ac21e73376d714503aad326dd6f8fec Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@debian.org>
Date: Sat, 12 Nov 2011 17:08:08 +0000
Subject: trail: update documentation; drop docs for directives, which are now
 in the wiki

---
 IkiWiki/Plugin/trail.pm | 94 ++++++++-----------------------------------------
 1 file changed, 14 insertions(+), 80 deletions(-)

diff --git a/IkiWiki/Plugin/trail.pm b/IkiWiki/Plugin/trail.pm
index 87d99dd3d..098b98607 100644
--- a/IkiWiki/Plugin/trail.pm
+++ b/IkiWiki/Plugin/trail.pm
@@ -27,7 +27,20 @@ If a page C<$T> is a trail, then it can have
 
 =item * C<$pagestate{$T}{trail}{contents}>
 
-Reference to an array of pagespecs or links in the trail.
+Reference to an array of lists each containing either:
+
+=over
+
+=item * C<[link, "link"]>
+
+A link specification, pointing to the same page that C<[[link]]> would select
+
+=item * C<[pagespec, "posts/*", "age", 0]>
+
+A match by pagespec; the third array element is the sort order and the fourth
+is whether to reverse sorting
+
+=back
 
 =item * C<$pagestate{$T}{trail}{sort}>
 
@@ -90,27 +103,6 @@ sub needsbuild (@) {
 
 my $scanned = 0;
 
-=for wiki
-
-The `trail` directive is supplied by the [[plugins/contrib/trail]]
-plugin. It sets options for the trail represented by this page. Example usage:
-
-    \[[!trail sort="meta(date)" circular="no" pages="blog/posts/*"]]
-
-The available options are:
-
-* `sort`: sets a [[ikiwiki/pagespec/sorting]] order; if not specified, the
-  items of the trail are ordered according to the first link to each item
-  found on the trail page
-
-* `circular`: if set to `yes` or `1`, the trail is made into a loop by
-  making the last page's "next" link point to the first page, and the first
-  page's "previous" link point to the last page
-
-* `pages`: add the given pages to the trail
-
-=cut
-
 sub preprocess_trail (@) {
 	my %params = @_;
 
@@ -155,34 +147,6 @@ sub preprocess_trail (@) {
 	return "";
 }
 
-=for wiki
-
-The `trailinline` directive is supplied by the [[plugins/contrib/trail]]
-plugin. It behaves like the [[trail]] and [[inline]] directives combined.
-Like [[inline]], it includes the selected pages into the page with the
-directive and/or an RSS or Atom feed; like [[trail]], it turns the
-included pages into a "trail" in which each page has a link to the
-previous and next pages.
-
-    \[[!inline sort="meta(date)" circular="no" pages="blog/posts/*"]]
-
-All the options for the [[inline]] and [[trail]] directives are valid.
-
-The `show`, `skip` and `feedshow` options from [[inline]] do not apply
-to the trail.
-
-* `sort`: sets a [[ikiwiki/pagespec/sorting]] order; if not specified, the
-  items of the trail are ordered according to the first link to each item
-  found on the trail page
-
-* `circular`: if set to `yes` or `1`, the trail is made into a loop by
-  making the last page's "next" link point to the first page, and the first
-  page's "previous" link point to the last page
-
-* `pages`: add the given pages to the trail
-
-=cut
-
 sub preprocess_trailinline (@) {
 	my %params = @_;
 
@@ -223,18 +187,6 @@ sub preprocess_trailinline (@) {
 	}
 }
 
-=for wiki
-
-The `trailitem` directive is supplied by the [[plugins/contrib/trail]] plugin.
-It is used like this:
-
-    \[[!trailitem some_other_page]]
-
-to add `some_other_page` to the trail represented by this page, without
-generating a visible hyperlink.
-
-=cut
-
 sub preprocess_trailitem (@) {
 	my $link = shift;
 	shift;
@@ -259,24 +211,6 @@ sub preprocess_trailitem (@) {
 	return "";
 }
 
-=for wiki
-
-The `traillink` directive is supplied by the [[plugins/contrib/trail]] plugin.
-It generates a visible [[ikiwiki/WikiLink]], and also adds the linked page to
-the trail represented by the page containing the directive.
-
-In its simplest form, the first parameter is like the content of a WikiLink:
-
-    \[[!traillink some_other_page]]
-
-The displayed text can also be overridden, either with a `|` symbol or with
-a `text` parameter:
-
-    \[[!traillink Click_here_to_start_the_trail|some_other_page]]
-    \[[!traillink some_other_page text="Click here to start the trail"]]
-
-=cut
-
 sub preprocess_traillink (@) {
 	my $link = shift;
 	shift;
-- 
cgit v1.2.3


From d70ba7cff3fc6cc78ea2f8eb0713212478ab6ba7 Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@debian.org>
Date: Sat, 12 Nov 2011 21:37:28 +0000
Subject: Split trail directive into trailitems, trailoptions

---
 IkiWiki/Plugin/trail.pm | 86 ++++++++++++++++++++++---------------------------
 t/trail.t               | 15 +++++----
 2 files changed, 46 insertions(+), 55 deletions(-)

diff --git a/IkiWiki/Plugin/trail.pm b/IkiWiki/Plugin/trail.pm
index 098b98607..5ee152155 100644
--- a/IkiWiki/Plugin/trail.pm
+++ b/IkiWiki/Plugin/trail.pm
@@ -12,9 +12,10 @@ use IkiWiki 3.00;
 sub import {
 	hook(type => "getsetup", id => "trail", call => \&getsetup);
 	hook(type => "needsbuild", id => "trail", call => \&needsbuild);
-	hook(type => "preprocess", id => "trail", call => \&preprocess_trail, scan => 1);
+	hook(type => "preprocess", id => "trailoptions", call => \&preprocess_trailoptions, scan => 1);
 	hook(type => "preprocess", id => "trailinline", call => \&preprocess_trailinline, scan => 1);
 	hook(type => "preprocess", id => "trailitem", call => \&preprocess_trailitem, scan => 1);
+	hook(type => "preprocess", id => "trailitems", call => \&preprocess_trailitems, scan => 1);
 	hook(type => "preprocess", id => "traillink", call => \&preprocess_traillink, scan => 1);
 	hook(type => "pagetemplate", id => "trail", call => \&pagetemplate);
 }
@@ -103,23 +104,9 @@ sub needsbuild (@) {
 
 my $scanned = 0;
 
-sub preprocess_trail (@) {
+sub preprocess_trailoptions (@) {
 	my %params = @_;
 
-	# avoid collecting everything in the preprocess stage if we already
-	# did in the scan stage
-	if (defined wantarray) {
-		return "" if $scanned;
-	}
-	else {
-		$scanned = 1;
-	}
-
-	# trail members from a pagespec ought to be in some sort of order,
-	# and path is a nice obvious default
-	$params{sortthese} = 'path' unless exists $params{sortthese};
-	$params{reversethese} = 'no' unless exists $params{reversethese};
-
 	if (exists $params{circular}) {
 		$pagestate{$params{page}}{trail}{circular} =
 			IkiWiki::yesno($params{circular});
@@ -133,47 +120,19 @@ sub preprocess_trail (@) {
 		$pagestate{$params{page}}{trail}{reverse} = $params{reverse};
 	}
 
-	if (exists $params{pages}) {
-		push @{$pagestate{$params{page}}{trail}{contents}},
-			["pagespec" => $params{pages}, $params{sortthese},
-				IkiWiki::yesno($params{reversethese})];
-	}
-
-	if (exists $params{pagenames}) {
-		my @list = map { [link =>  $_] } split ' ', $params{pagenames};
-		push @{$pagestate{$params{page}}{trail}{contents}}, @list;
-	}
-
 	return "";
 }
 
 sub preprocess_trailinline (@) {
 	my %params = @_;
 
-	if (exists $params{sort}) {
-		$params{sortthese} = $params{sort};
-		delete $params{sort};
-	}
-	else {
+	if (! exists $params{sort}) {
 		# sort in the same order as [[plugins/inline]]'s default
-		$params{sortthese} = 'age';
-	}
-
-	if (exists $params{reverse}) {
-		$params{reversethese} = $params{reverse};
-		delete $params{reverse};
-	}
-
-	if (exists $params{trailsort}) {
-		$params{sort} = $params{trailsort};
-	}
-
-	if (exists $params{trailreverse}) {
-		$params{reverse} = $params{trailreverse};
+		$params{sort} = 'age';
 	}
 
 	if (defined wantarray) {
-		scalar preprocess_trail(%params);
+		scalar preprocess_trailitems(%params);
 
 		if (IkiWiki->can("preprocess_inline")) {
 			return IkiWiki::preprocess_inline(@_);
@@ -183,7 +142,7 @@ sub preprocess_trailinline (@) {
 		}
 	}
 	else {
-		preprocess_trail(%params);
+		preprocess_trailitems(%params);
 	}
 }
 
@@ -211,6 +170,37 @@ sub preprocess_trailitem (@) {
 	return "";
 }
 
+sub preprocess_trailitems (@) {
+	my %params = @_;
+
+	# avoid collecting everything in the preprocess stage if we already
+	# did in the scan stage
+	if (defined wantarray) {
+		return "" if $scanned;
+	}
+	else {
+		$scanned = 1;
+	}
+
+	# trail members from a pagespec ought to be in some sort of order,
+	# and path is a nice obvious default
+	$params{sort} = 'path' unless exists $params{sort};
+	$params{reverse} = 'no' unless exists $params{reverse};
+
+	if (exists $params{pages}) {
+		push @{$pagestate{$params{page}}{trail}{contents}},
+			["pagespec" => $params{pages}, $params{sort},
+				IkiWiki::yesno($params{reverse})];
+	}
+
+	if (exists $params{pagenames}) {
+		my @list = map { [link =>  $_] } split ' ', $params{pagenames};
+		push @{$pagestate{$params{page}}{trail}{contents}}, @list;
+	}
+
+	return "";
+}
+
 sub preprocess_traillink (@) {
 	my $link = shift;
 	shift;
diff --git a/t/trail.t b/t/trail.t
index 28aa1c09d..0cf50ddc1 100755
--- a/t/trail.t
+++ b/t/trail.t
@@ -35,16 +35,16 @@ writefile("mushroom.mdwn", "t/tmp/in", "content of mushroom");
 writefile("snake.mdwn", "t/tmp/in", "content of snake");
 writefile("ratty.mdwn", "t/tmp/in", "content of ratty");
 writefile("mr_toad.mdwn", "t/tmp/in", "content of mr toad");
-writefile("add.mdwn", "t/tmp/in", '[[!trail pagenames="add/a add/b add/c add/d add/e"]]');
+writefile("add.mdwn", "t/tmp/in", '[[!trailitems pagenames="add/a add/b add/c add/d add/e"]]');
 writefile("add/b.mdwn", "t/tmp/in", "b");
 writefile("add/d.mdwn", "t/tmp/in", "d");
-writefile("del.mdwn", "t/tmp/in", '[[!trail pages="del/*" sort=title]]');
+writefile("del.mdwn", "t/tmp/in", '[[!trailitems pages="del/*" sort=title]]');
 writefile("del/a.mdwn", "t/tmp/in", "a");
 writefile("del/b.mdwn", "t/tmp/in", "b");
 writefile("del/c.mdwn", "t/tmp/in", "c");
 writefile("del/d.mdwn", "t/tmp/in", "d");
 writefile("del/e.mdwn", "t/tmp/in", "e");
-writefile("self_referential.mdwn", "t/tmp/in", '[[!trail pagenames="self_referential" circular=yes]]');
+writefile("self_referential.mdwn", "t/tmp/in", '[[!trailitems pagenames="self_referential" circular=yes]]');
 writefile("sorting/linked.mdwn", "t/tmp/in", "linked");
 writefile("sorting/a/b.mdwn", "t/tmp/in", "a/b");
 writefile("sorting/a/c.mdwn", "t/tmp/in", "a/c");
@@ -64,8 +64,8 @@ writefile("sorting/linked2.mdwn", "t/tmp/in", "linked2");
 # for trail. We change it later.
 writefile("sorting.mdwn", "t/tmp/in",
 	'[[!traillink linked]] ' .
-	'[[!trail pages="sorting/z/a or sorting/a/b or sorting/a/c"]] ' .
-	'[[!trail pagenames="beginning middle end"]] ' .
+	'[[!trailitems pages="sorting/z/a or sorting/a/b or sorting/a/c"]] ' .
+	'[[!trailitems pagenames="beginning middle end"]] ' .
 	'[[!trailinline pages="sorting/old or sorting/ancient or sorting/new"]] ' .
 	'[[!traillink linked2]]');
 
@@ -83,7 +83,8 @@ EOF
 );
 
 writefile("wind_in_the_willows.mdwn", "t/tmp/in", <<EOF
-[[!trail circular=yes sort=title pages="ratty or badger or mr_toad"]]
+[[!trailoptions circular=yes sort=title]]
+[[!trailitems pages="ratty or badger or mr_toad"]]
 [[!trailitem moley]]
 EOF
 );
@@ -183,7 +184,7 @@ ok(unlink("t/tmp/in/del/e.mdwn"));
 
 writefile("sorting.mdwn", "t/tmp/in",
 	readfile("t/tmp/in/sorting.mdwn") .
-	'[[!trailinline pages="doesnt_exist" trailsort="title" trailreverse="yes"]]'); 
+	'[[!trailoptions sort="title" reverse="yes"]]'); 
 
 ok(! system("$command -refresh"));
 
-- 
cgit v1.2.3


From dc3b9934d5660a085d9b5e041b7e8749493b9360 Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@debian.org>
Date: Sun, 18 Mar 2012 17:01:45 +0000
Subject: Move trail out of the contrib directory in preparation for eventual
 merge

---
 doc/ikiwiki/directive/trailinline.mdwn             |  11 ++
 doc/ikiwiki/directive/trailitem.mdwn               |   9 ++
 doc/ikiwiki/directive/trailitems.mdwn              |  24 ++++
 doc/ikiwiki/directive/traillink.mdwn               |  16 +++
 doc/ikiwiki/directive/trailoptions.mdwn            |  18 +++
 .../contrib/ikiwiki/directive/trailinline.mdwn     |  11 --
 .../contrib/ikiwiki/directive/trailitem.mdwn       |   9 --
 .../contrib/ikiwiki/directive/trailitems.mdwn      |  24 ----
 .../contrib/ikiwiki/directive/traillink.mdwn       |  16 ---
 .../contrib/ikiwiki/directive/trailoptions.mdwn    |  18 ---
 doc/plugins/contrib/trail.mdwn                     | 133 ---------------------
 doc/plugins/trail.mdwn                             |  76 ++++++++++++
 12 files changed, 154 insertions(+), 211 deletions(-)
 create mode 100644 doc/ikiwiki/directive/trailinline.mdwn
 create mode 100644 doc/ikiwiki/directive/trailitem.mdwn
 create mode 100644 doc/ikiwiki/directive/trailitems.mdwn
 create mode 100644 doc/ikiwiki/directive/traillink.mdwn
 create mode 100644 doc/ikiwiki/directive/trailoptions.mdwn
 delete mode 100644 doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn
 delete mode 100644 doc/plugins/contrib/ikiwiki/directive/trailitem.mdwn
 delete mode 100644 doc/plugins/contrib/ikiwiki/directive/trailitems.mdwn
 delete mode 100644 doc/plugins/contrib/ikiwiki/directive/traillink.mdwn
 delete mode 100644 doc/plugins/contrib/ikiwiki/directive/trailoptions.mdwn
 delete mode 100644 doc/plugins/contrib/trail.mdwn
 create mode 100644 doc/plugins/trail.mdwn

diff --git a/doc/ikiwiki/directive/trailinline.mdwn b/doc/ikiwiki/directive/trailinline.mdwn
new file mode 100644
index 000000000..e32fb34d0
--- /dev/null
+++ b/doc/ikiwiki/directive/trailinline.mdwn
@@ -0,0 +1,11 @@
+The `trailinline` directive is provided by the
+[[!iki plugins/trail desc=trail]]
+plugin. It is equivalent to combining [[ikiwiki/directive/trailitems]] and
+[[ikiwiki/directive/inline]] directives with the same options.
+
+A typical use is to navigate through all posts in a blog:
+
+      \[[!trailinline pages="page(./posts/*) and !*/Discussion" archive=yes
+        feedshow=10 quick=yes]]
+
+[[!meta robots="noindex, follow"]]
diff --git a/doc/ikiwiki/directive/trailitem.mdwn b/doc/ikiwiki/directive/trailitem.mdwn
new file mode 100644
index 000000000..59626b5a1
--- /dev/null
+++ b/doc/ikiwiki/directive/trailitem.mdwn
@@ -0,0 +1,9 @@
+The `trailitem` directive is supplied by the
+[[!iki plugins/trail desc=trail]] plugin. It is used like this:
+
+    \[[!trailitem some_other_page]]
+
+to add `some_other_page` to the trail represented by this page, without
+generating a visible hyperlink.
+
+[[!meta robots="noindex, follow"]]
diff --git a/doc/ikiwiki/directive/trailitems.mdwn b/doc/ikiwiki/directive/trailitems.mdwn
new file mode 100644
index 000000000..b1ba8d356
--- /dev/null
+++ b/doc/ikiwiki/directive/trailitems.mdwn
@@ -0,0 +1,24 @@
+The `trailitems` directive is supplied by the
+[[!iki plugins/trail desc=trail]] plugin. It adds pages
+to the trail represented by the current page, without producing any output
+on that page.
+
+    \[[!trailitems pages="posts/*" sort="age"]]
+
+    \[[!trailitems pagenames="a b c"]]
+
+Options are similar to [[!iki ikiwiki/directive/inline desc=inline]]:
+
+* `pages`: adds pages that match a [[ikiwiki/PageSpec]] to the trail
+  (cannot be used with `pagenames`)
+
+* `pagenames`: adds a space-separated list of pages to the trail,
+  with the same [[ikiwiki/SubPage/LinkingRules]] as for a [[ikiwiki/WikiLink]]
+  (cannot be used with `pages`)
+
+* `sort`: add the pages matched by `pages` to the trail in this
+  [[ikiwiki/pagespec/sorting]] order (cannot be used with `pagenames`)
+
+* `reverse`: reverse the order of `sort` (cannot be used with `pagenames`)
+
+[[!meta robots="noindex, follow"]]
diff --git a/doc/ikiwiki/directive/traillink.mdwn b/doc/ikiwiki/directive/traillink.mdwn
new file mode 100644
index 000000000..090e2538d
--- /dev/null
+++ b/doc/ikiwiki/directive/traillink.mdwn
@@ -0,0 +1,16 @@
+The `traillink` directive is supplied by the
+[[!iki plugins/trail desc=trail]]
+plugin. It generates a visible [[ikiwiki/WikiLink]], and also adds the
+linked page to the trail represented by the page containing the directive.
+
+In its simplest form, the first parameter is like the content of a WikiLink:
+
+    \[[!traillink some_other_page]]
+
+The displayed text can also be overridden, either with a `|` symbol or with
+a `text` parameter:
+
+    \[[!traillink Click_here_to_start_the_trail|some_other_page]]
+    \[[!traillink some_other_page text="Click here to start the trail"]]
+
+[[!meta robots="noindex, follow"]]
diff --git a/doc/ikiwiki/directive/trailoptions.mdwn b/doc/ikiwiki/directive/trailoptions.mdwn
new file mode 100644
index 000000000..d83f444c0
--- /dev/null
+++ b/doc/ikiwiki/directive/trailoptions.mdwn
@@ -0,0 +1,18 @@
+The `trailoptions` directive is supplied by the
+[[!iki plugins/trail desc=trail]] plugin. It sets options for the
+trail represented by this page.
+
+    \[[!trailoptions sort="meta(title)" circular="no"]]
+
+Options available:
+
+* `sort`: sets a [[ikiwiki/pagespec/sorting]] order for the entire trail,
+  overriding the order in which they were added
+
+* `reverse`: reverses the order of the trail
+
+* `circular`: if set to `yes` or `1`, the trail is made into a loop by
+  making the last page's "next" link point to the first page, and the first
+  page's "previous" link point to the last page
+
+[[!meta robots="noindex, follow"]]
diff --git a/doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn
deleted file mode 100644
index 91d8a4edf..000000000
--- a/doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn
+++ /dev/null
@@ -1,11 +0,0 @@
-The `trailinline` directive is provided by the
-[[!iki plugins/contrib/trail desc=trail]]
-plugin. It is equivalent to combining [[ikiwiki/directive/trailitems]] and
-[[ikiwiki/directive/inline]] directives with the same options.
-
-A typical use is to navigate through all posts in a blog:
-
-      \[[!trailinline pages="page(./posts/*) and !*/Discussion" archive=yes
-        feedshow=10 quick=yes]]
-
-[[!meta robots="noindex, follow"]]
diff --git a/doc/plugins/contrib/ikiwiki/directive/trailitem.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailitem.mdwn
deleted file mode 100644
index 73b1985a5..000000000
--- a/doc/plugins/contrib/ikiwiki/directive/trailitem.mdwn
+++ /dev/null
@@ -1,9 +0,0 @@
-The `trailitem` directive is supplied by the
-[[!iki plugins/contrib/trail desc=trail]] plugin. It is used like this:
-
-    \[[!trailitem some_other_page]]
-
-to add `some_other_page` to the trail represented by this page, without
-generating a visible hyperlink.
-
-[[!meta robots="noindex, follow"]]
diff --git a/doc/plugins/contrib/ikiwiki/directive/trailitems.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailitems.mdwn
deleted file mode 100644
index 4106ed33b..000000000
--- a/doc/plugins/contrib/ikiwiki/directive/trailitems.mdwn
+++ /dev/null
@@ -1,24 +0,0 @@
-The `trailitems` directive is supplied by the
-[[!iki plugins/contrib/trail desc=trail]] plugin. It adds pages
-to the trail represented by the current page, without producing any output
-on that page.
-
-    \[[!trailitems pages="posts/*" sort="age"]]
-
-    \[[!trailitems pagenames="a b c"]]
-
-Options are similar to [[!iki ikiwiki/directive/inline desc=inline]]:
-
-* `pages`: adds pages that match a [[ikiwiki/PageSpec]] to the trail
-  (cannot be used with `pagenames`)
-
-* `pagenames`: adds a space-separated list of pages to the trail,
-  with the same [[ikiwiki/SubPage/LinkingRules]] as for a [[ikiwiki/WikiLink]]
-  (cannot be used with `pages`)
-
-* `sort`: add the pages matched by `pages` to the trail in this
-  [[ikiwiki/pagespec/sorting]] order (cannot be used with `pagenames`)
-
-* `reverse`: reverse the order of `sort` (cannot be used with `pagenames`)
-
-[[!meta robots="noindex, follow"]]
diff --git a/doc/plugins/contrib/ikiwiki/directive/traillink.mdwn b/doc/plugins/contrib/ikiwiki/directive/traillink.mdwn
deleted file mode 100644
index 0e40e2411..000000000
--- a/doc/plugins/contrib/ikiwiki/directive/traillink.mdwn
+++ /dev/null
@@ -1,16 +0,0 @@
-The `traillink` directive is supplied by the
-[[!iki plugins/contrib/trail desc=trail]]
-plugin. It generates a visible [[ikiwiki/WikiLink]], and also adds the
-linked page to the trail represented by the page containing the directive.
-
-In its simplest form, the first parameter is like the content of a WikiLink:
-
-    \[[!traillink some_other_page]]
-
-The displayed text can also be overridden, either with a `|` symbol or with
-a `text` parameter:
-
-    \[[!traillink Click_here_to_start_the_trail|some_other_page]]
-    \[[!traillink some_other_page text="Click here to start the trail"]]
-
-[[!meta robots="noindex, follow"]]
diff --git a/doc/plugins/contrib/ikiwiki/directive/trailoptions.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailoptions.mdwn
deleted file mode 100644
index e1603f11b..000000000
--- a/doc/plugins/contrib/ikiwiki/directive/trailoptions.mdwn
+++ /dev/null
@@ -1,18 +0,0 @@
-The `trailoptions` directive is supplied by the
-[[!iki plugins/contrib/trail desc=trail]] plugin. It sets options for the
-trail represented by this page.
-
-    \[[!trailoptions sort="meta(title)" circular="no"]]
-
-Options available:
-
-* `sort`: sets a [[ikiwiki/pagespec/sorting]] order for the entire trail,
-  overriding the order in which they were added
-
-* `reverse`: reverses the order of the trail
-
-* `circular`: if set to `yes` or `1`, the trail is made into a loop by
-  making the last page's "next" link point to the first page, and the first
-  page's "previous" link point to the last page
-
-[[!meta robots="noindex, follow"]]
diff --git a/doc/plugins/contrib/trail.mdwn b/doc/plugins/contrib/trail.mdwn
deleted file mode 100644
index bfd4d3d0b..000000000
--- a/doc/plugins/contrib/trail.mdwn
+++ /dev/null
@@ -1,133 +0,0 @@
-[[!tag patch]]
-[[!template id=gitbranch branch=smcv/trail3 author="[[smcv]]"]]
-
-Available from [[smcv]]'s git repository, in the `trail3` branch. This
-plugin aims to solve [[todo/wikitrails]] in a simpler way; it can also be
-used for [[navigation through blog posts|todo/Pagination_next_prev_links]].
-
-If you don't want to use a branch of ikiwiki, manual installation requires
-these files (use the "raw" link in gitweb to download):
-
-* [trail.pm](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/trail3:/IkiWiki/Plugin/trail.pm)
-  in an `IkiWiki/Plugin` subdirectory of your configured `plugindir`
-* [page.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/trail3:/templates/page.tmpl)
-  and
-  [trails.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/trail3:/templates/trails.tmpl)
-  in your configured `templatedir`, or a `templates` subdirectory of your wiki repository
-* the trail-related bits from the end of the
-  [stylesheet](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/trail3:/doc/style.css)
-  (put them in your local.css)
-* the trail-related bits at the end of the
-  [actiontabs](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/trail3:/themes/actiontabs/style.css)
-  or [blueview/goldtype](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/trail3:/themes/blueview/style.css)
-  stylesheets, if you use one of those themes (again, put them in your local.css)
-
-The branch also includes [[todo/test_coverage]] machinery.
-
-Demo:
-
-* [in use on entries in my blog](http://smcv.pseudorandom.co.uk/)
-* [a demo trail based on links](http://demo.hosted.pseudorandom.co.uk/trail/)
-* [a demo hybrid trail/inline](http://demo.hosted.pseudorandom.co.uk/trail2/)
-
-The page `e` is in both demo trails, to demonstrate how a page in more than
-one trail looks.
-
-The `smcv/trail2` branch is an older version of `trail3` which used typed links
-as its data structure, resulting in timing-related limitations (it couldn't
-select pages for the trail by using pagespecs, because pagespecs can't be
-evaluated correctly until the scan stage has finished).
-
-Updated, November 2011:
-
-* reinstated `inline` integration ([[report]] integration would probably be
-  pretty easy too, if this gets merged)
-* switched from typed links back to a custom data structure to avoid
-  chicken/egg problems with ordering
-* create typed links too, as a side-effect, but not when using an inline
-* regression test with nearly full coverage
-* CSS for the default anti-theme and all built-in themes (it looks nicest
-  in the default anti-theme and in actiontabs - the demo uses actiontabs)
-
-Known bugs:
-
-* the blueview and goldtype CSS nearly work, but the alignment is a bit off
-
-----
-
-[[!template id=plugin name=trail author="[[Simon_McVittie|smcv]]"]]
-[[!tag type/chrome]]
-
-This plugin provides the [[ikiwiki/directive/trailoptions]],
-[[ikiwiki/directive/traillink]], [[ikiwiki/directive/trailitem]],
-[[ikiwiki/directive/trailitems]]
-and [[ikiwiki/directive/trailinline]] [[directives|ikiwiki/directive]].
-
-It's sometimes useful to have "trails" of pages in a wiki where each
-page links to the next and/or previous page. For instance, you could use
-this for a guided tour, sequence of chapters, or sequence of blog posts.
-
-In this plugin, a trail is represented by a page, and the pages in the
-trail are indicated by specially marked links within that page, or by
-including groups of pages with a [[ikiwiki/directive]].
-
-If using the default `page.tmpl`, each page automatically displays the
-trails that it's a member of (if any), with links to the trail and to
-the next and previous members. HTML `<link>` tags with the `prev`,
-`next` and `up` relations are also generated.
-
-The [[ikiwiki/directive/trailoptions]] directive sets options for the
-entire trail.
-
-Pages can be included in a trail in various ways:
-
-* The [[ikiwiki/directive/trailinline]] directive sets up an [[inline]],
-  and at the same time adds the matching pages (from `pages` or `pagenames`)
-  to the trail. One use is to navigate through all posts in a blog:
-
-        \[[!trailinline pages="page(./posts/*) and !*/Discussion" archive=yes
-          feedshow=10 quick=yes]]
-
-  This directive only works if the [[!iki plugins/inline desc=inline]]
-  plugin is also enabled.
-
-* The [[ikiwiki/directive/trailitems]] directive has optional `pages` and
-  `pagenames` options which behave the same as in [[inline]], but don't
-  produce any output in the page, so you can have trails that don't list
-  all their pages.
-
-* The [[ikiwiki/directive/traillink]] directive makes a visible link
-  and also adds the linked page to the trail. This will typically be
-  used in a bullet list, but could also be in paragraph text:
-
-        * [[!traillink Introduction]]
-        * [[!traillink "Chapter 1"]]
-        * [[!traillink Chapter_2]]
-        * [[!traillink Appendix_A]]
-
-  or
-
-        To use this software you must \[[!traillink install]] it,
-        \[[!traillink configuration text="configure it"]],
-        and finally \[[!traillink running|run_it]].
-
-  This also counts as a [[ikiwiki/WikiLink]] for things like the `link()`
-  [[ikiwiki/PageSpec]] item.
-
-* The [[ikiwiki/directive/trailitem]] directive adds a page to the trail
-  like `traillink`, but produces an invisible link, rather like `\[[!tag]]`:
-
-        To use this software you must \[[!traillink install]] it,
-        \[[!trailitem installing_from_packages]]
-        \[[!trailitem installing_from_source]]
-        \[[!traillink configuration text="configure it"]],
-        and finally \[[!traillink running|run_it]].
-        \[[!trailitem troubleshooting]]
-
-  Like `\[[!tag]]`, this still counts as a [[ikiwiki/WikiLink]] even though
-  there's no visible link.
-
-You can mix several of these directives in one page. The resulting
-trail will contain all of the pages matched by any of the directives,
-in the same order that the directives appear (unless you use the `sort` or
-`reverse` options on `\[[!trailoptions]]`).
diff --git a/doc/plugins/trail.mdwn b/doc/plugins/trail.mdwn
new file mode 100644
index 000000000..406d40246
--- /dev/null
+++ b/doc/plugins/trail.mdwn
@@ -0,0 +1,76 @@
+[[!template id=plugin name=trail author="[[Simon_McVittie|smcv]]"]]
+[[!tag type/chrome]]
+
+This plugin provides the [[ikiwiki/directive/trailoptions]],
+[[ikiwiki/directive/traillink]], [[ikiwiki/directive/trailitem]],
+[[ikiwiki/directive/trailitems]]
+and [[ikiwiki/directive/trailinline]] [[directives|ikiwiki/directive]].
+
+It's sometimes useful to have "trails" of pages in a wiki where each
+page links to the next and/or previous page. For instance, you could use
+this for a guided tour, sequence of chapters, or sequence of blog posts.
+
+In this plugin, a trail is represented by a page, and the pages in the
+trail are indicated by specially marked links within that page, or by
+including groups of pages with a [[ikiwiki/directive]].
+
+If using the default `page.tmpl`, each page automatically displays the
+trails that it's a member of (if any), with links to the trail and to
+the next and previous members. HTML `<link>` tags with the `prev`,
+`next` and `up` relations are also generated.
+
+The [[ikiwiki/directive/trailoptions]] directive sets options for the
+entire trail.
+
+Pages can be included in a trail in various ways:
+
+* The [[ikiwiki/directive/trailinline]] directive sets up an [[inline]],
+  and at the same time adds the matching pages (from `pages` or `pagenames`)
+  to the trail. One use is to navigate through all posts in a blog:
+
+        \[[!trailinline pages="page(./posts/*) and !*/Discussion" archive=yes
+          feedshow=10 quick=yes]]
+
+  This directive only works if the [[!iki plugins/inline desc=inline]]
+  plugin is also enabled.
+
+* The [[ikiwiki/directive/trailitems]] directive has optional `pages` and
+  `pagenames` options which behave the same as in [[inline]], but don't
+  produce any output in the page, so you can have trails that don't list
+  all their pages.
+
+* The [[ikiwiki/directive/traillink]] directive makes a visible link
+  and also adds the linked page to the trail. This will typically be
+  used in a bullet list, but could also be in paragraph text:
+
+        * [[!traillink Introduction]]
+        * [[!traillink "Chapter 1"]]
+        * [[!traillink Chapter_2]]
+        * [[!traillink Appendix_A]]
+
+  or
+
+        To use this software you must \[[!traillink install]] it,
+        \[[!traillink configuration text="configure it"]],
+        and finally \[[!traillink running|run_it]].
+
+  This also counts as a [[ikiwiki/WikiLink]] for things like the `link()`
+  [[ikiwiki/PageSpec]] item.
+
+* The [[ikiwiki/directive/trailitem]] directive adds a page to the trail
+  like `traillink`, but produces an invisible link, rather like `\[[!tag]]`:
+
+        To use this software you must \[[!traillink install]] it,
+        \[[!trailitem installing_from_packages]]
+        \[[!trailitem installing_from_source]]
+        \[[!traillink configuration text="configure it"]],
+        and finally \[[!traillink running|run_it]].
+        \[[!trailitem troubleshooting]]
+
+  Like `\[[!tag]]`, this still counts as a [[ikiwiki/WikiLink]] even though
+  there's no visible link.
+
+You can mix several of these directives in one page. The resulting
+trail will contain all of the pages matched by any of the directives,
+in the same order that the directives appear (unless you use the `sort` or
+`reverse` options on `\[[!trailoptions]]`).
-- 
cgit v1.2.3


From 63bb8b42f76e350cdf7a1256ad0fe7ad63199f63 Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@debian.org>
Date: Sun, 18 Mar 2012 17:11:05 +0000
Subject: Replace [[!trailinline]] directive with [[!inline trail=yes]]

---
 IkiWiki/Plugin/inline.pm               | 19 ++++++++++++++++++-
 IkiWiki/Plugin/trail.pm                | 26 +-------------------------
 doc/examples/blog/posts.mdwn           |  2 +-
 doc/ikiwiki/directive/inline.mdwn      |  5 +++++
 doc/ikiwiki/directive/trailinline.mdwn | 11 -----------
 doc/plugins/trail.mdwn                 | 18 +++++++++---------
 t/trail.t                              |  6 +++---
 7 files changed, 37 insertions(+), 50 deletions(-)
 delete mode 100644 doc/ikiwiki/directive/trailinline.mdwn

diff --git a/IkiWiki/Plugin/inline.pm b/IkiWiki/Plugin/inline.pm
index 159cc5def..3dc410c27 100644
--- a/IkiWiki/Plugin/inline.pm
+++ b/IkiWiki/Plugin/inline.pm
@@ -19,7 +19,7 @@ sub import {
 	hook(type => "checkconfig", id => "inline", call => \&checkconfig);
 	hook(type => "sessioncgi", id => "inline", call => \&sessioncgi);
 	hook(type => "preprocess", id => "inline", 
-		call => \&IkiWiki::preprocess_inline);
+		call => \&IkiWiki::preprocess_inline, scan => 1);
 	hook(type => "pagetemplate", id => "inline",
 		call => \&IkiWiki::pagetemplate_inline);
 	hook(type => "format", id => "inline", call => \&format, first => 1);
@@ -155,6 +155,23 @@ sub preprocess_inline (@) {
 	if (! exists $params{pages} && ! exists $params{pagenames}) {
 		error gettext("missing pages parameter");
 	}
+
+	if (! defined wantarray) {
+		# Running in scan mode: only do the essentials
+
+		if (yesno($params{trail}) && IkiWiki::Plugin::trail->can("preprocess_trailitems")) {
+			# default to sorting age, the same as inline itself,
+			# but let the params override that
+			IkiWiki::Plugin::trail::preprocess_trailitems(sort => 'age', %params);
+		}
+
+		return;
+	}
+
+	if (yesno($params{trail}) && IkiWiki::Plugin::trail->can("preprocess_trailitems")) {
+		scalar IkiWiki::Plugin::trail::preprocess_trailitems(sort => 'age', %params);
+	}
+
 	my $raw=yesno($params{raw});
 	my $archive=yesno($params{archive});
 	my $rss=(($config{rss} || $config{allowrss}) && exists $params{rss}) ? yesno($params{rss}) : $config{rss};
diff --git a/IkiWiki/Plugin/trail.pm b/IkiWiki/Plugin/trail.pm
index 5ee152155..4f309ea2e 100644
--- a/IkiWiki/Plugin/trail.pm
+++ b/IkiWiki/Plugin/trail.pm
@@ -1,6 +1,6 @@
 #!/usr/bin/perl
 # Copyright © 2008-2011 Joey Hess
-# Copyright © 2009-2011 Simon McVittie <http://smcv.pseudorandom.co.uk/>
+# Copyright © 2009-2012 Simon McVittie <http://smcv.pseudorandom.co.uk/>
 # Licensed under the GNU GPL, version 2, or any later version published by the
 # Free Software Foundation
 package IkiWiki::Plugin::trail;
@@ -13,7 +13,6 @@ sub import {
 	hook(type => "getsetup", id => "trail", call => \&getsetup);
 	hook(type => "needsbuild", id => "trail", call => \&needsbuild);
 	hook(type => "preprocess", id => "trailoptions", call => \&preprocess_trailoptions, scan => 1);
-	hook(type => "preprocess", id => "trailinline", call => \&preprocess_trailinline, scan => 1);
 	hook(type => "preprocess", id => "trailitem", call => \&preprocess_trailitem, scan => 1);
 	hook(type => "preprocess", id => "trailitems", call => \&preprocess_trailitems, scan => 1);
 	hook(type => "preprocess", id => "traillink", call => \&preprocess_traillink, scan => 1);
@@ -123,29 +122,6 @@ sub preprocess_trailoptions (@) {
 	return "";
 }
 
-sub preprocess_trailinline (@) {
-	my %params = @_;
-
-	if (! exists $params{sort}) {
-		# sort in the same order as [[plugins/inline]]'s default
-		$params{sort} = 'age';
-	}
-
-	if (defined wantarray) {
-		scalar preprocess_trailitems(%params);
-
-		if (IkiWiki->can("preprocess_inline")) {
-			return IkiWiki::preprocess_inline(@_);
-		}
-		else {
-			error("trailinline directive requires the inline plugin");
-		}
-	}
-	else {
-		preprocess_trailitems(%params);
-	}
-}
-
 sub preprocess_trailitem (@) {
 	my $link = shift;
 	shift;
diff --git a/doc/examples/blog/posts.mdwn b/doc/examples/blog/posts.mdwn
index 6e9a3f001..2bd0f1d6f 100644
--- a/doc/examples/blog/posts.mdwn
+++ b/doc/examples/blog/posts.mdwn
@@ -1,3 +1,3 @@
 Here is a full list of posts to the [[blog|index]].
 
-[[!trailinline pages="page(./posts/*) and !*/Discussion" archive=yes feedshow=10 quick=yes]]
+[[!inline pages="page(./posts/*) and !*/Discussion" archive=yes feedshow=10 quick=yes trail=yes]]
diff --git a/doc/ikiwiki/directive/inline.mdwn b/doc/ikiwiki/directive/inline.mdwn
index 22c18d9a1..4b11e5997 100644
--- a/doc/ikiwiki/directive/inline.mdwn
+++ b/doc/ikiwiki/directive/inline.mdwn
@@ -117,5 +117,10 @@ Here are some less often needed parameters:
   [[SubPage/LinkingRules]] as in a [[ikiwiki/WikiLink]]), and they are inlined
   in exactly the order given: the `sort` and `pages` parameters cannot be used
   in conjunction with this one.
+* `trail` - If the [[!iki plugins/trail desc=trail]] plugin is enabled, turn
+  the inlined pages into a trail with next/previous links, by passing the same
+  options to [[ikiwiki/directive/trailitems]]. The `skip` and `show` options
+  are ignored by the trail, so the next/previous links traverse through
+  all matching pages.
 
 [[!meta robots="noindex, follow"]]
diff --git a/doc/ikiwiki/directive/trailinline.mdwn b/doc/ikiwiki/directive/trailinline.mdwn
deleted file mode 100644
index e32fb34d0..000000000
--- a/doc/ikiwiki/directive/trailinline.mdwn
+++ /dev/null
@@ -1,11 +0,0 @@
-The `trailinline` directive is provided by the
-[[!iki plugins/trail desc=trail]]
-plugin. It is equivalent to combining [[ikiwiki/directive/trailitems]] and
-[[ikiwiki/directive/inline]] directives with the same options.
-
-A typical use is to navigate through all posts in a blog:
-
-      \[[!trailinline pages="page(./posts/*) and !*/Discussion" archive=yes
-        feedshow=10 quick=yes]]
-
-[[!meta robots="noindex, follow"]]
diff --git a/doc/plugins/trail.mdwn b/doc/plugins/trail.mdwn
index 406d40246..14b97e35a 100644
--- a/doc/plugins/trail.mdwn
+++ b/doc/plugins/trail.mdwn
@@ -3,8 +3,7 @@
 
 This plugin provides the [[ikiwiki/directive/trailoptions]],
 [[ikiwiki/directive/traillink]], [[ikiwiki/directive/trailitem]],
-[[ikiwiki/directive/trailitems]]
-and [[ikiwiki/directive/trailinline]] [[directives|ikiwiki/directive]].
+and [[ikiwiki/directive/trailitems]] [[directives|ikiwiki/directive]].
 
 It's sometimes useful to have "trails" of pages in a wiki where each
 page links to the next and/or previous page. For instance, you could use
@@ -24,15 +23,16 @@ entire trail.
 
 Pages can be included in a trail in various ways:
 
-* The [[ikiwiki/directive/trailinline]] directive sets up an [[inline]],
-  and at the same time adds the matching pages (from `pages` or `pagenames`)
-  to the trail. One use is to navigate through all posts in a blog:
+* The [[ikiwiki/directive/inline]] directive with `trail="yes"` sets up an
+  [[inline]], and at the same time adds the matching pages (from `pages` or
+  `pagenames`) to the trail. One use is to navigate through all posts in
+  a blog:
 
-        \[[!trailinline pages="page(./posts/*) and !*/Discussion" archive=yes
-          feedshow=10 quick=yes]]
+        \[[!inline pages="page(./posts/*) and !*/Discussion" archive=yes
+          feedshow=10 quick=yes trail=yes]]
 
-  This directive only works if the [[!iki plugins/inline desc=inline]]
-  plugin is also enabled.
+  This only works if the trail and [[!iki plugins/inline desc=inline]]
+  plugins are both enabled.
 
 * The [[ikiwiki/directive/trailitems]] directive has optional `pages` and
   `pagenames` options which behave the same as in [[inline]], but don't
diff --git a/t/trail.t b/t/trail.t
index 0cf50ddc1..17fe54310 100755
--- a/t/trail.t
+++ b/t/trail.t
@@ -60,13 +60,13 @@ ok(utime(333333333, 333333333, "t/tmp/in/sorting/new.mdwn"));
 ok(utime(222222222, 222222222, "t/tmp/in/sorting/old.mdwn"));
 ok(utime(111111111, 111111111, "t/tmp/in/sorting/ancient.mdwn"));
 writefile("sorting/linked2.mdwn", "t/tmp/in", "linked2");
-# This initially uses the default sort order: age for trailinline, and path
-# for trail. We change it later.
+# This initially uses the default sort order: age for the inline, and path
+# for trailitems. We change it later.
 writefile("sorting.mdwn", "t/tmp/in",
 	'[[!traillink linked]] ' .
 	'[[!trailitems pages="sorting/z/a or sorting/a/b or sorting/a/c"]] ' .
 	'[[!trailitems pagenames="beginning middle end"]] ' .
-	'[[!trailinline pages="sorting/old or sorting/ancient or sorting/new"]] ' .
+	'[[!inline pages="sorting/old or sorting/ancient or sorting/new" trail="yes"]] ' .
 	'[[!traillink linked2]]');
 
 writefile("meme.mdwn", "t/tmp/in", <<EOF
-- 
cgit v1.2.3


From 24168b993e65994d2996d02bfaa36fb80bb65ca7 Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@debian.org>
Date: Sun, 18 Mar 2012 17:34:39 +0000
Subject: Add a build_affected hook so trail doesn't have to inject

In principle, building any pages affected by links, backlinks etc.
could work the same way.
---
 IkiWiki/Plugin/trail.pm | 18 +++++-------------
 IkiWiki/Render.pm       |  8 ++++++++
 doc/plugins/write.mdwn  | 16 ++++++++++++++++
 3 files changed, 29 insertions(+), 13 deletions(-)

diff --git a/IkiWiki/Plugin/trail.pm b/IkiWiki/Plugin/trail.pm
index 4f309ea2e..29830175e 100644
--- a/IkiWiki/Plugin/trail.pm
+++ b/IkiWiki/Plugin/trail.pm
@@ -17,6 +17,7 @@ sub import {
 	hook(type => "preprocess", id => "trailitems", call => \&preprocess_trailitems, scan => 1);
 	hook(type => "preprocess", id => "traillink", call => \&preprocess_traillink, scan => 1);
 	hook(type => "pagetemplate", id => "trail", call => \&pagetemplate);
+	hook(type => "build_affected", id => "trail", call => \&build_affected);
 }
 
 =head1 Page state
@@ -275,14 +276,9 @@ sub trails_differ {
 
 my $done_prerender = 0;
 
-my %origsubs;
-
 sub prerender {
 	return if $done_prerender;
 
-	$origsubs{render_backlinks} = \&IkiWiki::render_backlinks;
-	inject(name => "IkiWiki::render_backlinks", call => \&render_backlinks);
-
 	%trail_to_members = ();
 	%member_to_trails = ();
 
@@ -368,18 +364,14 @@ sub prerender {
 	$done_prerender = 1;
 }
 
-# This is called at about the right time that we can hijack it to render
-# extra pages.
-sub render_backlinks ($) {
-	my $blc = shift;
+sub build_affected {
+	my %affected;
 
 	foreach my $member (keys %rebuild_trail_members) {
-		next unless exists $pagesources{$member};
-
-		IkiWiki::render($pagesources{$member}, sprintf(gettext("building %s, its previous or next page has changed"), $member));
+		$affected{$member} = sprintf(gettext("building %s, its previous or next page has changed"), $member);
 	}
 
-	$origsubs{render_backlinks}($blc);
+	return %affected;
 }
 
 sub title_of ($) {
diff --git a/IkiWiki/Render.pm b/IkiWiki/Render.pm
index 05132a8a8..adb39a983 100644
--- a/IkiWiki/Render.pm
+++ b/IkiWiki/Render.pm
@@ -800,6 +800,14 @@ sub refresh () {
 		derender_internal($file);
 	}
 
+	run_hooks(build_affected => sub {
+		my %affected = shift->();
+		while (my ($page, $message) = each %affected) {
+			next unless exists $pagesources{$page};
+			render($pagesources{$page}, $message);
+		}
+	});
+
 	my ($backlinkchanged, $linkchangers)=calculate_changed_links($changed,
 		$del, $oldlink_targets);
 
diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index dcab041dc..d62ab6e63 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -356,6 +356,22 @@ when the page is being previewed.)
 The function is passed named parameters: "page" and "content", and 
 should return the formatted content.
 
+### build_affected
+
+	hook(type => "build_affected", id => "foo", call => \&build_affected);
+
+This hook is called after the directly changed pages have been built,
+and can cause extra pages to be built. If links and backlinks were provided
+by a plugin, this would be where that plugin would rebuild pages whose
+backlinks have changed, for instance. The [[trail]] plugin uses this hook
+to rebuild pages whose next or previous page has changed.
+
+The function should currently ignore its parameters. It returns a list with
+an even number of items (a hash in list context), where the first item of
+each pair is a page name to be rebuilt (if it was not already rebuilt), and
+the second is a log message resembling
+`building plugins/write because the phase of the moon has changed`.
+
 ### delete
 
 	hook(type => "delete", id => "foo", call => \&delete);
-- 
cgit v1.2.3