X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/9d51be7942f3aecc0d304c578465ef7397cbd035..bf056a7ef4d76f30eb78a7adb4cea576d5969eea:/doc/plugins/contrib/trail.mdwn diff --git a/doc/plugins/contrib/trail.mdwn b/doc/plugins/contrib/trail.mdwn index 6b96585b8..bfd4d3d0b 100644 --- a/doc/plugins/contrib/trail.mdwn +++ b/doc/plugins/contrib/trail.mdwn @@ -1,21 +1,39 @@ [[!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 -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: -* [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). @@ -24,14 +42,10 @@ 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) @@ -44,8 +58,9 @@ Known bugs: [[!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/trailitems]] 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 `` 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]], @@ -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. -* 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. @@ -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. -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, -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]]`).