new version; splitting docs between plugin and directive pages

1 files changed, 7 insertions, 147 deletions

diff --git a/doc/plugins/contrib/report.mdwn b/doc/plugins/contrib/report.mdwn
index c364d4a3a..0bd5392c6 100644
--- a/doc/plugins/contrib/report.mdwn
+++ b/doc/plugins/contrib/report.mdwn
@@ -1,157 +1,17 @@
 [[!template id=plugin name=report author="[[rubykat]]"]]
 [[!tag type/meta type/format]]
-[[!toc]]
-## NAME
-
 IkiWiki::Plugin::report - Produce templated reports from page field data.
 
-## SYNOPSIS
-
-    # activate the plugin
-    add_plugins => [qw{goodstuff report ....}],
-
-    \[[!report template="blog_summary"
-    pages="blog/*"
-    sort="mtime"]]
-
-## DESCRIPTION
-
-This plugin provides the **report** directive.  This enables one to report on
-the structured data ("field" values) of multiple pages; the output is formatted
-via a template.  This depends on the [[plugins/contrib/field]] plugin.
-
-The pages to report on are selected by a PageSpec given by the "pages"
-parameter.  The template is given by the "template" parameter.
-The template expects the data from a single page; it is applied
-to each matching page separately, one after the other.
-
-Additional parameters can be used to fill out the template, in
-addition to the "field" values.  Passed-in values override the
-"field" values.
-
-There are two places where template files can live.  One, as with the
-[[plugins/template]] plugin, is in the /templates directory on the wiki.  These
-templates are wiki pages, and can be edited from the web like other wiki
-pages.
-
-The second place where template files can live is in the global
-templates directory (the same place where the page.tmpl template lives).
-This is a useful place to put template files if you want to prevent
-them being edited from the web, and you don't want to have to make
-them work as wiki pages.
-
-## OPTIONS
-
-**template**: The template to use for the report.
-
-**pages**: A PageSpec to determine the pages to report on.
-
-**sort**: How the matching pages should be sorted.  Sorting criteria are separated by spaces.
-
-The possible values for sorting are:
-
-* **page**: Sort by the full page ID.
-* **pagename**: Sort by the base page name.
-* **pagename_natural**: Sort by the base page name, using Sort::Naturally if it is installed.
-* **mtime**: Sort by the page modification time.
-* **age**: Sort by the page creation time, newest first.
-
-Any other value is taken to be a field name to sort by.
-If a sort value begins with a minus (-) then the order for that field is reversed.
-
-### Headers
-
-An additional option is the "headers" option.  This is a space-separated
-list of field names which are to be used as headers in the report.  This
-is a way of getting around one of the limitations of HTML::Template, that
-is, not being able to do tests such as
-"if this-header is not equal to previous-header".
-
-Instead, that logic is performed inside the plugin.  The template is
-given parameters "HEADER1", "HEADER2" and so on, for each header.
-If the value of a header field is the same as the previous value,
-then HEADER**N** is set to be empty, but if the value of the header
-field is new, then HEADER**N** is given that value.
-
-#### Example
+This plugin provides the [[ikiwiki/directive/report]] directive.  This enables
+one to report on the structured data ("field" values) of multiple pages; the
+output is formatted via a template.  This depends on the
+[[plugins/contrib/field]] plugin.
 
-Suppose you're writing a blog in which you record "moods", and you
-want to display your blog posts by mood.
 
-    \[[!report template="mood_summary"
-    pages="blog/*"
-    sort="Mood Date title"
-    headers="Mood"]]
+## Activate the plugin
 
-The "mood_summary" template might be like this:
-
-    <TMPL_IF NAME="HEADER1">
-    ## <TMPL_VAR NAME="HEADER1">
-    </TMPL_IF>
-    ### <TMPL_VAR NAME="TITLE">
-    (<TMPL_VAR NAME="DATE">) \[[<TMPL_VAR NAME="PAGE">]]
-    <TMPL_VAR NAME="DESCRIPTION">
-    
-### Advanced Options
-
-The following options are used to improve efficiency when dealing
-with large numbers of pages; most people probably won't need them.
-
-**trail**:
-
-A page or pages to use as a "trail" page.  When a trail page is used,
-the matching pages are limited to (a subset of) the pages which that
-page links to; the "pages" pagespec in this case, rather than selecting
-pages from the entire wiki, will select pages from within the set of pages
-given by the trail page.
-
-**doscan**:
-
-Whether this report should be called in "scan" mode; if it is, then
-the pages which match the pagespec are added to the list of links from
-this page.  This can be used by *another* report by setting this
-page to be a "trail" page in *that* report.
-It is not possible to use "trail" and "doscan" at the same time.
-By default, "doscan" is false.
-
-## TEMPLATE PARAMETERS
-
-The templates are in HTML::Template format, just as [[plugins/template]] and
-[[ftemplate]] are.  The parameters passed in to the template are as follows:
-
-***fields***:
-
-The structured data from the current matching page.  This includes
-"title" and "description" if they are defined.
-
-***common values***:
-
-Values known for all pages: "page", "destpage".  Also "basename" (the base name of the page).
-
-***passed-in values***:
-
-Any additional parameters to the report directive are passed to the
-template; a parameter will override the matching "field" value.
-For example, if you have a "Mood" field, and you pass Mood="bad" to
-the report, then that will be the Mood which is given for the whole
-report.
-
-Generally this is useful if one wishes to make a more generic
-template and hide or show portions of it depending on what
-values are passed in the report directive call.
-
-For example, one could have a "hide_mood" parameter which would hide
-the "Mood" section of your template when it is true, which one could
-use when the Mood is one of the headers.
-
-***headers***:
-
-See the section on Headers.
-
-***first and last***:
-
-If this is the first page-record in the report, then "first" is true.
-If this is the last page-record in the report, then "last" is true.
+    # activate the plugin
+    add_plugins => [qw{goodstuff report ....}],
 
 ## PREREQUISITES