3 files changed, 32 insertions, 19 deletions
diff --git a/doc/plugins/contrib/ikiwiki/directive/ymlfront.mdwn b/doc/plugins/contrib/ikiwiki/directive/ymlfront.mdwn
new file mode 100644
index 000000000..bb4a58fc6
--- /dev/null
+++ b/doc/plugins/contrib/ikiwiki/directive/ymlfront.mdwn
@@ -0,0 +1,17 @@
+The `ymlfront` directive is supplied by the [[!iki plugins/contrib/ymlfront desc=ymlfront]] plugin.
+
+This directive allows the user to define arbitrary meta-data in YAML format.
+
+    \[[!ymlfront data="""
+     foo: fooness
+     bar: The Royal Pigeon
+     baz: 2
+     """]]
+
+There is one argument to this directive.
+
+* **data:**
+  The YAML-format data.  This should be enclosed inside triple-quotes to preserve the data correctly.
+
+If more than one ymlfront directive is given per page, the result is undefined.
+Likewise, it is inadvisable to try to mix the "---" ymlfront format with the directive form of the data.
diff --git a/doc/plugins/contrib/ymlfront.mdwn b/doc/plugins/contrib/ymlfront.mdwn
index 6dd8ed532..a2c649044 100644
--- a/doc/plugins/contrib/ymlfront.mdwn
+++ b/doc/plugins/contrib/ymlfront.mdwn
@@ -13,18 +13,21 @@ IkiWiki::Plugin::ymlfront - add YAML-format data to a page
 ## DESCRIPTION
 
 This plugin provides a way of adding arbitrary meta-data (data fields) to any
-page by prefixing the page with a YAML-format document.  This provides a way to
-create 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.
+page by prefixing the page with a YAML-format document.  This also provides
+the [[ikiwiki/directive/ymlfront]] directive, which enables one to put
+YAML-formatted data inside a standard IkiWiki [[ikiwiki/directive]].
+
+This is a way to create 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 [[field]] plugin.
 
 ## DETAILS
 
-The YAML-format data in a page must be placed at the start of the page
-and delimited by lines containing precisely three dashes.  The "normal"
-content of the page then follows.
+If one is not using the ymlfront directive, the YAML-format data in a page
+must be placed at the start of the page and delimited by lines containing
+precisely three dashes.  The "normal" content of the page then follows.
 
 For example:
 
@@ -42,7 +45,7 @@ That will be htmlized using the page-type of the page-file.
 
 ### Accessing the Data
 
-There are a few ways to access the data given in the YAML section.
+There are a few ways to access the given YAML data.
 
 * [[getfield]] plugin
 
diff --git a/doc/plugins/contrib/ymlfront/discussion.mdwn b/doc/plugins/contrib/ymlfront/discussion.mdwn
index b5c08fedd..b1fd65fff 100644
--- a/doc/plugins/contrib/ymlfront/discussion.mdwn
+++ b/doc/plugins/contrib/ymlfront/discussion.mdwn
@@ -1,13 +1,6 @@
-My field-etc branch in git://git.pseudorandom.co.uk/git/smcv/ikiwiki.git (gitweb:
-<http://git.pseudorandom.co.uk/smcv/ikiwiki.git?a=shortlog;h=refs/heads/field-etc>)
-has some fixes for compatibility with old YAML modules, mostly done by imitating
-Joey's code in IkiWiki::Setup::Yaml. Please consider merging :-) --[[smcv]]
+Now that I have implemented a \[[!ymlfront ...]] directive, I would like to remove support for the old "---" delimited format, because
 
-> I would if I could *find* it.  I checked out the "field-etc" branch, but I can't find the plugins in question under IkiWiki/Plugin; am I looking in the wrong place, or what?
-> --[[KathrynAndersen]]
+* it is fragile (easily breakable)
+* it is non-standard
 
->> Sorry, I accidentally removed `field-etc` by pushing with `--mirror` from a
->> different checkout. I've put it back; it's a branch from your `ikiplugins.git`,
->> so yes, the code should be in `IkiWiki/Plugin`. --[[smcv]]
-
->>> Done a while back, but now I've actually pushed to my repo. --[[KathrynAndersen]]
+Any objections?