Notes.

[git.ikiwiki.info.git] / doc / plugins / contrib / trail.mdwn

diff --git a/doc/plugins/contrib/trail.mdwn b/doc/plugins/contrib/trail.mdwn
index 6b96585b8bb3c01122b96ca1ec8ad7245d119d67..bfd4d3d0b79df7b60e316c67ce66f9e8ecf4aa64 100644 (file)
--- a/doc/plugins/contrib/trail.mdwn
+++ b/doc/plugins/contrib/trail.mdwn
@@ -1,21 +1,39 @@
 [[!tag patch]]
 [[!tag patch]]

-[[!template id=gitbranch branch=smcv/trail author="[[smcv]]"]]
+[[!template id=gitbranch branch=smcv/trail3 author="[[smcv]]"]]

 
 

-Available from [[smcv]]'s git repository, in the `trail` branch. This
+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
 plugin aims to solve [[todo/wikitrails]] in a simpler way; it can also be

-used for [[navigation through blog posts|Pagination_next_prev_links]].
-
-The branch also includes machinery to run most of the IkiWiki regression
-tests under [[!cpan Devel::Cover]].
+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:
 
 
 Demo:
 

-* [a trail based on links](http://demo.hosted.pseudorandom.co.uk/trail/)
-* [a hybrid trail/inline](http://demo.hosted.pseudorandom.co.uk/trail2/)
+* [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` in the demo is in both trails, to demonstrate how that looks.
+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 `trail` which used typed links
+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).
 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).


@@ -24,14 +42,10 @@ Updated, November 2011:
 
 * reinstated `inline` integration ([[report]] integration would probably be
   pretty easy too, if this gets merged)
 
 * 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
 * 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
 * create typed links too, as a side-effect, but not when using an inline

-

 * regression test with nearly full coverage
 * 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)
 
 * 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)
 


@@ -44,8 +58,9 @@ Known bugs:
 [[!template id=plugin name=trail author="[[Simon_McVittie|smcv]]"]]
 [[!tag type/chrome]]
 
 [[!template id=plugin name=trail author="[[Simon_McVittie|smcv]]"]]
 [[!tag type/chrome]]
 

-This plugin provides the [[ikiwiki/directive/trail]],
+This plugin provides the [[ikiwiki/directive/trailoptions]],

 [[ikiwiki/directive/traillink]], [[ikiwiki/directive/trailitem]],
 [[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
 and [[ikiwiki/directive/trailinline]] [[directives|ikiwiki/directive]].
 
 It's sometimes useful to have "trails" of pages in a wiki where each


@@ -61,6 +76,9 @@ 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 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]],
 Pages can be included in a trail in various ways:
 
 * The [[ikiwiki/directive/trailinline]] directive sets up an [[inline]],


@@ -73,7 +91,7 @@ Pages can be included in a trail in various ways:
   This directive only works if the [[!iki plugins/inline desc=inline]]
   plugin is also enabled.
 
   This directive only works if the [[!iki plugins/inline desc=inline]]
   plugin is also enabled.
 

-* The [[ikiwiki/directive/trail]] directive has optional `pages` and
+* 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.
   `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.


@@ -109,9 +127,7 @@ Pages can be included in a trail in various ways:
   Like `\[[!tag]]`, this still counts as a [[ikiwiki/WikiLink]] even though
   there's no visible link.
 
   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, and the resulting
+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,
 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).
-
-The [[ikiwiki/directive/trail]] directive can also be used to set options.
+in the same order that the directives appear (unless you use the `sort` or
+`reverse` options on `\[[!trailoptions]]`).