Merge branch 'master' into fancypodcast

[git.ikiwiki.info.git] / doc / plugins / contrib / ymlfront.mdwn

diff --git a/doc/plugins/contrib/ymlfront.mdwn b/doc/plugins/contrib/ymlfront.mdwn
index f4438f23c11656c38272cbfa1d6a68f62aba81e2..2805be04fd838429e71be664f12558e1f1003635 100644 (file)
--- a/doc/plugins/contrib/ymlfront.mdwn
+++ b/doc/plugins/contrib/ymlfront.mdwn
@@ -10,39 +10,79 @@ IkiWiki::Plugin::ymlfront - add YAML-format data to a page
     # activate the plugin
     add_plugins => [qw{goodstuff ymlfront ....}],
 
     # activate the plugin
     add_plugins => [qw{goodstuff ymlfront ....}],
 

+    # configure the plugin
+    ymlfront_delim => [qw(--YAML-- --YAML--)],
+

 ## DESCRIPTION
 
 This plugin provides a way of adding arbitrary meta-data (data fields) to any
 ## 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
 
 
 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.
+There are three formats for adding YAML data to a page.  These formats
+should not be mixed - the result is undefined.

 
 

-For example:
+1. ymlfront directive
+   
+   See [[ikiwiki/directive/ymlfront]] for more information.

 
 

-    ---
-    title: Foo does not work
-    Urgency: High
-    Status: Assigned
-    AssignedTo: Fred Nurk
-    Version: 1.2.3
-    ---
-    When running on the Sprongle system, the Foo function returns incorrect data.
+2. default YAML-compatible delimiter
+
+   By default, the YAML-format data in a page is placed at the start of
+   the page and delimited by lines containing precisely three dashes.
+   This is what YAML itself uses to delimit multiple documents.
+   The "normal" content of the page then follows.
+
+   For example:
+
+       ---
+       title: Foo does not work
+       Urgency: High
+       Status: Assigned
+       AssignedTo: Fred Nurk
+       Version: 1.2.3
+       ---
+       When running on the Sprongle system, the Foo function returns incorrect data.

 
 

-What will normally be displayed is everything following the second line of dashes.
-That will be htmlized using the page-type of the page-file.
+   What will normally be displayed is everything following the second line of dashes.  That will be htmlized using the page-type of the page-file.
+
+3. user-defined delimiter
+
+   Instead of using the default "---" delimiter, the user can define,
+   in the configuration file, the **ymlfront_delim** value, which is an
+   array containing two strings. The first string defines the markup for
+   the start of the YAML data, and the second string defines the markip
+   for the end of the YAML data. These two strings can be the same, or
+   they can be different. In this case, the YAML data section is not
+   required to be at the start of the page, but as with the default, it
+   is expected that only one data section will be on the page.
+
+   For example:
+
+       --YAML--
+       title: Foo does not work
+       Urgency: High
+       Status: Assigned
+       AssignedTo: Fred Nurk
+       Version: 1.2.3
+       --YAML--
+       When running on the Sprongle system, the Foo function returns incorrect data.
+
+   What will normally be displayed is everything outside the delimiters,
+   both before and after.  That will be htmlized using the page-type of the page-file.

 
 ### Accessing the Data
 
 
 ### Accessing the Data
 

-There are three ways to access the data given in the YAML section.
+There are a few ways to access the given YAML data.

 
 * [[getfield]] plugin
 
 
 * [[getfield]] plugin
 


@@ -83,6 +123,10 @@ There are three ways to access the data given in the YAML section.
 
        When running on the Sprongle system, the Foo function returns incorrect data.
 
 
        When running on the Sprongle system, the Foo function returns incorrect data.
 

+* [[report]] plugin
+
+  The **report** plugin is like the [[ftemplate]] plugin, but it reports on multiple pages, rather than just the current page.
+

 * write your own plugin
 
   In conjunction with the [[field]] plugin, you can write your own plugin to access the data.
 * write your own plugin
 
   In conjunction with the [[field]] plugin, you can write your own plugin to access the data.