split trail directive into trailitems and trailoptions

diff --git a/doc/plugins/contrib/ikiwiki/directive/trail.mdwn b/doc/plugins/contrib/ikiwiki/directive/trail.mdwn
deleted file mode 100644 (file)
index cf8c370..0000000
--- a/doc/plugins/contrib/ikiwiki/directive/trail.mdwn
+++ /dev/null
@@ -1,24 +0,0 @@
-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
index 4fae7ac8a2f6bf44e4af3f6700ba39ca9b2f4444..91d8a4edf9e9186f920abeacc37ecd97efd80d0e 100644 (file)
--- a/doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn
+++ b/doc/plugins/contrib/ikiwiki/directive/trailinline.mdwn
@@ -1,6 +1,6 @@
 The `trailinline` directive is provided by the
 [[!iki plugins/contrib/trail desc=trail]]
 The `trailinline` directive is provided by the
 [[!iki plugins/contrib/trail desc=trail]]

-plugin. It is equivalent to combining [[ikiwiki/directive/trail]] and
+plugin. It is equivalent to combining [[ikiwiki/directive/trailitems]] and

 [[ikiwiki/directive/inline]] directives with the same options.
 
 A typical use is to navigate through all posts in a blog:
 [[ikiwiki/directive/inline]] directives with the same options.
 
 A typical use is to navigate through all posts in a blog:

diff --git a/doc/plugins/contrib/ikiwiki/directive/trailitems.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailitems.mdwn
new file mode 100644 (file)
index 0000000..4106ed3
--- /dev/null
+++ b/doc/plugins/contrib/ikiwiki/directive/trailitems.mdwn
@@ -0,0 +1,24 @@
+The `trailitems` directive is supplied by the
+[[!iki plugins/contrib/trail desc=trail]] plugin. It adds pages
+to the trail represented by the current page, without producing any output
+on that page.
+
+    \[[!trailitems pages="posts/*" sort="age"]]
+
+    \[[!trailitems pagenames="a b c"]]
+
+Options are similar to [[!iki ikiwiki/directive/inline desc=inline]]:
+
+* `pages`: adds pages that match a [[ikiwiki/PageSpec]] to the trail
+  (cannot be used with `pagenames`)
+
+* `pagenames`: adds a space-separated list of pages to the trail,
+  with the same [[ikiwiki/SubPage/LinkingRules]] as for a [[ikiwiki/WikiLink]]
+  (cannot be used with `pages`)
+
+* `sort`: add the pages matched by `pages` to the trail in this
+  [[ikiwiki/pagespec/sorting]] order (cannot be used with `pagenames`)
+
+* `reverse`: reverse the order of `sort` (cannot be used with `pagenames`)
+
+[[!meta robots="noindex, follow"]]

diff --git a/doc/plugins/contrib/ikiwiki/directive/trailoptions.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailoptions.mdwn
new file mode 100644 (file)
index 0000000..e1603f1
--- /dev/null
+++ b/doc/plugins/contrib/ikiwiki/directive/trailoptions.mdwn
@@ -0,0 +1,18 @@
+The `trailoptions` directive is supplied by the
+[[!iki plugins/contrib/trail desc=trail]] plugin. It sets options for the
+trail represented by this page.
+
+    \[[!trailoptions sort="meta(title)" circular="no"]]
+
+Options available:
+
+* `sort`: sets a [[ikiwiki/pagespec/sorting]] order for the entire trail,
+  overriding the order in which they were added
+
+* `reverse`: reverses the order of the trail
+
+* `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/trail.mdwn b/doc/plugins/contrib/trail.mdwn
index fc43afef4c30f74f6ef118e3ef2698042f3d60b4..59daa58e7bd41922bd8c47853876f39d587905ff 100644 (file)
--- a/doc/plugins/contrib/trail.mdwn
+++ b/doc/plugins/contrib/trail.mdwn
@@ -59,8 +59,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


@@ -76,6 +77,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]],


@@ -88,7 +92,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.


@@ -124,9 +128,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]]`).