split trail directive into trailitems and trailoptions

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

diff --git a/doc/plugins/contrib/trail.mdwn b/doc/plugins/contrib/trail.mdwn
index 337e5d427d34ef932a15cebc9652ff6a8aeb60bd..59daa58e7bd41922bd8c47853876f39d587905ff 100644 (file)
--- a/doc/plugins/contrib/trail.mdwn
+++ b/doc/plugins/contrib/trail.mdwn
@@ -1,66 +1,134 @@
-[[!tag type/chrome 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.
-
-Joey: what do you think of this plugin? If you like the general approach
-and are likely to include it in ikiwiki, I'll try to modify
-[[plugins/contrib/album]] to be based on it, rather than partially
-reinventing it.
-
-Bugs:
-
-* \[[!inline pages="..." trail=yes]] currently tries to work out
-  what pages are in the trail, and their order, at scan time. That
-  won't work, because matching a pagespec at scan time is
-  unreliable - pages we want might not have been scanned yet! I
-  haven't worked out a solution for this. I think
-  \[[!inline pagenames="..." trail=yes]] would be safe, though.
+[[!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
+* a `trailinline` with no `sort` option is sorted in arbitrary order

 
 ----
 
 [[!template id=plugin name=trail author="[[Simon_McVittie|smcv]]"]]
 
 ----
 
 [[!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.

 
 

-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.
+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
 
 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.
+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 `traillink` [[ikiwiki/directive]] is used to record which pages
-are in a trail, and simultaneously link to them. Alternatively, the
-[[ikiwiki/directive/inline]] directive can be used with `trail=yes`
-to record the inlined pages as part of the trail, in the order in
-which they are inlined.
+* 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.

 
 

-## Directives
+* 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:

 
 

-(These will go to the appropriate pages in [[ikiwiki/directive]] if this
-plugin is included in ikiwiki.)
+        * [[!traillink Introduction]]
+        * [[!traillink "Chapter 1"]]
+        * [[!traillink Chapter_2]]
+        * [[!traillink Appendix_A]]

 
 

-### traillink
+  or

 
 

-The `traillink` directive is supplied by the [[!iki plugins/contrib/trail desc=trail]]
-plugin. This directive appears on the page representing a trail. It acts
-as a visible [[ikiwiki/WikiLink]], but also records the linked page as
-a member of the trail.
+        To use this software you must \[[!traillink install]] it,
+        \[[!traillink configuration text="configure it"]],
+        and finally \[[!traillink running|run_it]].

 
 

-Various syntaxes can be used:
+  This also counts as a [[ikiwiki/WikiLink]] for things like the `link()`
+  [[ikiwiki/PageSpec]] item.

 
 

-    \[[!traillink Badgers]]
-    \[[!traillink How_to_find_mushrooms_using_badgers|badgers]]
-    \[[!traillink badgers text="How to find mushrooms using badgers"]]
+* The [[ikiwiki/directive/trailitem]] directive adds a page to the trail
+  like `traillink`, but produces an invisible link, rather like `\[[!tag]]`:

 
 

-### trailoptions
+        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 `trailoptions` directive is supplied by the [[!iki plugins/contrib/trail desc=trail]]
-plugin. This directive appears on the page representing a trail, and
-produces no output.
+  Like `\[[!tag]]`, this still counts as a [[ikiwiki/WikiLink]] even though
+  there's no visible link.

 
 

-Currently, the only option supported is `[[!trailoptions circular=yes]]`,
-which adds links between the first and last pages, turning the trail into
-a circle.
+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]]`).