From 9d51be7942f3aecc0d304c578465ef7397cbd035 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Wed, 9 Nov 2011 23:43:00 +0000 Subject: Document trail plugin v3 --- doc/plugins/contrib/album.mdwn | 3 + doc/plugins/contrib/ikiwiki/directive/trail.mdwn | 24 ++++ .../contrib/ikiwiki/directive/trailinline.mdwn | 11 ++ .../contrib/ikiwiki/directive/trailitem.mdwn | 9 ++ .../contrib/ikiwiki/directive/traillink.mdwn | 16 +++ doc/plugins/contrib/trail.mdwn | 142 ++++++++++++--------- 6 files changed, 145 insertions(+), 60 deletions(-) create mode 100644 doc/plugins/contrib/ikiwiki/directive/trail.mdwn create mode 100644 doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn create mode 100644 doc/plugins/contrib/ikiwiki/directive/trailitem.mdwn create mode 100644 doc/plugins/contrib/ikiwiki/directive/traillink.mdwn (limited to 'doc/plugins') 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 `` 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 `` 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 `` 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. -- cgit v1.2.3