Document trail plugin v3

7 files changed, 167 insertions, 60 deletions

diff --git a/doc/plugins/contrib/album.mdwn b/doc/plugins/contrib/album.mdwn
index 8dfbbf716..dde533e76 100644
--- a/doc/plugins/contrib/album.mdwn
+++ b/doc/plugins/contrib/album.mdwn
@@ -6,6 +6,9 @@ Available from [[smcv]]'s git repository, in the `album2` branch.
 Older (pre-rebase) versions in `album`, `album-live` (the latter
 was used on an actual website and didn't explode too much).
 
+[The version currently available hasn't been modified to work with the
+November 2011 version of [[trail]]. -[[smcv]]]
+
 This plugin formats a collection of images into a photo album,
 in the same way as many websites: good examples include the
 PHP application [Gallery](http://gallery.menalto.com/), Flickr,
diff --git a/doc/plugins/contrib/ikiwiki/directive/trail.mdwn b/doc/plugins/contrib/ikiwiki/directive/trail.mdwn
new file mode 100644
index 000000000..cf8c370a7
--- /dev/null
+++ b/doc/plugins/contrib/ikiwiki/directive/trail.mdwn
@@ -0,0 +1,24 @@
+The `trail` directive is supplied by the
+[[!iki plugins/contrib/trail desc=trail]] plugin. It sets options for the
+trail represented by this page, and can also add pages to the trail. Example usage:
+
+    \[[!trail sort="meta(title)" circular="no"]]
+
+The available options are:
+
+* `pages`: adds pages that match a [[ikiwiki/PageSpec]] to the trail
+
+* `pagenames`: adds a space-separated list of pages to the trail,
+  with the same [[SubPage/LinkingRules]] as for a [[ikiwiki/WikiLink]]
+
+* `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
+
+* `reverse`: reverses the [[ikiwiki/pagespec/sorting]] order
+
+* `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
new file mode 100644
index 000000000..4fae7ac8a
--- /dev/null
+++ b/doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn
@@ -0,0 +1,11 @@
+The `trailinline` directive is provided by the
+[[!iki plugins/contrib/trail desc=trail]]
+plugin. It is equivalent to combining [[ikiwiki/directive/trail]] 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
new file mode 100644
index 000000000..73b1985a5
--- /dev/null
+++ b/doc/plugins/contrib/ikiwiki/directive/trailitem.mdwn
@@ -0,0 +1,9 @@
+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/traillink.mdwn b/doc/plugins/contrib/ikiwiki/directive/traillink.mdwn
new file mode 100644
index 000000000..0e40e2411
--- /dev/null
+++ b/doc/plugins/contrib/ikiwiki/directive/traillink.mdwn
@@ -0,0 +1,16 @@
+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/trail.mdwn b/doc/plugins/contrib/trail.mdwn
index def91d85a..6b96585b8 100644
--- a/doc/plugins/contrib/trail.mdwn
+++ b/doc/plugins/contrib/trail.mdwn
@@ -1,95 +1,117 @@
-[[!tag type/chrome patch]]
+[[!tag patch]]
 [[!template id=gitbranch branch=smcv/trail author="[[smcv]]"]]
 
 Available from [[smcv]]'s git repository, in the `trail` branch. This
-plugin aims to solve [[todo/wikitrails]] in a simpler way.
+plugin aims to solve [[todo/wikitrails]] in a simpler way; it can also be
+used for [[navigation through blog posts|Pagination_next_prev_links]].
 
-Updated, June 2011:
+The branch also includes machinery to run most of the IkiWiki regression
+tests under [[!cpan Devel::Cover]].
 
-* removed `inline` integration for now
+Demo:
 
-* added `<link>` tags
+* [a trail based on links](http://demo.hosted.pseudorandom.co.uk/trail/)
+* [a hybrid trail/inline](http://demo.hosted.pseudorandom.co.uk/trail2/)
 
-* switched from a custom data structure to using typed links
+The page `e` in the demo is in both trails, to demonstrate how that looks.
 
-----
+The `smcv/trail2` branch is an older version of `trail` 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).
 
-[[!template id=plugin name=trail author="[[Simon_McVittie|smcv]]"]]
+Updated, November 2011:
 
-It's sometimes useful to have "trails" of pages in a wiki, as a guided
-tour, sequence of chapters etc. 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.
+* reinstated `inline` integration ([[report]] integration would probably be
+  pretty easy too, if this gets merged)
 
-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.
+* switched from typed links back to a custom data structure to avoid
+  chicken/egg problems with ordering
 
-The `traillink` [[ikiwiki/directive]] is used to record which pages
-are in a trail, and simultaneously link to them. Alternatively, the
-[[ikiwiki/directive/trailitem]] directive can be used to make an
-invisible `traillink`.
+* create typed links too, as a side-effect, but not when using an inline
 
-## Directives
+* regression test with nearly full coverage
 
-(These will go to the appropriate pages in [[ikiwiki/directive]] if this
-plugin is included in ikiwiki.)
+* 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)
 
-### trailitem
+Known bugs:
 
-The `trailitem` directive is supplied by the [[!iki plugins/contrib/trail desc=trail]]
-plugin. It is used like this:
+* the blueview and goldtype CSS nearly work, but the alignment is a bit off
 
-    \[[!trailitem some_other_page]]
+----
 
-to add `some_other_page` to the trail represented by this page, without
-generating a visible hyperlink.
+[[!template id=plugin name=trail author="[[Simon_McVittie|smcv]]"]]
+[[!tag type/chrome]]
 
-### traillink
+This plugin provides the [[ikiwiki/directive/trail]],
+[[ikiwiki/directive/traillink]], [[ikiwiki/directive/trailitem]],
+and [[ikiwiki/directive/trailinline]] [[directives|ikiwiki/directive]].
 
-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.
+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 its simplest form, the first parameter is like the content of a WikiLink:
+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]].
 
