Document trail plugin v3

6 files changed, 145 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.