getfield: query field (meta-data) values

diff --git a/doc/plugins/contrib/getfield.mdwn b/doc/plugins/contrib/getfield.mdwn
new file mode 100644 (file)
index 0000000..ed03dc4
--- /dev/null
+++ b/doc/plugins/contrib/getfield.mdwn
@@ -0,0 +1,85 @@
+[[!template id=plugin name=getfield author="[[rubykat]]"]]
+[[!tag type/meta]]
+[[!toc]]
+## NAME
+
+IkiWiki::Plugin::getfield - query the values of fields
+
+## SYNOPSIS
+
+    # activate the plugin
+    add_plugins => [qw{goodstuff getfield ....}],
+
+## DESCRIPTION
+
+This plugin provides a way of querying the meta-data (data fields) of a page
+inside the page content (rather than inside a template) This provides a way to
+use per-page structured data, where each page is treated like a record, and the
+structured data are fields in that record.  This can include the meta-data for
+that page, such as the page title.
+
+This plugin is meant to be used in conjunction with the B<field> plugin.
+
+### USAGE
+
+One can get the value of a field by using special markup in the page.
+This does not use directive markup, in order to make it easier to
+use the markup inside other directives.  There are two forms:
+
+* {{$*fieldname*}}
+
+  This queries the value of *fieldname* for the source page.
+
+  For example:
+
+       \[[!meta title="My Long and Complicated Title With Potential For Spelling Mistakes"]]
+       # {{$title}}
+
+  When the page is processed, this will give you:
+
+       <h1>My Long and Complicated Title With Potential For Spelling Mistakes</h1>
+
+* {{+$*fieldname*+}}
+
+  This queries the value of *fieldname* for the destination page; that is,
+  the value when this page is included inside another page.
+
+  For example:
+
+  On PageA:
+
+       \[[!meta title="I Am Page A"]]
+       # {{+$title+}}
+
+       Stuff about A.
+
+  On PageB:
+
+       \[[!meta title="I Am Page B"]]
+       \[[!inline pagespec="PageA"]]
+
+  When PageA is displayed:
+
+       <h1>I Am Page A</h1>
+       <p>Stuff about A.</p>
+
+  When PageB is displayed:
+
+       <h1>I Am Page B</h1>
+       <p>Stuff about A.</p>
+
+### More Examples
+
+Listing all the sub-pages of the current page:
+
+    \[[!map pages="{{$page}}/*"]]
+
+### LIMITATIONS
+
+One cannot query the values of fields on pages other than the current
+page or the destination page.
+
+## DOWNLOAD
+
+* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/field.pm>
+* git repo at git://github.com/rubykat/ikiplugins.git