-    \[[!traillink some_other_page]]
+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 displayed text can also be overridden, either with a `|` symbol or with
-a `text` parameter:
+Pages can be included in a trail in various ways:
 
-    \[[!traillink Click_here_to_start_the_trail|some_other_page]]
-    \[[!traillink some_other_page text="Click here to start the trail"]]
+* 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:
 
-### trailoptions
+        \[[!trailinline pages="page(./posts/*) and !*/Discussion" archive=yes
+          feedshow=10 quick=yes]]
 
-The `trailoptions` directive is supplied by the [[!iki plugins/contrib/trail desc=trail]]
-plugin. It sets options for the trail represented by this page. Example usage:
+  This directive only works if the [[!iki plugins/inline desc=inline]]
+  plugin is also enabled.
 
-    \[[!trailoptions sort="meta(title)" circular="no"]]
+* The [[ikiwiki/directive/trail]] 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 available options are:
+* 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:
 
-* `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
+        * [[!traillink Introduction]]
+        * [[!traillink "Chapter 1"]]
+        * [[!traillink Chapter_2]]
+        * [[!traillink Appendix_A]]
 
-* `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
+  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]]`:
 
-## Future directions
+        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]]
 
-The current version of this plugin doesn't implement inline-based or
-otherwise [[ikiwiki/PageSpec]]-based trails. This is difficult because
-there's a circular dependency:
+  Like `\[[!tag]]`, this still counts as a [[ikiwiki/WikiLink]] even though
+  there's no visible link.
 
-* adding typed links should happen *before* scanning has finished, to
-  guarantee that they're available before the first page is rendered
+You can mix several of these directives in one page, and the resulting
+trail will contain all of the pages matched by any of the directives,
+in the same order as the directives (unless you use the `sort` option
+on `\[[!trail]]` or `\[[!trailinline]]`, which takes precedence).
 
-* evaluating pagespecs should only happen *after* scanning has finished,
-  to guarantee that everything you might want to base a pagespec on
-  (`meta`, etc.) has been gathered by scanning
+The [[ikiwiki/directive/trail]] directive can also be used to set options.
diff --git a/doc/todo/Pagination_next_prev_links.mdwn b/doc/todo/Pagination_next_prev_links.mdwn
index f1c12d33f..e2b56a0cc 100644
--- a/doc/todo/Pagination_next_prev_links.mdwn
+++ b/doc/todo/Pagination_next_prev_links.mdwn
@@ -27,7 +27,29 @@ Thank you
 > reduces the generic usefulness of typed links, though - in particular
 > you can no longer use "is part of trail A" in a PageSpec. --[[smcv]]
 
+>> Version 3 of [[plugins/contrib/trail]] now does this. For `traillink`
+>> and `trailitem` it additionally adds a typed link, which it does not
+>> itself consume; for `trailinline` and `trail` it doesn't. --[[smcv]]
+
 >>> Indeed, I know the problem; I ran into the same kind of thing with my [[plugins/contrib/report]] plugin and its `trail` concept.
 >>> I simply had to declare that one couldn't use "trail" and "maketrail" options within the same report. That way, "maketrail" will add links in the "scan" pass, and "trail" will test for links in the "build" pass.  That usually works. --[[KathrynAndersen]]
 
+>>>> I'm not sure that even that is *quite* right: if your `trail` takes
+>>>> pagespecs as arguments, then it's potentially evaluating those pagespecs
+>>>> before all pages have been scanned, which could mean it lists pages
+>>>> which matched the spec before a recent change, or doesn't list pages
+>>>> which didn't previously match the spec but do now.
+>>>>
+>>>> In version 3 of [[plugins/contrib/trail]] I ended up storing
+>>>> uninterpreted pagespecs and links at scan time, and evaluating them the
+>>>> first time a page is built. I *think* that's sufficiently lazy to give
+>>>> the right answer... --[[smcv]]
+
 >> Do you have an example? --[[hendry]]
+
+>>> Now linked on the plugin's page - it doesn't pretend to be a blog, but
+>>> [the second demo](http://demo.hosted.pseudorandom.co.uk/trail2/)
+>>> is a `trailinline`, so you could do that with blog posts just as well.
+>>> Making [[plugins/contrib/album]] require `trail` v3, and trying it out
+>>> on my blog, are next on the list.
+>>> --[[smcv]]