split trail directive into trailitems and trailoptions

5 files changed, 52 insertions, 32 deletions

diff --git a/doc/plugins/contrib/ikiwiki/directive/trail.mdwn b/doc/plugins/contrib/ikiwiki/directive/trail.mdwn
deleted file mode 100644
index cf8c370a7..000000000
--- 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 4fae7ac8a..91d8a4edf 100644
--- 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]]
-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:
diff --git a/doc/plugins/contrib/ikiwiki/directive/trailitems.mdwn b/doc/plugins/contrib/ikiwiki/directive/trailitems.mdwn
new file mode 100644
index 000000000..4106ed33b
--- /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
index 000000000..e1603f11b
--- /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 fc43afef4..59daa58e7 100644
--- 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]]
 
-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
@@ -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 [[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]],
@@ -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.
 
-* 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.
@@ -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.
 
-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]]`).