From cf3ab205e8104035bdea74d380bd6c5670fb0036 Mon Sep 17 00:00:00 2001
From: "http://schmonz.livejournal.com/" <http://schmonz.livejournal.com/@web>
Date: Mon, 3 Aug 2009 02:56:42 -0400
Subject: note Perl module dependencies

---
 doc/plugins/contrib/cvs.mdwn | 1 +
 1 file changed, 1 insertion(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs.mdwn b/doc/plugins/contrib/cvs.mdwn
index 1ff71d274..727c3524a 100644
--- a/doc/plugins/contrib/cvs.mdwn
+++ b/doc/plugins/contrib/cvs.mdwn
@@ -10,6 +10,7 @@ This plugin allows ikiwiki to use [[!wikipedia desc="CVS" Concurrent Versions Sy
  * creates a small post-commit wrapper to prevent `cvs add <directory>` from being seen by ikiwiki's [[post-commit]] hook,
  * configures the wrapper itself as a post-commit hook in `CVSROOT/loginfo`.
 * [`cvsps`](http://www.cobite.com/cvsps/) is required (`rcs_recentchanges()` and `rcs_diff()` need it to work).
+* [[!cpan IPC::Cmd]] and [[!cpan String::ShellQuote]] are required (to safely keep `cvs` quiet and to safely escape commit messages, respectively).
 * CVS multi-directory commits happen separately; the post-commit hook sees only the first directory's changes in time for [[recentchanges|plugins/recentchanges]]. The next run of `ikiwiki --setup` will correctly re-render such a recentchanges entry. It might be possible to solve this problem with scripts like `commit_prep` and `log_accum` from CVS contrib.
 * Due to the name of CVS's metadata directories, it's impossible to create `.../CVS/foo.mdwn`. On case-insensitive filesystems it's also impossible to create `.../cvs/foo.mdwn`.
 * No testing or special-casing has been done with [[attachments|plugins/attachment]], but they'll probably need `cvs add -kb`.
-- 
cgit v1.2.3


From 9468c553e1ee8d484e896bef4c5abbeda775cabf Mon Sep 17 00:00:00 2001
From: "http://schmonz.livejournal.com/" <http://schmonz.livejournal.com/@web>
Date: Mon, 3 Aug 2009 03:23:42 -0400
Subject: maybe prevent trying to create .../CVS/whatever.mdwn

---
 doc/plugins/contrib/cvs.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs.mdwn b/doc/plugins/contrib/cvs.mdwn
index 727c3524a..fc5afebfd 100644
--- a/doc/plugins/contrib/cvs.mdwn
+++ b/doc/plugins/contrib/cvs.mdwn
@@ -12,7 +12,7 @@ This plugin allows ikiwiki to use [[!wikipedia desc="CVS" Concurrent Versions Sy
 * [`cvsps`](http://www.cobite.com/cvsps/) is required (`rcs_recentchanges()` and `rcs_diff()` need it to work).
 * [[!cpan IPC::Cmd]] and [[!cpan String::ShellQuote]] are required (to safely keep `cvs` quiet and to safely escape commit messages, respectively).
 * CVS multi-directory commits happen separately; the post-commit hook sees only the first directory's changes in time for [[recentchanges|plugins/recentchanges]]. The next run of `ikiwiki --setup` will correctly re-render such a recentchanges entry. It might be possible to solve this problem with scripts like `commit_prep` and `log_accum` from CVS contrib.
-* Due to the name of CVS's metadata directories, it's impossible to create `.../CVS/foo.mdwn`. On case-insensitive filesystems it's also impossible to create `.../cvs/foo.mdwn`.
+* Due to the name of CVS's metadata directories, it's impossible to create `.../CVS/foo.mdwn`. On case-insensitive filesystems it's also impossible to create `.../cvs/foo.mdwn`. Since the failure can have confusing effects on one's CVS checkout, perhaps the web interface should prevent the attempt.
 * No testing or special-casing has been done with [[attachments|plugins/attachment]], but they'll probably need `cvs add -kb`.
 
 Having a `$HOME/.cvsrc` isn't necessary. Sure does make using CVS more livable, though. Here's a good general-purpose one:
-- 
cgit v1.2.3


From 34e5f5eba3411855c9d3c733b6f11aa935f3d435 Mon Sep 17 00:00:00 2001
From: Jogo <Jogo@web>
Date: Thu, 6 Aug 2009 08:43:45 -0400
Subject:

---
 doc/plugins/contrib/linguas.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/linguas.mdwn b/doc/plugins/contrib/linguas.mdwn
index bf502606e..84ece042e 100644
--- a/doc/plugins/contrib/linguas.mdwn
+++ b/doc/plugins/contrib/linguas.mdwn
@@ -10,7 +10,7 @@ Download: [linguas.pm](http://ettin.org/pub/ikiwiki/linguas.pm) (2006-08-21).
 
 Note that even though it is still available for download, this plugin is no
 longer actively maintained. If you are interested in multilingual wiki pages, you
-can also take a look at other approaches such as [[todo/l10n]], [[plugins/contrib/po]],
+can also take a look at other approaches such as [[todo/l10n]], [[plugins/po]],
 or Lars Wirzenius's
 [Static website, with translations, using IkiWiki](http://liw.iki.fi/liw/log/2007-05.html#20070528b).
 
-- 
cgit v1.2.3


From 0b2100727b3e9288ff9c6587924ff5390c61f19a Mon Sep 17 00:00:00 2001
From: Jogo <Jogo@web>
Date: Thu, 6 Aug 2009 09:42:56 -0400
Subject:

---
 doc/plugins/contrib/navbar/discussion.mdwn | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 doc/plugins/contrib/navbar/discussion.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/navbar/discussion.mdwn b/doc/plugins/contrib/navbar/discussion.mdwn
new file mode 100644
index 000000000..0bbec743c
--- /dev/null
+++ b/doc/plugins/contrib/navbar/discussion.mdwn
@@ -0,0 +1,2 @@
+Where can I download this plugin ?
+-- [[jogo]]
-- 
cgit v1.2.3


From 4a331d8afc75f9c9fbfb1ef8d592fa1bfb4e2874 Mon Sep 17 00:00:00 2001
From: Jogo <Jogo@web>
Date: Thu, 6 Aug 2009 13:07:22 -0400
Subject:

---
 doc/plugins/contrib/unixrelpagespec.mdwn | 42 ++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)
 create mode 100644 doc/plugins/contrib/unixrelpagespec.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/unixrelpagespec.mdwn b/doc/plugins/contrib/unixrelpagespec.mdwn
new file mode 100644
index 000000000..a35f76c30
--- /dev/null
+++ b/doc/plugins/contrib/unixrelpagespec.mdwn
@@ -0,0 +1,42 @@
+[[!template id=plugin name=unixrelpagespec core=0 author="[[Jogo]]"]]
+
+I don't understand why `./*` correspond to siblings and not subpages.
+This is probably only meaningfull with [[plugins/autoindex]] turned on.
+
+Here is a small plugin wich follow usual Unix convention :
+
+- `./*` expand to subpages
+- `../*` expand to siblings
+
+---
+    #!/usr/bin/perl
+    # UnixRelPageSpec plugin.
+    # by Joseph Boudou <jogo at matabio dot net>
+    
+    package IkiWiki::Plugin::unixrelpagespec;
+    
+    use warnings;
+    use strict;
+    use IkiWiki 3.00;
+    
+    sub import {
+        inject(
+            name => 'IkiWiki::PageSpec::derel',
+            call => \&unix_derel
+        );
+    }
+    
+    sub unix_derel ($$) {
+        my $path = shift;
+        my $from = shift;
+    
+        if ($path =~ m!^\.{1,2}/!) {
+            $from =~ s#/?[^/]+$## if (defined $from and $path =~ m/^\.{2}/);
+            $path =~ s#^\.{1,2}/##;
+            $path = "$from/$path" if length $from;
+        }
+    
+        return $path;
+    }
+    
+    1;
-- 
cgit v1.2.3


From 255835660b91e601b250bffe5a00751767b43f87 Mon Sep 17 00:00:00 2001
From: bremner <bremner@web>
Date: Sat, 8 Aug 2009 16:48:00 -0400
Subject: question (for joeyh?) about IkiWiki::refresh()

---
 doc/plugins/contrib/postal/discussion.mdwn | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
 create mode 100644 doc/plugins/contrib/postal/discussion.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/postal/discussion.mdwn b/doc/plugins/contrib/postal/discussion.mdwn
new file mode 100644
index 000000000..90113eb41
--- /dev/null
+++ b/doc/plugins/contrib/postal/discussion.mdwn
@@ -0,0 +1,15 @@
+It seems like the filter 'postal-accept.pl' I wrote doesn't refresh thoroughly enough.  When a comment is added  it calls
+
+         IkiWiki::add_depends($page,$comments_page);
+
+And then after adding the actual comment, it ends with
+
+         IkiWiki::refresh();
+         IkiWiki::saveindex();
+
+Sure enough, the page being commented on is refreshed, but not any inline pages (e.g. tags pages, blog top level) that contain it.
+Is there a way to recursively refresh? Or should it work that way by default. I guess it is some part of the api that I don't understand, 
+since I think not many people grub about in the internals of ikiwiki this way.
+It would be nice to figure this out, doing a full rebuild every time I get a blog comment is not that fun.
+
+[[DavidBremner]]
-- 
cgit v1.2.3


From eb5e6b2bb63a7e1096e6f16ecc9d5bf881b23983 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@gnu.kitenet.net>
Date: Sat, 8 Aug 2009 17:01:10 -0400
Subject: response

---
 doc/plugins/contrib/postal/discussion.mdwn | 7 +++++++
 1 file changed, 7 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/postal/discussion.mdwn b/doc/plugins/contrib/postal/discussion.mdwn
index 90113eb41..3e6d056e2 100644
--- a/doc/plugins/contrib/postal/discussion.mdwn
+++ b/doc/plugins/contrib/postal/discussion.mdwn
@@ -13,3 +13,10 @@ since I think not many people grub about in the internals of ikiwiki this way.
 It would be nice to figure this out, doing a full rebuild every time I get a blog comment is not that fun.
 
 [[DavidBremner]]
+
+> Ikiwiki currently doesn't have support for transitive dependencies.
+> This is discussed deep inside [[todo/tracking_bugs_with_dependencies]]
+> and in [[todo/inlines_inheriting_links]]. 
+> 
+> FYI, the [[plugins/comments]] plugin avoids this problem by only showing the
+> comments on the page, and not on pages that inline it. --[[Joey]] 
-- 
cgit v1.2.3


From 3c1ebd20f84f1ec654105340a1d7c28dd3748557 Mon Sep 17 00:00:00 2001
From: bremner <bremner@web>
Date: Sat, 8 Aug 2009 17:19:07 -0400
Subject: ok, thanks. I'll probably do the same.

---
 doc/plugins/contrib/postal/discussion.mdwn | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/postal/discussion.mdwn b/doc/plugins/contrib/postal/discussion.mdwn
index 3e6d056e2..4eaacc044 100644
--- a/doc/plugins/contrib/postal/discussion.mdwn
+++ b/doc/plugins/contrib/postal/discussion.mdwn
@@ -20,3 +20,5 @@ It would be nice to figure this out, doing a full rebuild every time I get a blo
 > 
 > FYI, the [[plugins/comments]] plugin avoids this problem by only showing the
 > comments on the page, and not on pages that inline it. --[[Joey]] 
+>> Ok, thanks for the speedy response. I guess I should do the same thing.
+>> [[DavidBremner]]
-- 
cgit v1.2.3


From 792026fe97c47a3da4f941dc615ebf3bd428ad37 Mon Sep 17 00:00:00 2001
From: "http://schmonz.livejournal.com/" <http://schmonz.livejournal.com/@web>
Date: Sun, 9 Aug 2009 22:06:02 -0400
Subject: add install and usage directions, to-do list

---
 doc/plugins/contrib/cvs.mdwn | 43 ++++++++++++++++++++++++-------------------
 1 file changed, 24 insertions(+), 19 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs.mdwn b/doc/plugins/contrib/cvs.mdwn
index fc5afebfd..db9cde98b 100644
--- a/doc/plugins/contrib/cvs.mdwn
+++ b/doc/plugins/contrib/cvs.mdwn
@@ -2,20 +2,16 @@
 
 This plugin allows ikiwiki to use [[!wikipedia desc="CVS" Concurrent Versions System]] as an [[rcs]].
 
-* Diffs are against [[3.14159|news/version_3.14159]]. `cvs.pm` started life as a copy of `svn.pm`.
-* `IkiWiki.pm:wiki_file_prune_regexps` avoids copying CVS metadata into `$DESTDIR`.
-* [[ikiwiki-makerepo]]:
- * creates a repository,
- * imports `$SRCDIR` into top-level module `ikiwiki` (vendor tag IKIWIKI, release tag PRE_CVS),
- * creates a small post-commit wrapper to prevent `cvs add <directory>` from being seen by ikiwiki's [[post-commit]] hook,
- * configures the wrapper itself as a post-commit hook in `CVSROOT/loginfo`.
-* [`cvsps`](http://www.cobite.com/cvsps/) is required (`rcs_recentchanges()` and `rcs_diff()` need it to work).
-* [[!cpan IPC::Cmd]] and [[!cpan String::ShellQuote]] are required (to safely keep `cvs` quiet and to safely escape commit messages, respectively).
-* CVS multi-directory commits happen separately; the post-commit hook sees only the first directory's changes in time for [[recentchanges|plugins/recentchanges]]. The next run of `ikiwiki --setup` will correctly re-render such a recentchanges entry. It might be possible to solve this problem with scripts like `commit_prep` and `log_accum` from CVS contrib.
-* Due to the name of CVS's metadata directories, it's impossible to create `.../CVS/foo.mdwn`. On case-insensitive filesystems it's also impossible to create `.../cvs/foo.mdwn`. Since the failure can have confusing effects on one's CVS checkout, perhaps the web interface should prevent the attempt.
-* No testing or special-casing has been done with [[attachments|plugins/attachment]], but they'll probably need `cvs add -kb`.
+### Installation and usage
+7. Apply patches to [`IkiWiki.pm`](http://www.netbsd.org/~schmonz/ikiwiki-cvs/cvs-IkiWiki.pm.diff)
+and [`ikiwiki-makerepo`](http://www.netbsd.org/~schmonz/ikiwiki-cvs/cvs-ikiwiki-makerepo.diff).
+7. Rebuild and install ikiwiki.
+7. Install [cvsps](http://www.cobite.com/cvsps/), [[!cpan IPC::Cmd]], [[!cpan String::ShellQuote]], and [cvsweb](http://www.freebsd.org/projects/cvsweb.html) or the like.
+7. Download [`cvs.pm`](http://www.netbsd.org/~schmonz/ikiwiki-cvs/cvs.pm) into a suitable `$libdir/IkiWiki/Plugin`.
+7. While setting up a wiki [[by hand|setup/byhand]], also specify `--libdir` until you get to the point where you have a setup file. (This ensures the CVS plugin is found and its settings stanza included.)
+7. Adjust CVS-related parameters in your setup file.
 
-Having a `$HOME/.cvsrc` isn't necessary. Sure does make using CVS more livable, though. Here's a good general-purpose one:
+Consider creating `$HOME/.cvsrc` if you don't have one already; the plugin doesn't need it, but you yourself might. Here's a good general-purpose one:
 
     cvs -q
     checkout -P
@@ -23,10 +19,19 @@ Having a `$HOME/.cvsrc` isn't necessary. Sure does make using CVS more livable,
     diff -u
     rdiff -u
 
-Not knowing how the tests get set up, I blindly attempted to add subversion-like tests to `t/file_pruned.t`. They fail. But the plugin definitely works. :-)
+### Implementation details
+* Diffs are against [[3.14159|news/version_3.14159]]. `cvs.pm` started life as a copy of `svn.pm`.
+* `IkiWiki.pm:wiki_file_prune_regexps` avoids copying CVS metadata into `$DESTDIR`.
+* [[ikiwiki-makerepo]]:
+ * creates a repository,
+ * imports `$SRCDIR` into top-level module `ikiwiki` (vendor tag IKIWIKI, release tag PRE_CVS),
+ * creates a small post-commit wrapper to prevent `cvs add <directory>` from being seen by ikiwiki's [[post-commit]] hook,
+ * configures the wrapper itself as a post-commit hook in `CVSROOT/loginfo`.
+* CVS multi-directory commits happen separately; the post-commit hook sees only the first directory's changes in time for [[recentchanges|plugins/recentchanges]]. The next run of `ikiwiki --setup` will correctly re-render such a recentchanges entry. It should be possible to solve this problem with NetBSD's `commit_prep` and `log_accum`scripts (see below).
 
-### Code
-* [`cvs.pm`](http://www.netbsd.org/~schmonz/ikiwiki-cvs/cvs.pm)
-* [`cvs-IkiWiki.pm.diff`](http://www.netbsd.org/~schmonz/ikiwiki-cvs/cvs-IkiWiki.pm.diff)
-* [`cvs-ikiwiki-makerepo.diff`](http://www.netbsd.org/~schmonz/ikiwiki-cvs/cvs-ikiwiki-makerepo.diff)
-* [`cvs-t-file_pruned.t.diff`](http://www.netbsd.org/~schmonz/ikiwiki-cvs/cvs-t-file_pruned.t.diff)
+### To do
+* Add automated tests. ([Blindly adding svn-like tests to `t/file_pruned.t`](http://www.netbsd.org/~schmonz/ikiwiki-cvs/cvs-t-file_pruned.t.diff) doesn't do the trick.)
+* If the argument to `cvs add` smells like a binary file, `cvs add -kb` it (for [[plugins/attachment]] support).
+* Don't slurp the entire `cvsps` output into memory (!).
+* Instead of resource-intensively scraping changesets with `cvsps`, have `ikiwiki-makerepo` set up NetBSD-like `log_accum` and `commit_prep` scripts that coalesce and keep records of commits. `cvsps` can be used as a fallback for repositories without such records.
+* Perhaps prevent web edits from attempting to create `.../CVS/foo.mdwn` (and `.../cvs/foo.mdwn` on case-insensitive filesystems); thanks to the CVS metadata directory, the attempt will fail anyway (and much more confusingly) if we don't.
-- 
cgit v1.2.3


From af29201c3ce1099fbc3f8e6986d098fac6cef249 Mon Sep 17 00:00:00 2001
From: "http://schmonz.livejournal.com/" <http://schmonz.livejournal.com/@web>
Date: Sun, 9 Aug 2009 22:09:42 -0400
Subject: the post-commit wrapper wrapper also avoids cvs deadlock

---
 doc/plugins/contrib/cvs.mdwn | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs.mdwn b/doc/plugins/contrib/cvs.mdwn
index db9cde98b..f466b9399 100644
--- a/doc/plugins/contrib/cvs.mdwn
+++ b/doc/plugins/contrib/cvs.mdwn
@@ -25,9 +25,9 @@ Consider creating `$HOME/.cvsrc` if you don't have one already; the plugin doesn
 * [[ikiwiki-makerepo]]:
  * creates a repository,
  * imports `$SRCDIR` into top-level module `ikiwiki` (vendor tag IKIWIKI, release tag PRE_CVS),
- * creates a small post-commit wrapper to prevent `cvs add <directory>` from being seen by ikiwiki's [[post-commit]] hook,
+ * creates a small post-commit wrapper to prevent `cvs add <directory>` from being seen by ikiwiki's [[post-commit]] hook (and avoid `cvs` locking against itself),
  * configures the wrapper itself as a post-commit hook in `CVSROOT/loginfo`.
-* CVS multi-directory commits happen separately; the post-commit hook sees only the first directory's changes in time for [[recentchanges|plugins/recentchanges]]. The next run of `ikiwiki --setup` will correctly re-render such a recentchanges entry. It should be possible to solve this problem with NetBSD's `commit_prep` and `log_accum`scripts (see below).
+* CVS multi-directory commits happen separately; the post-commit hook sees only the first directory's changes in time for [[recentchanges|plugins/recentchanges]]. The next run of `ikiwiki --setup` will correctly re-render such a recentchanges entry. It should be possible to solve this problem with NetBSD's `commit_prep` and `log_accum` scripts (see below).
 
 ### To do
 * Add automated tests. ([Blindly adding svn-like tests to `t/file_pruned.t`](http://www.netbsd.org/~schmonz/ikiwiki-cvs/cvs-t-file_pruned.t.diff) doesn't do the trick.)
-- 
cgit v1.2.3


From 8ba32abaf27110d86a52720bcb738402bf90fadb Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@gnu.kitenet.net>
Date: Thu, 13 Aug 2009 17:55:01 -0400
Subject: review: question

---
 doc/plugins/contrib/cvs/discussion | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 doc/plugins/contrib/cvs/discussion

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs/discussion b/doc/plugins/contrib/cvs/discussion
new file mode 100644
index 000000000..e2411af63
--- /dev/null
+++ b/doc/plugins/contrib/cvs/discussion
@@ -0,0 +1,5 @@
+I've started reviewing this, and the main thing I don't like is the
+post-commit wrapper wrapper that ikiwiki-makerepo is patched to set up.
+That just seems unnecessarily complicated. Why can't ikiwiki itself detect
+the "cvs add <directory>" call and avoid doing anything in that case?
+--[[Joey]] 
-- 
cgit v1.2.3


From 3401dc6110ac785c1df3f447d2f1de017be92538 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@gnu.kitenet.net>
Date: Thu, 13 Aug 2009 18:12:28 -0400
Subject: fix name

---
 doc/plugins/contrib/cvs/discussion      | 5 -----
 doc/plugins/contrib/cvs/discussion.mdwn | 5 +++++
 2 files changed, 5 insertions(+), 5 deletions(-)
 delete mode 100644 doc/plugins/contrib/cvs/discussion
 create mode 100644 doc/plugins/contrib/cvs/discussion.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs/discussion b/doc/plugins/contrib/cvs/discussion
deleted file mode 100644
index e2411af63..000000000
--- a/doc/plugins/contrib/cvs/discussion
+++ /dev/null
@@ -1,5 +0,0 @@
-I've started reviewing this, and the main thing I don't like is the
-post-commit wrapper wrapper that ikiwiki-makerepo is patched to set up.
-That just seems unnecessarily complicated. Why can't ikiwiki itself detect
-the "cvs add <directory>" call and avoid doing anything in that case?
---[[Joey]] 
diff --git a/doc/plugins/contrib/cvs/discussion.mdwn b/doc/plugins/contrib/cvs/discussion.mdwn
new file mode 100644
index 000000000..e2411af63
--- /dev/null
+++ b/doc/plugins/contrib/cvs/discussion.mdwn
@@ -0,0 +1,5 @@
+I've started reviewing this, and the main thing I don't like is the
+post-commit wrapper wrapper that ikiwiki-makerepo is patched to set up.
+That just seems unnecessarily complicated. Why can't ikiwiki itself detect
+the "cvs add <directory>" call and avoid doing anything in that case?
+--[[Joey]] 
-- 
cgit v1.2.3


From b5576b556027e8f9b9ad52e02b383b8644adfb33 Mon Sep 17 00:00:00 2001
From: Amitai Schlair <schmonz@magnetic-babysitter.(none)>
Date: Sun, 16 Aug 2009 11:58:28 -0400
Subject: Life is simpler on a git branch.

---
 doc/plugins/contrib/cvs.mdwn | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs.mdwn b/doc/plugins/contrib/cvs.mdwn
index f466b9399..23e00201f 100644
--- a/doc/plugins/contrib/cvs.mdwn
+++ b/doc/plugins/contrib/cvs.mdwn
@@ -1,14 +1,11 @@
 [[!template id=plugin name=cvs core=0 author="[[schmonz]]"]]
 
+[[!template id=gitbranch branch=schmonz author="[[schmonz]]"]]
+
 This plugin allows ikiwiki to use [[!wikipedia desc="CVS" Concurrent Versions System]] as an [[rcs]].
 
-### Installation and usage
-7. Apply patches to [`IkiWiki.pm`](http://www.netbsd.org/~schmonz/ikiwiki-cvs/cvs-IkiWiki.pm.diff)
-and [`ikiwiki-makerepo`](http://www.netbsd.org/~schmonz/ikiwiki-cvs/cvs-ikiwiki-makerepo.diff).
-7. Rebuild and install ikiwiki.
+### Usage
 7. Install [cvsps](http://www.cobite.com/cvsps/), [[!cpan IPC::Cmd]], [[!cpan String::ShellQuote]], and [cvsweb](http://www.freebsd.org/projects/cvsweb.html) or the like.
-7. Download [`cvs.pm`](http://www.netbsd.org/~schmonz/ikiwiki-cvs/cvs.pm) into a suitable `$libdir/IkiWiki/Plugin`.
-7. While setting up a wiki [[by hand|setup/byhand]], also specify `--libdir` until you get to the point where you have a setup file. (This ensures the CVS plugin is found and its settings stanza included.)
 7. Adjust CVS-related parameters in your setup file.
 
 Consider creating `$HOME/.cvsrc` if you don't have one already; the plugin doesn't need it, but you yourself might. Here's a good general-purpose one:
@@ -20,7 +17,7 @@ Consider creating `$HOME/.cvsrc` if you don't have one already; the plugin doesn
     rdiff -u
 
 ### Implementation details
-* Diffs are against [[3.14159|news/version_3.14159]]. `cvs.pm` started life as a copy of `svn.pm`.
+* `cvs.pm` started life as a copy of [[3.14159|news/version_3.14159]]'s `svn.pm`.
 * `IkiWiki.pm:wiki_file_prune_regexps` avoids copying CVS metadata into `$DESTDIR`.
 * [[ikiwiki-makerepo]]:
  * creates a repository,
@@ -30,7 +27,7 @@ Consider creating `$HOME/.cvsrc` if you don't have one already; the plugin doesn
 * CVS multi-directory commits happen separately; the post-commit hook sees only the first directory's changes in time for [[recentchanges|plugins/recentchanges]]. The next run of `ikiwiki --setup` will correctly re-render such a recentchanges entry. It should be possible to solve this problem with NetBSD's `commit_prep` and `log_accum` scripts (see below).
 
 ### To do
-* Add automated tests. ([Blindly adding svn-like tests to `t/file_pruned.t`](http://www.netbsd.org/~schmonz/ikiwiki-cvs/cvs-t-file_pruned.t.diff) doesn't do the trick.)
+* Add automated tests. (Blindly adding svn-like tests to `t/file_pruned.t` doesn't do the trick.)
 * If the argument to `cvs add` smells like a binary file, `cvs add -kb` it (for [[plugins/attachment]] support).
 * Don't slurp the entire `cvsps` output into memory (!).
 * Instead of resource-intensively scraping changesets with `cvsps`, have `ikiwiki-makerepo` set up NetBSD-like `log_accum` and `commit_prep` scripts that coalesce and keep records of commits. `cvsps` can be used as a fallback for repositories without such records.
-- 
cgit v1.2.3


From 24d43bea075354ecd8546131529a064140b9039c Mon Sep 17 00:00:00 2001
From: Amitai Schlair <schmonz@magnetic-babysitter.(none)>
Date: Thu, 20 Aug 2009 16:10:56 -0400
Subject: response

---
 doc/plugins/contrib/cvs/discussion.mdwn | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs/discussion.mdwn b/doc/plugins/contrib/cvs/discussion.mdwn
index e2411af63..847d0f92a 100644
--- a/doc/plugins/contrib/cvs/discussion.mdwn
+++ b/doc/plugins/contrib/cvs/discussion.mdwn
@@ -3,3 +3,33 @@ post-commit wrapper wrapper that ikiwiki-makerepo is patched to set up.
 That just seems unnecessarily complicated. Why can't ikiwiki itself detect
 the "cvs add <directory>" call and avoid doing anything in that case?
 --[[Joey]] 
+
+> The wrapper wrapper does three things:
+>
+> 7. It ignores `cvs add <directory>`, since this is a weird CVS
+> behavior that ikiwiki gets confused by and doesn't need to act on.
+> 7. It prevents `cvs` locking against itself: `cvs commit` takes a
+> write lock and runs the post-commit hook, which runs `cvs update`,
+> which wants a read lock and sleeps forever -- unless the post-commit
+> hook runs in the background so the commit can "finish".
+> 7. It fails silently if the ikiwiki post-commit hook is missing.
+> CVS doesn't have any magic post-commit filenames, so hooks have to
+> be configured explicitly. I don't think a commit will actually fail
+> if a configured post-commit hook is missing (though I can't test
+> this at the moment).
+>
+> Thing 1 can probably be handled within ikiwiki, if that seems less
+> gross to you.
+>
+> Thing 2 I'm less sure of. (I'd like to see the web UI return
+> immediately on save anyway, to a temporary "rebuilding, please wait
+> if you feel like knowing when it's done" page, but this problem
+> with CVS happens with any kind of commit, and could conceivably
+> happen with some other VCS.)
+>
+> Thing 3 I think I did in order to squelch the error messages that
+> were bollixing up the CGI. It was easy to do this in the wrapper
+> wrapper, but if that's going away, it can be done just as easily
+> with output redirection in `CVSROOT/loginfo`.
+>
+> --[[schmonz]]
-- 
cgit v1.2.3


From 73e562edc865c6357cc1b4c8436e0a44957800e8 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@gnu.kitenet.net>
Date: Fri, 21 Aug 2009 16:09:26 -0400
Subject: response

---
 doc/plugins/contrib/cvs/discussion.mdwn | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs/discussion.mdwn b/doc/plugins/contrib/cvs/discussion.mdwn
index 847d0f92a..ed6cf506e 100644
--- a/doc/plugins/contrib/cvs/discussion.mdwn
+++ b/doc/plugins/contrib/cvs/discussion.mdwn
@@ -20,16 +20,34 @@ the "cvs add <directory>" call and avoid doing anything in that case?
 >
 > Thing 1 can probably be handled within ikiwiki, if that seems less
 > gross to you.
->
+
+>> It seems like it might be. You can use a `getopt` hook to check
+>> `@ARGV` to see how it was called. --[[Joey]] 
+
 > Thing 2 I'm less sure of. (I'd like to see the web UI return
 > immediately on save anyway, to a temporary "rebuilding, please wait
 > if you feel like knowing when it's done" page, but this problem
 > with CVS happens with any kind of commit, and could conceivably
 > happen with some other VCS.)
->
+
+>> None of the other VCSes let a write lock block a read lock, apparently.
+>> 
+>> Anyway, re the backgrounding, when committing via the web, the
+>> post-commit hook doesn't run anyway; the rendering is done via the
+>> ikiwiki CGI. It would certianly be nice if it popped up a quick "working"
+>> page and replaced it with the updated page when done, but that's
+>> unrelated;  the post-commit
+>> hook only does rendering when committing using the VCS directly. The
+>> backgrounding you do actually seems safe enough -- but tacking
+>> on a " &" to the ikiwiki wrapper call doesn't need a wrapper script,
+>> does it? --[[Joey]]
+
 > Thing 3 I think I did in order to squelch the error messages that
 > were bollixing up the CGI. It was easy to do this in the wrapper
 > wrapper, but if that's going away, it can be done just as easily
 > with output redirection in `CVSROOT/loginfo`.
 >
 > --[[schmonz]]
+
+>> If the error messages screw up the CGI they must go to stdout.
+>> I thought we had stderr even in the the CVS dark ages. ;-) --[[Joey]] 
-- 
cgit v1.2.3


From 7849d675a3cf3792a271a2fa9fc9172b394b3f25 Mon Sep 17 00:00:00 2001
From: Amitai Schlair <schmonz@magnetic-babysitter.(none)>
Date: Sat, 22 Aug 2009 02:02:34 -0400
Subject: response

---
 doc/plugins/contrib/cvs/discussion.mdwn | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs/discussion.mdwn b/doc/plugins/contrib/cvs/discussion.mdwn
index ed6cf506e..65b6befd1 100644
--- a/doc/plugins/contrib/cvs/discussion.mdwn
+++ b/doc/plugins/contrib/cvs/discussion.mdwn
@@ -24,6 +24,13 @@ the "cvs add <directory>" call and avoid doing anything in that case?
 >> It seems like it might be. You can use a `getopt` hook to check
 >> `@ARGV` to see how it was called. --[[Joey]] 
 
+>>> This does the trick iff the post-commit wrapper passes its args
+>>> along. Committed on my branch. This seems potentially dangerous,
+>>> since the args passed to ikiwiki are influenced by web commits.
+>>> I don't see an exploit, but for paranoia's sake, maybe the wrapper
+>>> should only be built with execv() if the cvs plugin is loaded?
+>>> --[[schmonz]]
+
 > Thing 2 I'm less sure of. (I'd like to see the web UI return
 > immediately on save anyway, to a temporary "rebuilding, please wait
 > if you feel like knowing when it's done" page, but this problem
@@ -42,6 +49,9 @@ the "cvs add <directory>" call and avoid doing anything in that case?
 >> on a " &" to the ikiwiki wrapper call doesn't need a wrapper script,
 >> does it? --[[Joey]]
 
+>>> Nope, it works fine to append it to the `CVSROOT/loginfo` line.
+>>> Fixed on my branch. --[[schmonz]]
+
 > Thing 3 I think I did in order to squelch the error messages that
 > were bollixing up the CGI. It was easy to do this in the wrapper
 > wrapper, but if that's going away, it can be done just as easily
@@ -51,3 +61,10 @@ the "cvs add <directory>" call and avoid doing anything in that case?
 
 >> If the error messages screw up the CGI they must go to stdout.
 >> I thought we had stderr even in the the CVS dark ages. ;-) --[[Joey]] 
+
+>>> Some messages go to stderr, but definitely not all. That's why
+>>> I wound up reaching for IPC::Cmd, to execute the command line
+>>> safely while shutting CVS up. Anyway, I've tested what happens
+>>> if a configured post-commit hook is missing, and it seems fine,
+>>> probably also thanks to IPC::Cmd.
+>>> --[[schmonz]]
-- 
cgit v1.2.3


From 2acc71849d78d1dde7ac237e8ebc54d33548e9e7 Mon Sep 17 00:00:00 2001
From: Amitai Schlair <schmonz@magnetic-babysitter.(none)>
Date: Sat, 22 Aug 2009 03:52:45 -0400
Subject: no more wrapper wrapper

---
 doc/plugins/contrib/cvs.mdwn | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs.mdwn b/doc/plugins/contrib/cvs.mdwn
index 23e00201f..6b600eef7 100644
--- a/doc/plugins/contrib/cvs.mdwn
+++ b/doc/plugins/contrib/cvs.mdwn
@@ -22,8 +22,7 @@ Consider creating `$HOME/.cvsrc` if you don't have one already; the plugin doesn
 * [[ikiwiki-makerepo]]:
  * creates a repository,
  * imports `$SRCDIR` into top-level module `ikiwiki` (vendor tag IKIWIKI, release tag PRE_CVS),
- * creates a small post-commit wrapper to prevent `cvs add <directory>` from being seen by ikiwiki's [[post-commit]] hook (and avoid `cvs` locking against itself),
- * configures the wrapper itself as a post-commit hook in `CVSROOT/loginfo`.
+ * configures the post-commit hook in `CVSROOT/loginfo`.
 * CVS multi-directory commits happen separately; the post-commit hook sees only the first directory's changes in time for [[recentchanges|plugins/recentchanges]]. The next run of `ikiwiki --setup` will correctly re-render such a recentchanges entry. It should be possible to solve this problem with NetBSD's `commit_prep` and `log_accum` scripts (see below).
 
 ### To do
-- 
cgit v1.2.3


From 59527de76708616bc8966d0ced3577573c3062b6 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@gnu.kitenet.net>
Date: Sat, 22 Aug 2009 14:29:18 -0400
Subject: uh oh

---
 doc/plugins/contrib/cvs/discussion.mdwn | 5 +++++
 1 file changed, 5 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs/discussion.mdwn b/doc/plugins/contrib/cvs/discussion.mdwn
index 65b6befd1..b063a53c2 100644
--- a/doc/plugins/contrib/cvs/discussion.mdwn
+++ b/doc/plugins/contrib/cvs/discussion.mdwn
@@ -31,6 +31,11 @@ the "cvs add <directory>" call and avoid doing anything in that case?
 >>> should only be built with execv() if the cvs plugin is loaded?
 >>> --[[schmonz]]
 
+>>>> Hadn't considered that. While in wrapper mode the normal getopt is not
+>>>> done, plugin getopt still runs, and so any unsafe options that 
+>>>> other plugins support could be a problem if another user runs
+>>>> the setuid wrapper and passes those options through. --[[Joey]]
+
 > Thing 2 I'm less sure of. (I'd like to see the web UI return
 > immediately on save anyway, to a temporary "rebuilding, please wait
 > if you feel like knowing when it's done" page, but this problem
-- 
cgit v1.2.3


From 0d5a8bc3f060a26069df4c20880888303ff41d55 Mon Sep 17 00:00:00 2001
From: Amitai Schlair <schmonz@magnetic-babysitter.(none)>
Date: Sun, 23 Aug 2009 15:41:29 -0400
Subject: new rsync plugin

---
 doc/plugins/contrib/rsync.mdwn | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)
 create mode 100644 doc/plugins/contrib/rsync.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/rsync.mdwn b/doc/plugins/contrib/rsync.mdwn
new file mode 100644
index 000000000..71cd63947
--- /dev/null
+++ b/doc/plugins/contrib/rsync.mdwn
@@ -0,0 +1,21 @@
+[[!template id=plugin name=rsync core=0 author="[[schmonz]]"]]
+
+[[!template id=gitbranch branch=schmonz author="[[schmonz]]"]]
+
+This plugin allows ikiwiki to push generated pages to another host
+by running a command such as `rsync`.
+
+### Usage
+7. Enable automated SSH key exchange between ikiwiki and the remote
+   host. [keychain](http://www.gentoo.org/proj/en/keychain/) makes
+   it easy to use a passphrase-protected key for this purpose. It's
+   also a good idea to specify the exact command line to be permitted
+   in the remote host's `$HOME/.ssh/authorized_keys`.
+7. Set `rsync_command` in your setup file. If you're using a
+   passphrase-protected key, then set `rsync_command` to a shell
+   script which reads `keychain`'s current state before calling
+   `rsync`.
+
+### Implementation details
+* The plugin relies on a new "postrefresh" hook called at the very end of
+  `IkiWiki/Render.pm:refresh()`.
-- 
cgit v1.2.3


From 18a7b65094ca761fea0785a81f3c0923ea66b018 Mon Sep 17 00:00:00 2001
From: Amitai Schlair <schmonz@magnetic-babysitter.(none)>
Date: Sun, 23 Aug 2009 18:15:56 -0400
Subject: response

---
 doc/plugins/contrib/cvs/discussion.mdwn | 13 +++++++++++++
 1 file changed, 13 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs/discussion.mdwn b/doc/plugins/contrib/cvs/discussion.mdwn
index b063a53c2..2de938fb7 100644
--- a/doc/plugins/contrib/cvs/discussion.mdwn
+++ b/doc/plugins/contrib/cvs/discussion.mdwn
@@ -36,6 +36,19 @@ the "cvs add <directory>" call and avoid doing anything in that case?
 >>>> other plugins support could be a problem if another user runs
 >>>> the setuid wrapper and passes those options through. --[[Joey]]
 
+>>>>> I've tried compiling the argument check into the wrapper as
+>>>>> the first thing main() does, and was surprised to find that
+>>>>> this doesn't prevent the `cvs add <dir>` deadlock in a web
+>>>>> commit. I was convinced this'd be a reasonable solution,
+>>>>> especially if conditionalized on the cvs plugin being loaded,
+>>>>> but it doesn't work. And I stuck debug printfs at the beginning
+>>>>> of all the rcs_foo() subs, and whatever `cvs add <dir>` is
+>>>>> doing to ikiwiki isn't visible to my plugin, because none of
+>>>>> those subs are getting called. Nuts. Can you think of anything
+>>>>> else that might solve the problem, or should I go back to
+>>>>> generating a minimal wrapper wrapper that checks for just
+>>>>> this one thing? --[[schmonz]]
+
 > Thing 2 I'm less sure of. (I'd like to see the web UI return
 > immediately on save anyway, to a temporary "rebuilding, please wait
 > if you feel like knowing when it's done" page, but this problem
-- 
cgit v1.2.3


From 80ca685385cd827f19718eaea5fb772782f68d3b Mon Sep 17 00:00:00 2001
From: Amitai Schlair <schmonz@magnetic-babysitter.(none)>
Date: Sun, 23 Aug 2009 23:27:53 -0400
Subject: why I needed this, in case it's useful to someone else

---
 doc/plugins/contrib/rsync/discussion.mdwn | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)
 create mode 100644 doc/plugins/contrib/rsync/discussion.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/rsync/discussion.mdwn b/doc/plugins/contrib/rsync/discussion.mdwn
new file mode 100644
index 000000000..a2c2eb725
--- /dev/null
+++ b/doc/plugins/contrib/rsync/discussion.mdwn
@@ -0,0 +1,27 @@
+## A use case
+
+Why I needed this plugin: I have two web servers available to me
+for a project. Neither does everything I need, but together they
+do. (This is a bit like the [Amazon S3
+scenario](http://kitenet.net/~joey/blog/entry/running_a_wiki_on_Amazon_S3/).)
+
+Server (1) is a university web server. It provides plentiful space
+and bandwidth, easy authentication for people editing the wiki, and
+a well-known stable URL. The wiki really wants to live here and
+very easily could except that the server doesn't allow arbitrary
+CGIs.
+
+Server (2) is provided by a generous alumnus's paid [[tips/DreamHost]]
+account. Disk and particularly network usage need to be minimized
+because over some threshold it costs him. CGI, etc. are available.
+
+My plan was to host the wiki on server (1) by taking advantage of
+server (2) to store the repository, source checkout, and generated
+pages, to host the repository browser, and to handle ikiwiki's CGI
+operations. In order for this to work, web edits on (2) would need
+to automatically push any changed pages to (1).
+
+As a proof of concept, I added an rsync post-commit hook after
+ikiwiki's usual. It worked, just not for web edits, which is how
+the wiki will be used. So I wrote this plugin to finish the job.
+The wiki now lives on (1), and clicking "edit" just works.
-- 
cgit v1.2.3


From a27861c512bcf5808c59d9bc2b38c80b559d6d69 Mon Sep 17 00:00:00 2001
From: "http://www.cse.unsw.edu.au/~willu/"
 <http://www.cse.unsw.edu.au/~willu/@web>
Date: Mon, 24 Aug 2009 03:13:25 -0400
Subject: Comment on another possible solution to the use case.

---
 doc/plugins/contrib/rsync/discussion.mdwn | 11 +++++++++++
 1 file changed, 11 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/rsync/discussion.mdwn b/doc/plugins/contrib/rsync/discussion.mdwn
index a2c2eb725..b2d21e6d5 100644
--- a/doc/plugins/contrib/rsync/discussion.mdwn
+++ b/doc/plugins/contrib/rsync/discussion.mdwn
@@ -25,3 +25,14 @@ As a proof of concept, I added an rsync post-commit hook after
 ikiwiki's usual. It worked, just not for web edits, which is how
 the wiki will be used. So I wrote this plugin to finish the job.
 The wiki now lives on (1), and clicking "edit" just works.
+
+> Just out of interest, why use `rsync` and not `git push`.  i.e. a
+> different setup to solve the same problem would be to run a
+> normal ikiwiki setup on the universities server with its git
+> repository available over ssh (same security setup your using
+> for rsync should work for git over ssh).  On the cgi-capable server,
+> when it would rsync, make it git push.  It would seem that git
+> has enough information that it should be able to be more
+> network efficient.  It also means that corruption at one end
+> wouldn't be propagated to the other end. -- [[Will]]
+
-- 
cgit v1.2.3


From 8d504e6b3dcacd333c0b07387e7acd3bf8a65d9c Mon Sep 17 00:00:00 2001
From: "http://schmonz.livejournal.com/" <http://schmonz.livejournal.com/@web>
Date: Mon, 24 Aug 2009 04:20:31 -0400
Subject: response

---
 doc/plugins/contrib/rsync/discussion.mdwn | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/rsync/discussion.mdwn b/doc/plugins/contrib/rsync/discussion.mdwn
index b2d21e6d5..20c04af0f 100644
--- a/doc/plugins/contrib/rsync/discussion.mdwn
+++ b/doc/plugins/contrib/rsync/discussion.mdwn
@@ -24,7 +24,7 @@ to automatically push any changed pages to (1).
 As a proof of concept, I added an rsync post-commit hook after
 ikiwiki's usual. It worked, just not for web edits, which is how
 the wiki will be used. So I wrote this plugin to finish the job.
-The wiki now lives on (1), and clicking "edit" just works.
+The wiki now lives on (1), and clicking "edit" just works. --[[schmonz]]
 
 > Just out of interest, why use `rsync` and not `git push`.  i.e. a
 > different setup to solve the same problem would be to run a
@@ -36,3 +36,13 @@ The wiki now lives on (1), and clicking "edit" just works.
 > network efficient.  It also means that corruption at one end
 > wouldn't be propagated to the other end. -- [[Will]]
 
+>> Hey, that's a nice solution. (The site was in svn to begin with,
+>> but it's in git now.) One advantage of my approach in this particular
+>> case: server (1) doesn't have `git` installed, but does have `rsync`,
+>> so (1)'s environment can remain completely untweaked other than the
+>> SSH arrangement. I kind of like that all the sysadmin effort is
+>> contained on one host.
+>>
+>> This plugin is definitely still useful for projects not able to use
+>> a DVCS (of which I've got at least one other), and possibly for
+>> other uses not yet imagined. ;-) --[[schmonz]]
-- 
cgit v1.2.3


From 43db8269a002daf00ac6195d4bd70018b4b68b75 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@gnu.kitenet.net>
Date: Mon, 24 Aug 2009 15:47:24 -0400
Subject: response

---
 doc/plugins/contrib/cvs/discussion.mdwn | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs/discussion.mdwn b/doc/plugins/contrib/cvs/discussion.mdwn
index 2de938fb7..e1fa6e428 100644
--- a/doc/plugins/contrib/cvs/discussion.mdwn
+++ b/doc/plugins/contrib/cvs/discussion.mdwn
@@ -49,6 +49,9 @@ the "cvs add <directory>" call and avoid doing anything in that case?
 >>>>> generating a minimal wrapper wrapper that checks for just
 >>>>> this one thing? --[[schmonz]]
 
+>>>>>> I don't see how there could possibly be a difference between
+>>>>>> ikiwiki's C wrapper and your shell wrapper wrapper here. --[[Joey]]
+
 > Thing 2 I'm less sure of. (I'd like to see the web UI return
 > immediately on save anyway, to a temporary "rebuilding, please wait
 > if you feel like knowing when it's done" page, but this problem
-- 
cgit v1.2.3


From 6962b3459725a921714b4d777cab6288711f4990 Mon Sep 17 00:00:00 2001
From: Amitai Schlair <schmonz@magnetic-babysitter.(none)>
Date: Sat, 29 Aug 2009 22:17:40 -0400
Subject: This is in my git branch now, no need for a copy of the code here.

---
 doc/plugins/contrib/unixauth.mdwn | 204 +-------------------------------------
 1 file changed, 2 insertions(+), 202 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/unixauth.mdwn b/doc/plugins/contrib/unixauth.mdwn
index 6108ebfae..137195139 100644
--- a/doc/plugins/contrib/unixauth.mdwn
+++ b/doc/plugins/contrib/unixauth.mdwn
@@ -1,6 +1,8 @@
 [[!template id=plugin name=unixauth core=0 author="[[schmonz]]"]]
 [[!tag type/auth]]
 
+[[!template id=gitbranch branch=schmonz author="[[schmonz]]"]]
+
 This plugin authenticates users against the Unix user database. It presents a similar UI to [[plugins/passwordauth]], but simpler, as there's no need to be able to register or change one's password.
 
 To authenticate, either [checkpassword](http://cr.yp.to/checkpwd.html) or [pwauth](http://www.unixpapa.com/pwauth/) must be installed and configured. `checkpassword` is strongly preferred. If your web server runs as an unprivileged user -- as it darn well should! -- then `checkpassword` needs to be setuid root. (Or your ikiwiki CGI wrapper, I guess, but don't do that.) Other checkpassword implementations are available, notably [checkpassword-pam](http://checkpasswd-pam.sourceforge.net/).
@@ -17,205 +19,3 @@ __Security__: [As with passwordauth](/security/#index14h2), be wary of sending u
 `unixauth` needs the `HTTPS` environment variable, available in ikiwiki 2.67 or later (fixed in #[502047](http://bugs.debian.org/502047)), without which it fails closed.
 
 The plugin has not been tested with newer versions of ikiwiki. [[schmonz]] hopes to have time to polish this plugin soon.
-
-[[!toggle id="code" text="unixauth.pm"]]
-
-[[!toggleable id="code" text="""
-
-    #!/usr/bin/perl
-    # Ikiwiki unixauth authentication.
-    package IkiWiki::Plugin::unixauth;
-    
-    use warnings;
-    use strict;
-    use IkiWiki 2.00;
-    
-    sub import {
-        hook(type => "getsetup", id => "unixauth", call => \&getsetup);
-            hook(type => "formbuilder_setup", id => "unixauth",
-                call => \&formbuilder_setup);
-            hook(type => "formbuilder", id => "unixauth",
-                call => \&formbuilder);
-        hook(type => "sessioncgi", id => "unixauth", call => \&sessioncgi);
-    }
-    
-    sub getsetup () {
-        return
-        unixauth_type => {
-                type => "string",
-                example => "checkpassword",
-                description => "type of authenticator; can be 'checkpassword' or 'pwauth'",
-                safe => 0,
-                rebuild => 1,
-        },
-        unixauth_command => {
-                type => "string",
-                example => "/path/to/checkpassword",
-                description => "full path and any arguments",
-                safe => 0,
-                rebuild => 1,
-        },
-        unixauth_requiressl => {
-                type => "boolean",
-                example => "1",
-                description => "require SSL? strongly recommended",
-                safe => 0,
-                rebuild => 1,
-        },
-        plugin => {
-                description => "Unix user authentication",
-                safe => 0,
-                rebuild => 1,
-        },
-    }
-    
-    # Checks if a string matches a user's password, and returns true or false.
-    sub checkpassword ($$;$) {
-        my $user=shift;
-        my $password=shift;
-        my $field=shift || "password";
-    
-        # It's very important that the user not be allowed to log in with
-        # an empty password!
-        if (! length $password) {
-                return 0;
-        }
-    
-        my $ret=0;
-        if (! exists $config{unixauth_type}) {
-                # admin needs to carefully think over his configuration
-                return 0;
-        }
-        elsif ($config{unixauth_type} eq "checkpassword") {
-                open UNIXAUTH, "|$config{unixauth_command} true 3<&0" or die("Could not run $config{unixauth_type}");
-                print UNIXAUTH "$user\0$password\0Y123456\0";
-                close UNIXAUTH;
-                $ret=!($?>>8);
-        }
-        elsif ($config{unixauth_type} eq "pwauth") {
-                open UNIXAUTH, "|$config{unixauth_command}" or die("Could not run $config{unixauth_type}");
-                print UNIXAUTH "$user\n$password\n";
-                close UNIXAUTH;
-                $ret=!($?>>8);
-        }
-        else {
-                # no such authentication type
-                return 0;
-        }
-    
-        if ($ret) {
-            my $userinfo=IkiWiki::userinfo_retrieve();
-            if (! length $user || ! defined $userinfo ||
-                ! exists $userinfo->{$user} || ! ref $userinfo->{$user}) {
-                    IkiWiki::userinfo_setall($user, {
-                        'email' => '',
-                        'regdate' => time,
-                    });
-            }
-        }
-    
-        return $ret;
-    }
-    
-    sub formbuilder_setup (@) {
-        my %params=@_;
-    
-        my $form=$params{form};
-        my $session=$params{session};
-        my $cgi=$params{cgi};
-    
-        # if not under SSL, die before even showing a login form,
-        # unless the admin explicitly says it's fine
-        if (! exists $config{unixauth_requiressl}) {
-                $config{unixauth_requiressl} = 1;
-        }
-        if ($config{unixauth_requiressl}) {
-            if ((! $config{sslcookie}) || (! exists $ENV{'HTTPS'})) {
-                die("SSL required to login. Contact your administrator.<br>");
-            }
-        }
-    
-        if ($form->title eq "signin") {
-                $form->field(name => "name", required => 0);
-                $form->field(name => "password", type => "password", required => 0);
-                
-                if ($form->submitted) {
-                        my $submittype=$form->submitted;
-                        # Set required fields based on how form was submitted.
-                        my %required=(
-                                "Login" => [qw(name password)],
-                        );
-                        foreach my $opt (@{$required{$submittype}}) {
-                                $form->field(name => $opt, required => 1);
-                        }
-        
-                        # Validate password against name for Login.
-                        if ($submittype eq "Login") {
-                                $form->field(
-                                        name => "password",
-                                        validate => sub {
-                                                checkpassword($form->field("name"), shift);
-                                        },
-                                );
-                        }
-                        
-                        # XXX is this reachable? looks like no
-                        elsif ($submittype eq "Login") {
-                                $form->field( 
-                                        name => "name",
-                                        validate => sub {
-                                                my $name=shift;
-                                                length $name &&
-                                                IkiWiki::userinfo_get($name, "regdate");
-                                        },
-                                );
-                        }
-                }
-                else {
-                        # First time settings.
-                        $form->field(name => "name");
-                        if ($session->param("name")) {
-                                $form->field(name => "name", value => $session->param("name"));
-                        }
-                }
-        }
-        elsif ($form->title eq "preferences") {
-                $form->field(name => "name", disabled => 1, 
-                        value => $session->param("name"), force => 1,
-                        fieldset => "login");
-                $form->field(name => "password", disabled => 1, type => "password",
-                        fieldset => "login"),
-        }
-    }
-    
-    sub formbuilder (@) {
-        my %params=@_;
-    
-        my $form=$params{form};
-        my $session=$params{session};
-        my $cgi=$params{cgi};
-        my $buttons=$params{buttons};
-    
-        if ($form->title eq "signin") {
-                if ($form->submitted && $form->validate) {
-                        if ($form->submitted eq 'Login') {
-                                $session->param("name", $form->field("name"));
-                                IkiWiki::cgi_postsignin($cgi, $session);
-                        }
-                }
-        }
-        elsif ($form->title eq "preferences") {
-                if ($form->submitted eq "Save Preferences" && $form->validate) {
-                        my $user_name=$form->field('name');
-                }
-        }
-    }
-    
-    sub sessioncgi ($$) {
-        my $q=shift;
-        my $session=shift;
-    }
-    
-    1
-
-"""]]
-- 
cgit v1.2.3


From 0721363a7adfc0f993a485a45222482a8a854a19 Mon Sep 17 00:00:00 2001
From: Amitai Schlair <schmonz@magnetic-babysitter.(none)>
Date: Sun, 30 Aug 2009 01:26:57 -0400
Subject: bug fixed, to-dos done

---
 doc/plugins/contrib/cvs.mdwn            | 2 --
 doc/plugins/contrib/cvs/discussion.mdwn | 4 ++++
 2 files changed, 4 insertions(+), 2 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs.mdwn b/doc/plugins/contrib/cvs.mdwn
index 6b600eef7..afef98c74 100644
--- a/doc/plugins/contrib/cvs.mdwn
+++ b/doc/plugins/contrib/cvs.mdwn
@@ -27,7 +27,5 @@ Consider creating `$HOME/.cvsrc` if you don't have one already; the plugin doesn
 
 ### To do
 * Add automated tests. (Blindly adding svn-like tests to `t/file_pruned.t` doesn't do the trick.)
-* If the argument to `cvs add` smells like a binary file, `cvs add -kb` it (for [[plugins/attachment]] support).
-* Don't slurp the entire `cvsps` output into memory (!).
 * Instead of resource-intensively scraping changesets with `cvsps`, have `ikiwiki-makerepo` set up NetBSD-like `log_accum` and `commit_prep` scripts that coalesce and keep records of commits. `cvsps` can be used as a fallback for repositories without such records.
 * Perhaps prevent web edits from attempting to create `.../CVS/foo.mdwn` (and `.../cvs/foo.mdwn` on case-insensitive filesystems); thanks to the CVS metadata directory, the attempt will fail anyway (and much more confusingly) if we don't.
diff --git a/doc/plugins/contrib/cvs/discussion.mdwn b/doc/plugins/contrib/cvs/discussion.mdwn
index e1fa6e428..e142452d0 100644
--- a/doc/plugins/contrib/cvs/discussion.mdwn
+++ b/doc/plugins/contrib/cvs/discussion.mdwn
@@ -52,6 +52,10 @@ the "cvs add <directory>" call and avoid doing anything in that case?
 >>>>>> I don't see how there could possibly be a difference between
 >>>>>> ikiwiki's C wrapper and your shell wrapper wrapper here. --[[Joey]]
 
+>>>>>>> I was comparing strings overly precisely. Fixed on my branch.
+>>>>>>> I've also knocked off the two most pressing to-do items. I
+>>>>>>> think the plugin's ready for prime time. --[[schmonz]]
+
 > Thing 2 I'm less sure of. (I'd like to see the web UI return
 > immediately on save anyway, to a temporary "rebuilding, please wait
 > if you feel like knowing when it's done" page, but this problem
-- 
cgit v1.2.3


From 558873131f10c52ecbc0b97544db6556964f172a Mon Sep 17 00:00:00 2001
From: Amitai Schlair <schmonz@magnetic-babysitter.(none)>
Date: Sun, 30 Aug 2009 01:31:15 -0400
Subject: also need File::ReadBackwards now

---
 doc/plugins/contrib/cvs.mdwn | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs.mdwn b/doc/plugins/contrib/cvs.mdwn
index afef98c74..4cd7dcc7d 100644
--- a/doc/plugins/contrib/cvs.mdwn
+++ b/doc/plugins/contrib/cvs.mdwn
@@ -5,7 +5,9 @@
 This plugin allows ikiwiki to use [[!wikipedia desc="CVS" Concurrent Versions System]] as an [[rcs]].
 
 ### Usage
-7. Install [cvsps](http://www.cobite.com/cvsps/), [[!cpan IPC::Cmd]], [[!cpan String::ShellQuote]], and [cvsweb](http://www.freebsd.org/projects/cvsweb.html) or the like.
+7. Install [cvsps](http://www.cobite.com/cvsps/), [[!cpan IPC::Cmd]],
+[[!cpan String::ShellQuote]], [[!cpan File::ReadBackwards]], and
+[cvsweb](http://www.freebsd.org/projects/cvsweb.html) or the like.
 7. Adjust CVS-related parameters in your setup file.
 
 Consider creating `$HOME/.cvsrc` if you don't have one already; the plugin doesn't need it, but you yourself might. Here's a good general-purpose one:
-- 
cgit v1.2.3


From 58cef9c3cf6da1b614c0a24ebef15a0d8ecea335 Mon Sep 17 00:00:00 2001
From: Amitai Schlair <schmonz@magnetic-babysitter.(none)>
Date: Sun, 30 Aug 2009 02:35:38 -0400
Subject: describe the wrapper change

---
 doc/plugins/contrib/cvs.mdwn | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs.mdwn b/doc/plugins/contrib/cvs.mdwn
index 4cd7dcc7d..1c43fb272 100644
--- a/doc/plugins/contrib/cvs.mdwn
+++ b/doc/plugins/contrib/cvs.mdwn
@@ -20,7 +20,11 @@ Consider creating `$HOME/.cvsrc` if you don't have one already; the plugin doesn
 
 ### Implementation details
 * `cvs.pm` started life as a copy of [[3.14159|news/version_3.14159]]'s `svn.pm`.
-* `IkiWiki.pm:wiki_file_prune_regexps` avoids copying CVS metadata into `$DESTDIR`.
+* `IkiWiki.pm:wiki_file_prune_regexps` avoids copying CVS metadata
+into `$DESTDIR`.
+* `IkiWiki/Wrapper.pm` avoids calling ikiwiki from post-commit if it's a
+directory being `cvs add`ed (this check is only compiled into the wrapper
+iff the configured VCS is "cvs").
 * [[ikiwiki-makerepo]]:
  * creates a repository,
  * imports `$SRCDIR` into top-level module `ikiwiki` (vendor tag IKIWIKI, release tag PRE_CVS),
-- 
cgit v1.2.3


From 6fe3c6bb5f34dca6fc23ba910a9d9a583da9f4c9 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@gnu.kitenet.net>
Date: Wed, 2 Sep 2009 16:10:57 -0400
Subject: ruther review

---
 doc/plugins/contrib/cvs/discussion.mdwn | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs/discussion.mdwn b/doc/plugins/contrib/cvs/discussion.mdwn
index e142452d0..b5f03ac6f 100644
--- a/doc/plugins/contrib/cvs/discussion.mdwn
+++ b/doc/plugins/contrib/cvs/discussion.mdwn
@@ -93,3 +93,32 @@ the "cvs add <directory>" call and avoid doing anything in that case?
 >>> if a configured post-commit hook is missing, and it seems fine,
 >>> probably also thanks to IPC::Cmd.
 >>> --[[schmonz]]
+
+----
+
+
+Further review.. --[[Joey]] 
+
+I don't understand what `cvs_shquote_commit` is
+trying to do with the test message, but it seems
+highly likely to be insecure; I never trust anything 
+that relies on safely quoting user input passed to the shell. 
+
+(As an aside, `shell_quote` can die on certian inputs.)
+
+Seems to me that, if `IPC::Cmd` exposes input to the shell
+(which I have not verified but its docs don't specify; a bad sign)
+you chose the wrong tool and ended up doing down the wrong
+route, dragging in shell quoting problems and fixes. Since you
+chose to use `IPC::Cmd`	just because you wanted to shut
+up CVS stderr, my suggestion would be to use plain `system`
+to run the command, with stderr temporarily sent to /dev/null:
+
+	open(my $savederr, ">&STDERR");
+	open(STDERR, ">", "/dev/null");
+	my $ret=system("cvs", "-Q", @_);
+	open(STDERR, ">$savederr");
+
+`cvs_runcvs` should not take an array reference. It's
+usual for this type of function to take a list of parameters
+to pass to the command.
-- 
cgit v1.2.3


From f582457ea04a6ce66a2c54ec0731e2569aa30d3f Mon Sep 17 00:00:00 2001
From: bremner <bremner@web>
Date: Thu, 3 Sep 2009 08:18:27 -0400
Subject:

---
 doc/plugins/contrib/mailbox/discussion.mdwn | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/mailbox/discussion.mdwn b/doc/plugins/contrib/mailbox/discussion.mdwn
index 00fb0c05f..9520fdd70 100644
--- a/doc/plugins/contrib/mailbox/discussion.mdwn
+++ b/doc/plugins/contrib/mailbox/discussion.mdwn
@@ -3,3 +3,6 @@
 For some reason, `git fetch` from http://pivot.cs.unb.ca/git/ikimailbox.git/ didn't work very smoothly for me: it hung, and I had to restart it 3 times before the download was complete.
 
 I'm writing this just to let you know that there might be some problems with such connections to your http-server. --Ivan Z.
+> I can't replicate this (two months later!)
+> I can suggest trying the git:// url for download if you can.
+> Also, if you really want to get my attention, send me email   [[DavidBremner]]
-- 
cgit v1.2.3


From 127ed4d6c7a7d2cc518102757b7b4be49d20fce8 Mon Sep 17 00:00:00 2001
From: Amitai Schlair <schmonz@magnetic-babysitter.(none)>
Date: Fri, 4 Sep 2009 15:08:48 -0500
Subject: no more IPC::Cmd or String::ShellQuote, huzzah

---
 doc/plugins/contrib/cvs.mdwn            | 4 ++--
 doc/plugins/contrib/cvs/discussion.mdwn | 3 +++
 2 files changed, 5 insertions(+), 2 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs.mdwn b/doc/plugins/contrib/cvs.mdwn
index 1c43fb272..fcf5b936f 100644
--- a/doc/plugins/contrib/cvs.mdwn
+++ b/doc/plugins/contrib/cvs.mdwn
@@ -5,8 +5,8 @@
 This plugin allows ikiwiki to use [[!wikipedia desc="CVS" Concurrent Versions System]] as an [[rcs]].
 
 ### Usage
-7. Install [cvsps](http://www.cobite.com/cvsps/), [[!cpan IPC::Cmd]],
-[[!cpan String::ShellQuote]], [[!cpan File::ReadBackwards]], and
+7. Install [cvsps](http://www.cobite.com/cvsps/), [[!cpan
+File::ReadBackwards]], and
 [cvsweb](http://www.freebsd.org/projects/cvsweb.html) or the like.
 7. Adjust CVS-related parameters in your setup file.
 
diff --git a/doc/plugins/contrib/cvs/discussion.mdwn b/doc/plugins/contrib/cvs/discussion.mdwn
index b5f03ac6f..1f0ce0102 100644
--- a/doc/plugins/contrib/cvs/discussion.mdwn
+++ b/doc/plugins/contrib/cvs/discussion.mdwn
@@ -122,3 +122,6 @@ to run the command, with stderr temporarily sent to /dev/null:
 `cvs_runcvs` should not take an array reference. It's
 usual for this type of function to take a list of parameters
 to pass to the command.
+
+> Thanks for reading carefully. I've tested your suggestions and
+> applied them on my branch. --[[schmonz]]
-- 
cgit v1.2.3


From 1b4c3fb551754cc70abd7a18871a79d79ac3cb5b Mon Sep 17 00:00:00 2001
From: Amitai Schlair <schmonz@magnetic-babysitter.Ativa>
Date: Wed, 9 Sep 2009 22:36:23 -0400
Subject: note refactored wrapper tweakulation

---
 doc/plugins/contrib/cvs/discussion.mdwn | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs/discussion.mdwn b/doc/plugins/contrib/cvs/discussion.mdwn
index 1f0ce0102..155a2289d 100644
--- a/doc/plugins/contrib/cvs/discussion.mdwn
+++ b/doc/plugins/contrib/cvs/discussion.mdwn
@@ -125,3 +125,19 @@ to pass to the command.
 
 > Thanks for reading carefully. I've tested your suggestions and
 > applied them on my branch. --[[schmonz]]
+
+----
+
+I've abstracted out CVS's involvement in the wrapper, adding a new
+"wrapperargcheck" hook to examine `argc/argv` and return success or
+failure (failure causes the wrapper to terminate) and implementing
+this hook in the plugin. In the non-CVS case, the check immediately
+returns success, so the added overhead is just a function call.
+
+Given how rarely anything should need to reach in and modify the
+wrapper -- I'd go so far as to say we shouldn't make it too easy
+-- I don't think it's worth the effort to try and design a more
+general-purpose way to do so. If and when some other problem thinks
+it wants to be solved by a new wrapper hook, it's easy enough to add
+one. Until then, I'd say it's more important to keep the wrapper as
+short and clear as possible. --[[schmonz]]
-- 
cgit v1.2.3


From b7415543c1ee1ee6ee0404cf781e89043de26fb7 Mon Sep 17 00:00:00 2001
From: Amitai Schlair <schmonz@magnetic-babysitter.(none)>
Date: Wed, 9 Sep 2009 22:42:47 -0400
Subject: describe current state of wrapper modification

---
 doc/plugins/contrib/cvs.mdwn | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs.mdwn b/doc/plugins/contrib/cvs.mdwn
index fcf5b936f..3d72255fe 100644
--- a/doc/plugins/contrib/cvs.mdwn
+++ b/doc/plugins/contrib/cvs.mdwn
@@ -22,9 +22,9 @@ Consider creating `$HOME/.cvsrc` if you don't have one already; the plugin doesn
 * `cvs.pm` started life as a copy of [[3.14159|news/version_3.14159]]'s `svn.pm`.
 * `IkiWiki.pm:wiki_file_prune_regexps` avoids copying CVS metadata
 into `$DESTDIR`.
-* `IkiWiki/Wrapper.pm` avoids calling ikiwiki from post-commit if it's a
-directory being `cvs add`ed (this check is only compiled into the wrapper
-iff the configured VCS is "cvs").
+* `IkiWiki/Wrapper.pm` provides a new "wrapperargcheck" hook, which
+the plugin implements to avoid calling ikiwiki from post-commit
+(and locking against itself) if it's a directory being `cvs add`ed.
 * [[ikiwiki-makerepo]]:
  * creates a repository,
  * imports `$SRCDIR` into top-level module `ikiwiki` (vendor tag IKIWIKI, release tag PRE_CVS),
-- 
cgit v1.2.3


From 689106ad3a24850543c7855b8531a1bf8dcfdb63 Mon Sep 17 00:00:00 2001
From: Amitai Schlair <schmonz@magnetic-babysitter.(none)>
Date: Wed, 9 Sep 2009 23:17:15 -0400
Subject: automated tests added (and they highlight that the plugin should
 probably restore the caller's working directory)

---
 doc/plugins/contrib/cvs.mdwn | 1 -
 1 file changed, 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs.mdwn b/doc/plugins/contrib/cvs.mdwn
index 3d72255fe..947fa7268 100644
--- a/doc/plugins/contrib/cvs.mdwn
+++ b/doc/plugins/contrib/cvs.mdwn
@@ -32,6 +32,5 @@ the plugin implements to avoid calling ikiwiki from post-commit
 * CVS multi-directory commits happen separately; the post-commit hook sees only the first directory's changes in time for [[recentchanges|plugins/recentchanges]]. The next run of `ikiwiki --setup` will correctly re-render such a recentchanges entry. It should be possible to solve this problem with NetBSD's `commit_prep` and `log_accum` scripts (see below).
 
 ### To do
-* Add automated tests. (Blindly adding svn-like tests to `t/file_pruned.t` doesn't do the trick.)
 * Instead of resource-intensively scraping changesets with `cvsps`, have `ikiwiki-makerepo` set up NetBSD-like `log_accum` and `commit_prep` scripts that coalesce and keep records of commits. `cvsps` can be used as a fallback for repositories without such records.
 * Perhaps prevent web edits from attempting to create `.../CVS/foo.mdwn` (and `.../cvs/foo.mdwn` on case-insensitive filesystems); thanks to the CVS metadata directory, the attempt will fail anyway (and much more confusingly) if we don't.
-- 
cgit v1.2.3


From d2b57ae20fa1800d142adad5b3e43dddb97e9466 Mon Sep 17 00:00:00 2001
From: Amitai Schlair <schmonz@magnetic-babysitter.(none)>
Date: Thu, 10 Sep 2009 00:59:05 -0400
Subject: File::chdir is needed now

---
 doc/plugins/contrib/cvs.mdwn | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs.mdwn b/doc/plugins/contrib/cvs.mdwn
index 947fa7268..d45992300 100644
--- a/doc/plugins/contrib/cvs.mdwn
+++ b/doc/plugins/contrib/cvs.mdwn
@@ -5,8 +5,8 @@
 This plugin allows ikiwiki to use [[!wikipedia desc="CVS" Concurrent Versions System]] as an [[rcs]].
 
 ### Usage
-7. Install [cvsps](http://www.cobite.com/cvsps/), [[!cpan
-File::ReadBackwards]], and
+7. Install [[!cpan File::chdir]], [[!cpan File::ReadBackwards]],
+[cvsps](http://www.cobite.com/cvsps/), and
 [cvsweb](http://www.freebsd.org/projects/cvsweb.html) or the like.
 7. Adjust CVS-related parameters in your setup file.
 
-- 
cgit v1.2.3


From 525d4cd037b1da19f4d54cf113212cbe452be417 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@gnu.kitenet.net>
Date: Thu, 10 Sep 2009 14:06:30 -0400
Subject: new hook

---
 doc/plugins/contrib/cvs/discussion.mdwn | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs/discussion.mdwn b/doc/plugins/contrib/cvs/discussion.mdwn
index 155a2289d..ace455d06 100644
--- a/doc/plugins/contrib/cvs/discussion.mdwn
+++ b/doc/plugins/contrib/cvs/discussion.mdwn
@@ -141,3 +141,7 @@ general-purpose way to do so. If and when some other problem thinks
 it wants to be solved by a new wrapper hook, it's easy enough to add
 one. Until then, I'd say it's more important to keep the wrapper as
 short and clear as possible. --[[schmonz]]
+
+> I've committed a slightly different hook, which should be general enough
+> that `IkiWiki::Receive` can also use it, so please adapt your code to
+> that. --[[Joey]]
-- 
cgit v1.2.3


From 5ee980d77a614865747101615a6a795bec6f272f Mon Sep 17 00:00:00 2001
From: Amitai Schlair <schmonz@magnetic-babysitter.(none)>
Date: Thu, 10 Sep 2009 15:17:28 -0400
Subject: catch up to genwrapper

---
 doc/plugins/contrib/cvs.mdwn            | 3 ---
 doc/plugins/contrib/cvs/discussion.mdwn | 2 ++
 2 files changed, 2 insertions(+), 3 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs.mdwn b/doc/plugins/contrib/cvs.mdwn
index d45992300..b75929139 100644
--- a/doc/plugins/contrib/cvs.mdwn
+++ b/doc/plugins/contrib/cvs.mdwn
@@ -22,9 +22,6 @@ Consider creating `$HOME/.cvsrc` if you don't have one already; the plugin doesn
 * `cvs.pm` started life as a copy of [[3.14159|news/version_3.14159]]'s `svn.pm`.
 * `IkiWiki.pm:wiki_file_prune_regexps` avoids copying CVS metadata
 into `$DESTDIR`.
-* `IkiWiki/Wrapper.pm` provides a new "wrapperargcheck" hook, which
-the plugin implements to avoid calling ikiwiki from post-commit
-(and locking against itself) if it's a directory being `cvs add`ed.
 * [[ikiwiki-makerepo]]:
  * creates a repository,
  * imports `$SRCDIR` into top-level module `ikiwiki` (vendor tag IKIWIKI, release tag PRE_CVS),
diff --git a/doc/plugins/contrib/cvs/discussion.mdwn b/doc/plugins/contrib/cvs/discussion.mdwn
index ace455d06..645b2388b 100644
--- a/doc/plugins/contrib/cvs/discussion.mdwn
+++ b/doc/plugins/contrib/cvs/discussion.mdwn
@@ -145,3 +145,5 @@ short and clear as possible. --[[schmonz]]
 > I've committed a slightly different hook, which should be general enough
 > that `IkiWiki::Receive` can also use it, so please adapt your code to
 > that. --[[Joey]]
+
+>> Done. --[[schmonz]].
-- 
cgit v1.2.3


From e5d9d3cc52598c68fc91903a5ca5fd43c7d1cf21 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@gnu.kitenet.net>
Date: Thu, 10 Sep 2009 16:31:58 -0400
Subject: add rcs/cvs

---
 doc/plugins/contrib/cvs.mdwn            |  33 -------
 doc/plugins/contrib/cvs/discussion.mdwn | 149 --------------------------------
 doc/rcs/cvs.mdwn                        |  27 ++++++
 doc/rcs/cvs/discussion.mdwn             | 149 ++++++++++++++++++++++++++++++++
 doc/rcs/details.mdwn                    |   2 +
 5 files changed, 178 insertions(+), 182 deletions(-)
 delete mode 100644 doc/plugins/contrib/cvs.mdwn
 delete mode 100644 doc/plugins/contrib/cvs/discussion.mdwn
 create mode 100644 doc/rcs/cvs.mdwn
 create mode 100644 doc/rcs/cvs/discussion.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/cvs.mdwn b/doc/plugins/contrib/cvs.mdwn
deleted file mode 100644
index b75929139..000000000
--- a/doc/plugins/contrib/cvs.mdwn
+++ /dev/null
@@ -1,33 +0,0 @@
-[[!template id=plugin name=cvs core=0 author="[[schmonz]]"]]
-
-[[!template id=gitbranch branch=schmonz author="[[schmonz]]"]]
-
-This plugin allows ikiwiki to use [[!wikipedia desc="CVS" Concurrent Versions System]] as an [[rcs]].
-
-### Usage
-7. Install [[!cpan File::chdir]], [[!cpan File::ReadBackwards]],
-[cvsps](http://www.cobite.com/cvsps/), and
-[cvsweb](http://www.freebsd.org/projects/cvsweb.html) or the like.
-7. Adjust CVS-related parameters in your setup file.
-
-Consider creating `$HOME/.cvsrc` if you don't have one already; the plugin doesn't need it, but you yourself might. Here's a good general-purpose one:
-
-    cvs -q
-    checkout -P
-    update -dP
-    diff -u
-    rdiff -u
-
-### Implementation details
-* `cvs.pm` started life as a copy of [[3.14159|news/version_3.14159]]'s `svn.pm`.
-* `IkiWiki.pm:wiki_file_prune_regexps` avoids copying CVS metadata
-into `$DESTDIR`.
-* [[ikiwiki-makerepo]]:
- * creates a repository,
- * imports `$SRCDIR` into top-level module `ikiwiki` (vendor tag IKIWIKI, release tag PRE_CVS),
- * configures the post-commit hook in `CVSROOT/loginfo`.
-* CVS multi-directory commits happen separately; the post-commit hook sees only the first directory's changes in time for [[recentchanges|plugins/recentchanges]]. The next run of `ikiwiki --setup` will correctly re-render such a recentchanges entry. It should be possible to solve this problem with NetBSD's `commit_prep` and `log_accum` scripts (see below).
-
-### To do
-* Instead of resource-intensively scraping changesets with `cvsps`, have `ikiwiki-makerepo` set up NetBSD-like `log_accum` and `commit_prep` scripts that coalesce and keep records of commits. `cvsps` can be used as a fallback for repositories without such records.
-* Perhaps prevent web edits from attempting to create `.../CVS/foo.mdwn` (and `.../cvs/foo.mdwn` on case-insensitive filesystems); thanks to the CVS metadata directory, the attempt will fail anyway (and much more confusingly) if we don't.
diff --git a/doc/plugins/contrib/cvs/discussion.mdwn b/doc/plugins/contrib/cvs/discussion.mdwn
deleted file mode 100644
index 645b2388b..000000000
--- a/doc/plugins/contrib/cvs/discussion.mdwn
+++ /dev/null
@@ -1,149 +0,0 @@
-I've started reviewing this, and the main thing I don't like is the
-post-commit wrapper wrapper that ikiwiki-makerepo is patched to set up.
-That just seems unnecessarily complicated. Why can't ikiwiki itself detect
-the "cvs add <directory>" call and avoid doing anything in that case?
---[[Joey]] 
-
-> The wrapper wrapper does three things:
->
-> 7. It ignores `cvs add <directory>`, since this is a weird CVS
-> behavior that ikiwiki gets confused by and doesn't need to act on.
-> 7. It prevents `cvs` locking against itself: `cvs commit` takes a
-> write lock and runs the post-commit hook, which runs `cvs update`,
-> which wants a read lock and sleeps forever -- unless the post-commit
-> hook runs in the background so the commit can "finish".
-> 7. It fails silently if the ikiwiki post-commit hook is missing.
-> CVS doesn't have any magic post-commit filenames, so hooks have to
-> be configured explicitly. I don't think a commit will actually fail
-> if a configured post-commit hook is missing (though I can't test
-> this at the moment).
->
-> Thing 1 can probably be handled within ikiwiki, if that seems less
-> gross to you.
-
->> It seems like it might be. You can use a `getopt` hook to check
->> `@ARGV` to see how it was called. --[[Joey]] 
-
->>> This does the trick iff the post-commit wrapper passes its args
->>> along. Committed on my branch. This seems potentially dangerous,
->>> since the args passed to ikiwiki are influenced by web commits.
->>> I don't see an exploit, but for paranoia's sake, maybe the wrapper
->>> should only be built with execv() if the cvs plugin is loaded?
->>> --[[schmonz]]
-
->>>> Hadn't considered that. While in wrapper mode the normal getopt is not
->>>> done, plugin getopt still runs, and so any unsafe options that 
->>>> other plugins support could be a problem if another user runs
->>>> the setuid wrapper and passes those options through. --[[Joey]]
-
->>>>> I've tried compiling the argument check into the wrapper as
->>>>> the first thing main() does, and was surprised to find that
->>>>> this doesn't prevent the `cvs add <dir>` deadlock in a web
->>>>> commit. I was convinced this'd be a reasonable solution,
->>>>> especially if conditionalized on the cvs plugin being loaded,
->>>>> but it doesn't work. And I stuck debug printfs at the beginning
->>>>> of all the rcs_foo() subs, and whatever `cvs add <dir>` is
->>>>> doing to ikiwiki isn't visible to my plugin, because none of
->>>>> those subs are getting called. Nuts. Can you think of anything
->>>>> else that might solve the problem, or should I go back to
->>>>> generating a minimal wrapper wrapper that checks for just
->>>>> this one thing? --[[schmonz]]
-
->>>>>> I don't see how there could possibly be a difference between
->>>>>> ikiwiki's C wrapper and your shell wrapper wrapper here. --[[Joey]]
-
->>>>>>> I was comparing strings overly precisely. Fixed on my branch.
->>>>>>> I've also knocked off the two most pressing to-do items. I
->>>>>>> think the plugin's ready for prime time. --[[schmonz]]
-
-> Thing 2 I'm less sure of. (I'd like to see the web UI return
-> immediately on save anyway, to a temporary "rebuilding, please wait
-> if you feel like knowing when it's done" page, but this problem
-> with CVS happens with any kind of commit, and could conceivably
-> happen with some other VCS.)
-
->> None of the other VCSes let a write lock block a read lock, apparently.
->> 
->> Anyway, re the backgrounding, when committing via the web, the
->> post-commit hook doesn't run anyway; the rendering is done via the
->> ikiwiki CGI. It would certianly be nice if it popped up a quick "working"
->> page and replaced it with the updated page when done, but that's
->> unrelated;  the post-commit
->> hook only does rendering when committing using the VCS directly. The
->> backgrounding you do actually seems safe enough -- but tacking
->> on a " &" to the ikiwiki wrapper call doesn't need a wrapper script,
->> does it? --[[Joey]]
-
->>> Nope, it works fine to append it to the `CVSROOT/loginfo` line.
->>> Fixed on my branch. --[[schmonz]]
-
-> Thing 3 I think I did in order to squelch the error messages that
-> were bollixing up the CGI. It was easy to do this in the wrapper
-> wrapper, but if that's going away, it can be done just as easily
-> with output redirection in `CVSROOT/loginfo`.
->
-> --[[schmonz]]
-
->> If the error messages screw up the CGI they must go to stdout.
->> I thought we had stderr even in the the CVS dark ages. ;-) --[[Joey]] 
-
->>> Some messages go to stderr, but definitely not all. That's why
->>> I wound up reaching for IPC::Cmd, to execute the command line
->>> safely while shutting CVS up. Anyway, I've tested what happens
->>> if a configured post-commit hook is missing, and it seems fine,
->>> probably also thanks to IPC::Cmd.
->>> --[[schmonz]]
-
-----
-
-
-Further review.. --[[Joey]] 
-
-I don't understand what `cvs_shquote_commit` is
-trying to do with the test message, but it seems
-highly likely to be insecure; I never trust anything 
-that relies on safely quoting user input passed to the shell. 
-
-(As an aside, `shell_quote` can die on certian inputs.)
-
-Seems to me that, if `IPC::Cmd` exposes input to the shell
-(which I have not verified but its docs don't specify; a bad sign)
-you chose the wrong tool and ended up doing down the wrong
-route, dragging in shell quoting problems and fixes. Since you
-chose to use `IPC::Cmd`	just because you wanted to shut
-up CVS stderr, my suggestion would be to use plain `system`
-to run the command, with stderr temporarily sent to /dev/null:
-
-	open(my $savederr, ">&STDERR");
-	open(STDERR, ">", "/dev/null");
-	my $ret=system("cvs", "-Q", @_);
-	open(STDERR, ">$savederr");
-
-`cvs_runcvs` should not take an array reference. It's
-usual for this type of function to take a list of parameters
-to pass to the command.
-
-> Thanks for reading carefully. I've tested your suggestions and
-> applied them on my branch. --[[schmonz]]
-
-----
-
-I've abstracted out CVS's involvement in the wrapper, adding a new
-"wrapperargcheck" hook to examine `argc/argv` and return success or
-failure (failure causes the wrapper to terminate) and implementing
-this hook in the plugin. In the non-CVS case, the check immediately
-returns success, so the added overhead is just a function call.
-
-Given how rarely anything should need to reach in and modify the
-wrapper -- I'd go so far as to say we shouldn't make it too easy
--- I don't think it's worth the effort to try and design a more
-general-purpose way to do so. If and when some other problem thinks
-it wants to be solved by a new wrapper hook, it's easy enough to add
-one. Until then, I'd say it's more important to keep the wrapper as
-short and clear as possible. --[[schmonz]]
-
-> I've committed a slightly different hook, which should be general enough
-> that `IkiWiki::Receive` can also use it, so please adapt your code to
-> that. --[[Joey]]
-
->> Done. --[[schmonz]].
diff --git a/doc/rcs/cvs.mdwn b/doc/rcs/cvs.mdwn
new file mode 100644
index 000000000..f0bd0f6f0
--- /dev/null
+++ b/doc/rcs/cvs.mdwn
@@ -0,0 +1,27 @@
+If you really need to, you can use [[!wikipedia desc="CVS" Concurrent Versions System]]
+with ikiwiki.
+
+### Usage
+7. Install [[!cpan File::chdir]], [[!cpan File::ReadBackwards]],
+[cvsps](http://www.cobite.com/cvsps/), and
+[cvsweb](http://www.freebsd.org/projects/cvsweb.html) or the like.
+7. Adjust CVS-related parameters in your setup file.
+
+Consider creating `$HOME/.cvsrc` if you don't have one already; the plugin doesn't need it, but you yourself might. Here's a good general-purpose one:
+
+    cvs -q
+    checkout -P
+    update -dP
+    diff -u
+    rdiff -u
+
+### Implementation details
+* [[ikiwiki-makerepo]]:
+ * creates a repository,
+ * imports `$SRCDIR` into top-level module `ikiwiki` (vendor tag IKIWIKI, release tag PRE_CVS),
+ * configures the post-commit hook in `CVSROOT/loginfo`.
+* CVS multi-directory commits happen separately; the post-commit hook sees only the first directory's changes in time for [[recentchanges|plugins/recentchanges]]. The next run of `ikiwiki --setup` will correctly re-render such a recentchanges entry. It should be possible to solve this problem with NetBSD's `commit_prep` and `log_accum` scripts (see below).
+
+### To do
+* Instead of resource-intensively scraping changesets with `cvsps`, have `ikiwiki-makerepo` set up NetBSD-like `log_accum` and `commit_prep` scripts that coalesce and keep records of commits. `cvsps` can be used as a fallback for repositories without such records.
+* Perhaps prevent web edits from attempting to create `.../CVS/foo.mdwn` (and `.../cvs/foo.mdwn` on case-insensitive filesystems); thanks to the CVS metadata directory, the attempt will fail anyway (and much more confusingly) if we don't.
diff --git a/doc/rcs/cvs/discussion.mdwn b/doc/rcs/cvs/discussion.mdwn
new file mode 100644
index 000000000..645b2388b
--- /dev/null
+++ b/doc/rcs/cvs/discussion.mdwn
@@ -0,0 +1,149 @@
+I've started reviewing this, and the main thing I don't like is the
+post-commit wrapper wrapper that ikiwiki-makerepo is patched to set up.
+That just seems unnecessarily complicated. Why can't ikiwiki itself detect
+the "cvs add <directory>" call and avoid doing anything in that case?
+--[[Joey]] 
+
+> The wrapper wrapper does three things:
+>
+> 7. It ignores `cvs add <directory>`, since this is a weird CVS
+> behavior that ikiwiki gets confused by and doesn't need to act on.
+> 7. It prevents `cvs` locking against itself: `cvs commit` takes a
+> write lock and runs the post-commit hook, which runs `cvs update`,
+> which wants a read lock and sleeps forever -- unless the post-commit
+> hook runs in the background so the commit can "finish".
+> 7. It fails silently if the ikiwiki post-commit hook is missing.
+> CVS doesn't have any magic post-commit filenames, so hooks have to
+> be configured explicitly. I don't think a commit will actually fail
+> if a configured post-commit hook is missing (though I can't test
+> this at the moment).
+>
+> Thing 1 can probably be handled within ikiwiki, if that seems less
+> gross to you.
+
+>> It seems like it might be. You can use a `getopt` hook to check
+>> `@ARGV` to see how it was called. --[[Joey]] 
+
+>>> This does the trick iff the post-commit wrapper passes its args
+>>> along. Committed on my branch. This seems potentially dangerous,
+>>> since the args passed to ikiwiki are influenced by web commits.
+>>> I don't see an exploit, but for paranoia's sake, maybe the wrapper
+>>> should only be built with execv() if the cvs plugin is loaded?
+>>> --[[schmonz]]
+
+>>>> Hadn't considered that. While in wrapper mode the normal getopt is not
+>>>> done, plugin getopt still runs, and so any unsafe options that 
+>>>> other plugins support could be a problem if another user runs
+>>>> the setuid wrapper and passes those options through. --[[Joey]]
+
+>>>>> I've tried compiling the argument check into the wrapper as
+>>>>> the first thing main() does, and was surprised to find that
+>>>>> this doesn't prevent the `cvs add <dir>` deadlock in a web
+>>>>> commit. I was convinced this'd be a reasonable solution,
+>>>>> especially if conditionalized on the cvs plugin being loaded,
+>>>>> but it doesn't work. And I stuck debug printfs at the beginning
+>>>>> of all the rcs_foo() subs, and whatever `cvs add <dir>` is
+>>>>> doing to ikiwiki isn't visible to my plugin, because none of
+>>>>> those subs are getting called. Nuts. Can you think of anything
+>>>>> else that might solve the problem, or should I go back to
+>>>>> generating a minimal wrapper wrapper that checks for just
+>>>>> this one thing? --[[schmonz]]
+
+>>>>>> I don't see how there could possibly be a difference between
+>>>>>> ikiwiki's C wrapper and your shell wrapper wrapper here. --[[Joey]]
+
+>>>>>>> I was comparing strings overly precisely. Fixed on my branch.
+>>>>>>> I've also knocked off the two most pressing to-do items. I
+>>>>>>> think the plugin's ready for prime time. --[[schmonz]]
+
+> Thing 2 I'm less sure of. (I'd like to see the web UI return
+> immediately on save anyway, to a temporary "rebuilding, please wait
+> if you feel like knowing when it's done" page, but this problem
+> with CVS happens with any kind of commit, and could conceivably
+> happen with some other VCS.)
+
+>> None of the other VCSes let a write lock block a read lock, apparently.
+>> 
+>> Anyway, re the backgrounding, when committing via the web, the
+>> post-commit hook doesn't run anyway; the rendering is done via the
+>> ikiwiki CGI. It would certianly be nice if it popped up a quick "working"
+>> page and replaced it with the updated page when done, but that's
+>> unrelated;  the post-commit
+>> hook only does rendering when committing using the VCS directly. The
+>> backgrounding you do actually seems safe enough -- but tacking
+>> on a " &" to the ikiwiki wrapper call doesn't need a wrapper script,
+>> does it? --[[Joey]]
+
+>>> Nope, it works fine to append it to the `CVSROOT/loginfo` line.
+>>> Fixed on my branch. --[[schmonz]]
+
+> Thing 3 I think I did in order to squelch the error messages that
+> were bollixing up the CGI. It was easy to do this in the wrapper
+> wrapper, but if that's going away, it can be done just as easily
+> with output redirection in `CVSROOT/loginfo`.
+>
+> --[[schmonz]]
+
+>> If the error messages screw up the CGI they must go to stdout.
+>> I thought we had stderr even in the the CVS dark ages. ;-) --[[Joey]] 
+
+>>> Some messages go to stderr, but definitely not all. That's why
+>>> I wound up reaching for IPC::Cmd, to execute the command line
+>>> safely while shutting CVS up. Anyway, I've tested what happens
+>>> if a configured post-commit hook is missing, and it seems fine,
+>>> probably also thanks to IPC::Cmd.
+>>> --[[schmonz]]
+
+----
+
+
+Further review.. --[[Joey]] 
+
+I don't understand what `cvs_shquote_commit` is
+trying to do with the test message, but it seems
+highly likely to be insecure; I never trust anything 
+that relies on safely quoting user input passed to the shell. 
+
+(As an aside, `shell_quote` can die on certian inputs.)
+
+Seems to me that, if `IPC::Cmd` exposes input to the shell
+(which I have not verified but its docs don't specify; a bad sign)
+you chose the wrong tool and ended up doing down the wrong
+route, dragging in shell quoting problems and fixes. Since you
+chose to use `IPC::Cmd`	just because you wanted to shut
+up CVS stderr, my suggestion would be to use plain `system`
+to run the command, with stderr temporarily sent to /dev/null:
+
+	open(my $savederr, ">&STDERR");
+	open(STDERR, ">", "/dev/null");
+	my $ret=system("cvs", "-Q", @_);
+	open(STDERR, ">$savederr");
+
+`cvs_runcvs` should not take an array reference. It's
+usual for this type of function to take a list of parameters
+to pass to the command.
+
+> Thanks for reading carefully. I've tested your suggestions and
+> applied them on my branch. --[[schmonz]]
+
+----
+
+I've abstracted out CVS's involvement in the wrapper, adding a new
+"wrapperargcheck" hook to examine `argc/argv` and return success or
+failure (failure causes the wrapper to terminate) and implementing
+this hook in the plugin. In the non-CVS case, the check immediately
+returns success, so the added overhead is just a function call.
+
+Given how rarely anything should need to reach in and modify the
+wrapper -- I'd go so far as to say we shouldn't make it too easy
+-- I don't think it's worth the effort to try and design a more
+general-purpose way to do so. If and when some other problem thinks
+it wants to be solved by a new wrapper hook, it's easy enough to add
+one. Until then, I'd say it's more important to keep the wrapper as
+short and clear as possible. --[[schmonz]]
+
+> I've committed a slightly different hook, which should be general enough
+> that `IkiWiki::Receive` can also use it, so please adapt your code to
+> that. --[[Joey]]
+
+>> Done. --[[schmonz]].
diff --git a/doc/rcs/details.mdwn b/doc/rcs/details.mdwn
index 6492cf38c..013ddb745 100644
--- a/doc/rcs/details.mdwn
+++ b/doc/rcs/details.mdwn
@@ -288,3 +288,5 @@ user for cleanup.  This is less neat than it could be, in that a conflict marked
 revision gets committed to the repository.
 
 ## [[bzr]]
+
+## [[cvs]]
-- 
cgit v1.2.3


From 412a4dd62ade18f5e057ff3324321188245a542e Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@gnu.kitenet.net>
Date: Fri, 11 Sep 2009 14:44:32 -0400
Subject: review

---
 doc/plugins/contrib/rsync/discussion.mdwn | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/rsync/discussion.mdwn b/doc/plugins/contrib/rsync/discussion.mdwn
index 20c04af0f..9b4184e5f 100644
--- a/doc/plugins/contrib/rsync/discussion.mdwn
+++ b/doc/plugins/contrib/rsync/discussion.mdwn
@@ -46,3 +46,17 @@ The wiki now lives on (1), and clicking "edit" just works. --[[schmonz]]
 >> This plugin is definitely still useful for projects not able to use
 >> a DVCS (of which I've got at least one other), and possibly for
 >> other uses not yet imagined. ;-) --[[schmonz]]
+
+----
+
+Revew: --[[Joey]] 
+
+* I think it should not throw an error if no command is set. Just don't do anything.
+* If the rsync fails, it currently errors out, which will probably also leave
+  the wiki in a broken state, since ikiwiki will not get a chance to save
+  its state. This seems fragile; what if the laptop is offline, or the
+  server is down, etc. Maybe it should just warn if the rsync fails?
+* Is a new hook really needed? The savestate hook runs at a similar time;
+  only issue with it is that it is run even when ikiwiki has not
+  rendered any updated pages. Bah, I think you do need the new hook, how
+  annoying..
-- 
cgit v1.2.3


From 544cedaa1903c6314ed7ba98d96965a4017944ec Mon Sep 17 00:00:00 2001
From: Amitai Schlair <schmonz@magnetic-babysitter.(none)>
Date: Fri, 11 Sep 2009 17:34:47 -0400
Subject: response

---
 doc/plugins/contrib/rsync/discussion.mdwn | 6 ++++++
 1 file changed, 6 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/rsync/discussion.mdwn b/doc/plugins/contrib/rsync/discussion.mdwn
index 9b4184e5f..b162fbd6b 100644
--- a/doc/plugins/contrib/rsync/discussion.mdwn
+++ b/doc/plugins/contrib/rsync/discussion.mdwn
@@ -60,3 +60,9 @@ Revew: --[[Joey]]
   only issue with it is that it is run even when ikiwiki has not
   rendered any updated pages. Bah, I think you do need the new hook, how
   annoying..
+
+> * Depends whether the plugin would be on by default. If yes, then yes.
+>   If the admin has to enable it, I'd think they'd want the error.
+> * Changed the other errors to warnings.
+> * The name might be wrong: there isn't anything rsync-specific about the
+>   plugin, that's just the command I personally need to run. --[[schmonz]]
-- 
cgit v1.2.3


From a7d7acc0f761fff16637e427f30d365b54be1a33 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@gnu.kitenet.net>
Date: Fri, 11 Sep 2009 17:47:31 -0400
Subject: resp

---
 doc/plugins/contrib/rsync/discussion.mdwn | 9 +++++++++
 1 file changed, 9 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/rsync/discussion.mdwn b/doc/plugins/contrib/rsync/discussion.mdwn
index b162fbd6b..6bf7a3826 100644
--- a/doc/plugins/contrib/rsync/discussion.mdwn
+++ b/doc/plugins/contrib/rsync/discussion.mdwn
@@ -66,3 +66,12 @@ Revew: --[[Joey]]
 > * Changed the other errors to warnings.
 > * The name might be wrong: there isn't anything rsync-specific about the
 >   plugin, that's just the command I personally need to run. --[[schmonz]]
+
+>> One problem with the error is that it prevents dumping a new setup file with
+>> the plugin enabled, and then editing it to configure. ie:
+
+	joey@gnu:~>ikiwiki -setup .ikiwiki/joeywiki.setup -plugin rsync -dumpsetup new.setup
+	Must specify rsync_command
+
+> rsync seems by far the most likely command, though someone might use something
+> to push via ftp instead. I think calling it rsync is ok. --[[Joey]] 
-- 
cgit v1.2.3


From 5b818c9f2ac9c9a2d953f29194913036ab26c225 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@gnu.kitenet.net>
Date: Fri, 11 Sep 2009 18:28:35 -0400
Subject: doc update, add --exclude ikiwiki.cgi to examples

---
 IkiWiki/Plugin/rsync.pm                   |  2 +-
 doc/plugins/contrib/rsync.mdwn            | 21 ---------
 doc/plugins/contrib/rsync/discussion.mdwn | 77 -------------------------------
 doc/plugins/rsync.mdwn                    | 17 +++++++
 doc/plugins/rsync/discussion.mdwn         | 77 +++++++++++++++++++++++++++++++
 5 files changed, 95 insertions(+), 99 deletions(-)
 delete mode 100644 doc/plugins/contrib/rsync.mdwn
 delete mode 100644 doc/plugins/contrib/rsync/discussion.mdwn
 create mode 100644 doc/plugins/rsync.mdwn
 create mode 100644 doc/plugins/rsync/discussion.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/IkiWiki/Plugin/rsync.pm b/IkiWiki/Plugin/rsync.pm
index a62347a44..f14989ff8 100644
--- a/IkiWiki/Plugin/rsync.pm
+++ b/IkiWiki/Plugin/rsync.pm
@@ -18,7 +18,7 @@ sub getsetup () {
 		},
 		rsync_command => {
 			type => "string",
-			example => "rsync -qa --delete . user\@host:/path/to/docroot/",
+			example => "rsync -qa --delete . user\@host:/path/to/docroot/ --exclude ikiwiki.cgi",
 			description => "command to run to sync updated pages",
 			safe => 0,
 			rebuild => 0,
diff --git a/doc/plugins/contrib/rsync.mdwn b/doc/plugins/contrib/rsync.mdwn
deleted file mode 100644
index 71cd63947..000000000
--- a/doc/plugins/contrib/rsync.mdwn
+++ /dev/null
@@ -1,21 +0,0 @@
-[[!template id=plugin name=rsync core=0 author="[[schmonz]]"]]
-
-[[!template id=gitbranch branch=schmonz author="[[schmonz]]"]]
-
-This plugin allows ikiwiki to push generated pages to another host
-by running a command such as `rsync`.
-
-### Usage
-7. Enable automated SSH key exchange between ikiwiki and the remote
-   host. [keychain](http://www.gentoo.org/proj/en/keychain/) makes
-   it easy to use a passphrase-protected key for this purpose. It's
-   also a good idea to specify the exact command line to be permitted
-   in the remote host's `$HOME/.ssh/authorized_keys`.
-7. Set `rsync_command` in your setup file. If you're using a
-   passphrase-protected key, then set `rsync_command` to a shell
-   script which reads `keychain`'s current state before calling
-   `rsync`.
-
-### Implementation details
-* The plugin relies on a new "postrefresh" hook called at the very end of
-  `IkiWiki/Render.pm:refresh()`.
diff --git a/doc/plugins/contrib/rsync/discussion.mdwn b/doc/plugins/contrib/rsync/discussion.mdwn
deleted file mode 100644
index 6bf7a3826..000000000
--- a/doc/plugins/contrib/rsync/discussion.mdwn
+++ /dev/null
@@ -1,77 +0,0 @@
-## A use case
-
-Why I needed this plugin: I have two web servers available to me
-for a project. Neither does everything I need, but together they
-do. (This is a bit like the [Amazon S3
-scenario](http://kitenet.net/~joey/blog/entry/running_a_wiki_on_Amazon_S3/).)
-
-Server (1) is a university web server. It provides plentiful space
-and bandwidth, easy authentication for people editing the wiki, and
-a well-known stable URL. The wiki really wants to live here and
-very easily could except that the server doesn't allow arbitrary
-CGIs.
-
-Server (2) is provided by a generous alumnus's paid [[tips/DreamHost]]
-account. Disk and particularly network usage need to be minimized
-because over some threshold it costs him. CGI, etc. are available.
-
-My plan was to host the wiki on server (1) by taking advantage of
-server (2) to store the repository, source checkout, and generated
-pages, to host the repository browser, and to handle ikiwiki's CGI
-operations. In order for this to work, web edits on (2) would need
-to automatically push any changed pages to (1).
-
-As a proof of concept, I added an rsync post-commit hook after
-ikiwiki's usual. It worked, just not for web edits, which is how
-the wiki will be used. So I wrote this plugin to finish the job.
-The wiki now lives on (1), and clicking "edit" just works. --[[schmonz]]
-
-> Just out of interest, why use `rsync` and not `git push`.  i.e. a
-> different setup to solve the same problem would be to run a
-> normal ikiwiki setup on the universities server with its git
-> repository available over ssh (same security setup your using
-> for rsync should work for git over ssh).  On the cgi-capable server,
-> when it would rsync, make it git push.  It would seem that git
-> has enough information that it should be able to be more
-> network efficient.  It also means that corruption at one end
-> wouldn't be propagated to the other end. -- [[Will]]
-
->> Hey, that's a nice solution. (The site was in svn to begin with,
->> but it's in git now.) One advantage of my approach in this particular
->> case: server (1) doesn't have `git` installed, but does have `rsync`,
->> so (1)'s environment can remain completely untweaked other than the
->> SSH arrangement. I kind of like that all the sysadmin effort is
->> contained on one host.
->>
->> This plugin is definitely still useful for projects not able to use
->> a DVCS (of which I've got at least one other), and possibly for
->> other uses not yet imagined. ;-) --[[schmonz]]
-
-----
-
-Revew: --[[Joey]] 
-
-* I think it should not throw an error if no command is set. Just don't do anything.
-* If the rsync fails, it currently errors out, which will probably also leave
-  the wiki in a broken state, since ikiwiki will not get a chance to save
-  its state. This seems fragile; what if the laptop is offline, or the
-  server is down, etc. Maybe it should just warn if the rsync fails?
-* Is a new hook really needed? The savestate hook runs at a similar time;
-  only issue with it is that it is run even when ikiwiki has not
-  rendered any updated pages. Bah, I think you do need the new hook, how
-  annoying..
-
-> * Depends whether the plugin would be on by default. If yes, then yes.
->   If the admin has to enable it, I'd think they'd want the error.
-> * Changed the other errors to warnings.
-> * The name might be wrong: there isn't anything rsync-specific about the
->   plugin, that's just the command I personally need to run. --[[schmonz]]
-
->> One problem with the error is that it prevents dumping a new setup file with
->> the plugin enabled, and then editing it to configure. ie:
-
-	joey@gnu:~>ikiwiki -setup .ikiwiki/joeywiki.setup -plugin rsync -dumpsetup new.setup
-	Must specify rsync_command
-
-> rsync seems by far the most likely command, though someone might use something
-> to push via ftp instead. I think calling it rsync is ok. --[[Joey]] 
diff --git a/doc/plugins/rsync.mdwn b/doc/plugins/rsync.mdwn
new file mode 100644
index 000000000..0ab3872d9
--- /dev/null
+++ b/doc/plugins/rsync.mdwn
@@ -0,0 +1,17 @@
+[[!template id=plugin name=rsync author="[[schmonz]]"]]
+
+This plugin allows ikiwiki to push generated pages to another host
+by running a command such as `rsync`.
+
+The command to run is specified by setting `rsync_command` in your setup
+file. The command will be run in your destdir, so something like this
+is a typical command:
+
+	rsync -qa --delete . user\@host:/path/to/docroot/ --exclude ikiwiki.cgi
+
+If using rsync over ssh, you will need to enable noninteractive ssh login
+to the remote host. It's also a good idea to specify the exact command line
+to be permitted in the remote host's `$HOME/.ssh/authorized_keys`.
+
+Be sure to exclude the `ikiwiki.cgi` wrapper from being sent to the remote
+host.
diff --git a/doc/plugins/rsync/discussion.mdwn b/doc/plugins/rsync/discussion.mdwn
new file mode 100644
index 000000000..6bf7a3826
--- /dev/null
+++ b/doc/plugins/rsync/discussion.mdwn
@@ -0,0 +1,77 @@
+## A use case
+
+Why I needed this plugin: I have two web servers available to me
+for a project. Neither does everything I need, but together they
+do. (This is a bit like the [Amazon S3
+scenario](http://kitenet.net/~joey/blog/entry/running_a_wiki_on_Amazon_S3/).)
+
+Server (1) is a university web server. It provides plentiful space
+and bandwidth, easy authentication for people editing the wiki, and
+a well-known stable URL. The wiki really wants to live here and
+very easily could except that the server doesn't allow arbitrary
+CGIs.
+
+Server (2) is provided by a generous alumnus's paid [[tips/DreamHost]]
+account. Disk and particularly network usage need to be minimized
+because over some threshold it costs him. CGI, etc. are available.
+
+My plan was to host the wiki on server (1) by taking advantage of
+server (2) to store the repository, source checkout, and generated
+pages, to host the repository browser, and to handle ikiwiki's CGI
+operations. In order for this to work, web edits on (2) would need
+to automatically push any changed pages to (1).
+
+As a proof of concept, I added an rsync post-commit hook after
+ikiwiki's usual. It worked, just not for web edits, which is how
+the wiki will be used. So I wrote this plugin to finish the job.
+The wiki now lives on (1), and clicking "edit" just works. --[[schmonz]]
+
+> Just out of interest, why use `rsync` and not `git push`.  i.e. a
+> different setup to solve the same problem would be to run a
+> normal ikiwiki setup on the universities server with its git
+> repository available over ssh (same security setup your using
+> for rsync should work for git over ssh).  On the cgi-capable server,
+> when it would rsync, make it git push.  It would seem that git
+> has enough information that it should be able to be more
+> network efficient.  It also means that corruption at one end
+> wouldn't be propagated to the other end. -- [[Will]]
+
+>> Hey, that's a nice solution. (The site was in svn to begin with,
+>> but it's in git now.) One advantage of my approach in this particular
+>> case: server (1) doesn't have `git` installed, but does have `rsync`,
+>> so (1)'s environment can remain completely untweaked other than the
+>> SSH arrangement. I kind of like that all the sysadmin effort is
+>> contained on one host.
+>>
+>> This plugin is definitely still useful for projects not able to use
+>> a DVCS (of which I've got at least one other), and possibly for
+>> other uses not yet imagined. ;-) --[[schmonz]]
+
+----
+
+Revew: --[[Joey]] 
+
+* I think it should not throw an error if no command is set. Just don't do anything.
+* If the rsync fails, it currently errors out, which will probably also leave
+  the wiki in a broken state, since ikiwiki will not get a chance to save
+  its state. This seems fragile; what if the laptop is offline, or the
+  server is down, etc. Maybe it should just warn if the rsync fails?
+* Is a new hook really needed? The savestate hook runs at a similar time;
+  only issue with it is that it is run even when ikiwiki has not
+  rendered any updated pages. Bah, I think you do need the new hook, how
+  annoying..
+
+> * Depends whether the plugin would be on by default. If yes, then yes.
+>   If the admin has to enable it, I'd think they'd want the error.
+> * Changed the other errors to warnings.
+> * The name might be wrong: there isn't anything rsync-specific about the
+>   plugin, that's just the command I personally need to run. --[[schmonz]]
+
+>> One problem with the error is that it prevents dumping a new setup file with
+>> the plugin enabled, and then editing it to configure. ie:
+
+	joey@gnu:~>ikiwiki -setup .ikiwiki/joeywiki.setup -plugin rsync -dumpsetup new.setup
+	Must specify rsync_command
+
+> rsync seems by far the most likely command, though someone might use something
+> to push via ftp instead. I think calling it rsync is ok. --[[Joey]] 
-- 
cgit v1.2.3


From bac0174b786a10d3cb8277bfa519918bd38762c4 Mon Sep 17 00:00:00 2001
From: brush <brush@web>
Date: Tue, 22 Sep 2009 18:49:03 -0400
Subject: installation attachments q's

---
 doc/plugins/contrib/album/discussion.mdwn | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 doc/plugins/contrib/album/discussion.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/album/discussion.mdwn b/doc/plugins/contrib/album/discussion.mdwn
new file mode 100644
index 000000000..ee3aa6ce4
--- /dev/null
+++ b/doc/plugins/contrib/album/discussion.mdwn
@@ -0,0 +1,7 @@
+thanks for this plugin.  it might help me in my application, which is to provide album/galleries which can be edited (ie. new images added, taken away, etc.) through web interface.
+
+i have two challenges: firstly, for installation, i'm not sure what all the files are that need to be downloaded (because of my setup i can't easily pull the repo).  so far i have Ikiwiki/Plugins/album.pm; ikiwiki-album; and 4 files in templates/  any others?
+
+secondly: barring the CGI interface for editing the album, which would be great, is there at least a way to use attachment plugin or any other to manually add images and then create viewers for them?
+
+i'm new to ikiwiki, apologies if this is dealt with elsewhere.  -brush
-- 
cgit v1.2.3


From be47e501c32cec7660129f430a4f93ee7fe8d3ff Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Fri, 25 Sep 2009 14:19:49 -0400
Subject: reply to potential album user

---
 doc/plugins/contrib/album/discussion.mdwn | 46 +++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/album/discussion.mdwn b/doc/plugins/contrib/album/discussion.mdwn
index ee3aa6ce4..7a3c19cf6 100644
--- a/doc/plugins/contrib/album/discussion.mdwn
+++ b/doc/plugins/contrib/album/discussion.mdwn
@@ -1,7 +1,53 @@
 thanks for this plugin.  it might help me in my application, which is to provide album/galleries which can be edited (ie. new images added, taken away, etc.) through web interface.
 
+> That's my goal eventually, too. Perhaps you can help to
+> design/write this plugin? At the moment I'm mostly
+> waiting for a design "sanity check" from [[Joey]],
+> but any feedback you can provide on the design would
+> also be helpful. --[[smcv]]
+
 i have two challenges: firstly, for installation, i'm not sure what all the files are that need to be downloaded (because of my setup i can't easily pull the repo).  so far i have Ikiwiki/Plugins/album.pm; ikiwiki-album; and 4 files in templates/  any others?
 
+> Those are all the added files; ikiwiki-album isn't strictly
+> needed (IkiWiki itself doesn't use that code, but you can
+> use it to turn a directory full of images into correct
+> input for the album plugin).
+>
+> You probably also want the album plugin's expanded version of
+> style.css (or put its extra rules in your local.css).
+> Without that, your albums will be quite ugly.
+>
+> There aren't currently any other files modified by my branch.
+> --[[smcv]]
+
 secondly: barring the CGI interface for editing the album, which would be great, is there at least a way to use attachment plugin or any other to manually add images and then create viewers for them?
 
+> Images are just attachments, and viewers are pages (any supported
+> format, but .html will be fastest to render). Attach each image,
+> then write a page for each image containing the
+> \[[!albumimage]] directive (usually it will *only* contain that
+> directive).
+>
+> The script ikiwiki-album can help you to do this in a git/svn/etc.
+> tree; doing it over the web will be a lot of work (until I get
+> the CGI interface written), but it should already be possible!
+>
+> The structure is something like this:
+> 
+> * album.mdwn (contains the \[[!album]] directive, and perhaps also
+>   some \[[!albumsection]] directives)
+> * album/a.jpg
+> * album/a.html (contains the \[[!albumimage]] directive for a.jpg)
+> * album/b.jpg
+> * album/b.html (contains the \[[!albumimage]] directive for b.jpg)
+>
+> Have a look at ikiwiki-album to see how the directives are meant to
+> work in practice.
+>
+> --[[smcv]]
+
 i'm new to ikiwiki, apologies if this is dealt with elsewhere.  -brush
+
+> This plugin is pretty ambitious, and is unfinished, so I'd recommend
+> playing with  a normal IkiWiki installation for a bit, then trying
+> out this plugin when you've mastered the basics of IkiWiki. --[[smcv]]
-- 
cgit v1.2.3


From caa3818effe74c52fc783e31c51f0566c7805e62 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@gnu.kitenet.net>
Date: Wed, 30 Sep 2009 15:17:03 -0400
Subject: thoughts

---
 doc/plugins/contrib/album/discussion.mdwn | 33 +++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/album/discussion.mdwn b/doc/plugins/contrib/album/discussion.mdwn
index 7a3c19cf6..5fb91c5a4 100644
--- a/doc/plugins/contrib/album/discussion.mdwn
+++ b/doc/plugins/contrib/album/discussion.mdwn
@@ -51,3 +51,36 @@ i'm new to ikiwiki, apologies if this is dealt with elsewhere.  -brush
 > This plugin is pretty ambitious, and is unfinished, so I'd recommend
 > playing with  a normal IkiWiki installation for a bit, then trying
 > out this plugin when you've mastered the basics of IkiWiki. --[[smcv]]
+
+----
+
+You had wanted my feedback on the design of this. I have not looked at the
+code or tried it yet, but here goes. --[[Joey]]	
+
+* Needing to create the albumimage "viewer" pages for each photo
+  seems like it will become a pain. Everyone will need to come up
+  with their own automation for it, and then there's the question
+  of how to automate it when uploading attachments.
+* With each viewer page having next/prev links, I can see how you
+  were having the scalability issues with ikiwiki's data structures
+  earlier!
+* And doesn't each viewer page really depend on every other page in the
+  same albumsection? If a new page is added, the next/prev links
+  may need to be updated, for example. If so, there will be much
+  unnecessary rebuilding.
+* One thing I do like about having individual pages per image is
+  that they can each have their own comments, etc.
+* Seems possibly backwards that the albumimage controls what album
+  an image appears in. Two use cases -- 1: I may want to make a locked
+  album, but then anyone who can write to any other page on the wiki can
+  add an image to it. 2: I may want an image to appear in more than one
+  album. Think tags. So it seems it would be better to have the album
+  directive control what pages it includes (a la inline).
+* Putting a few of the above thoughts together, my ideal album system
+  seems to be one where I can just drop the images into a directory and
+  have them appear in the album index, as well as each generate their own wiki
+  page. Plus some way I can, later, edit metadata for captions,
+  etc. (Real pity we can't just put arbitrary metadata into the images
+  themselves.) This is almost pointing toward making the images first-class
+  wiki page sources. Hey, it worked for po! :) But the metadata and editing
+  problems probably don't really allow that.
-- 
cgit v1.2.3


From 3a188c047b4fed29865e7516f3b208901b22161d Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Mon, 5 Oct 2009 16:08:19 -0400
Subject: thoughts about renaming the actual images to .albumimage

---
 doc/plugins/contrib/album/discussion.mdwn | 127 ++++++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/album/discussion.mdwn b/doc/plugins/contrib/album/discussion.mdwn
index 5fb91c5a4..a613bb2d2 100644
--- a/doc/plugins/contrib/album/discussion.mdwn
+++ b/doc/plugins/contrib/album/discussion.mdwn
@@ -61,21 +61,59 @@ code or tried it yet, but here goes. --[[Joey]]
   seems like it will become a pain. Everyone will need to come up
   with their own automation for it, and then there's the question
   of how to automate it when uploading attachments.
+
+> There's already a script (ikiwiki-album) to populate a git
+> checkout with skeleton "viewer" pages; I was planning to make a
+> specialized CGI interface for albums after getting feedback from
+> you (since the requirements for that CGI interface change depending
+> on the implementation). I agree that this is ugly, though. -s
+
 * With each viewer page having next/prev links, I can see how you
   were having the scalability issues with ikiwiki's data structures
   earlier!
+
+> Yeah, I think they're a basic requirement from a UI point of view
+> though (although they don't necessarily have to be full wikilinks).
+> -s
+
 * And doesn't each viewer page really depend on every other page in the
   same albumsection? If a new page is added, the next/prev links
   may need to be updated, for example. If so, there will be much
   unnecessary rebuilding.
+
+> albumsections are just a way to insert headings into the flow of
+> photos, so they don't actually affect dependencies.
+>
+> One non-obvious constraint of ikiwiki's current design is that
+> everything "off-page" necessary to build any page has to happen
+> at scan time, which has caused a few strange design decisions,
+> like the fact that each viewer controls what album it's in.
+>
+> It's difficult for the contents of the album to just be a
+> pagespec, like for inline, because pagespecs can depend on
+> metadata, which is gathered in arbitrary order at scan time;
+> so the earliest you can safely apply a pagespec to the wiki
+> contents to get a concrete list of pages is at rebuild time.
+>
+> (This stalled my attempt at a trail plugin, too.) -s
+
 * One thing I do like about having individual pages per image is
   that they can each have their own comments, etc.
+
+> Yes; also, they can be wikilinked. I consider those to be
+> UI requirements. -s
+
 * Seems possibly backwards that the albumimage controls what album
   an image appears in. Two use cases -- 1: I may want to make a locked
   album, but then anyone who can write to any other page on the wiki can
   add an image to it. 2: I may want an image to appear in more than one
   album. Think tags. So it seems it would be better to have the album
   directive control what pages it includes (a la inline).
+
+> See note above about pagespecs not being very safe early on.
+> You did merge my inline-with-pagenames feature, which is safe to use
+> at scan time, though.
+
 * Putting a few of the above thoughts together, my ideal album system
   seems to be one where I can just drop the images into a directory and
   have them appear in the album index, as well as each generate their own wiki
@@ -84,3 +122,92 @@ code or tried it yet, but here goes. --[[Joey]]
   themselves.) This is almost pointing toward making the images first-class
   wiki page sources. Hey, it worked for po! :) But the metadata and editing
   problems probably don't really allow that.
+
+> Putting a JPEG in the web form is not an option from my point of
+> view :-) but perhaps there could just be a "web-editable" flag supplied
+> by plugins, and things could be changed to respect it.
+>
+> In a way, what you really want for metadata is to have it in the album
+> page, so you can batch-edit the whole lot by editing one file (this
+> does mean that editing the album necessarily causes each of its viewers
+> to be rebuilt, but in practice that happens anyway). -s
+
+----
+
+Trying to use the "special extension" design:
+
+Suppose that each viewer is a JPEG-or-GIF-or-something, with extension
+".albumimage". We have a gallery "memes" with three images, badger,
+mushroom and snake.
+
+Files in git repo:
+
+* index.mdwn
+* memes.mdwn
+* memes/badger.albumimage (a renamed JPEG)
+* memes/badger/comment_1._comment
+* memes/badger/comment_2._comment
+* memes/mushroom.albumimage (a renamed GIF)
+* memes/mushroom.meta (sidecar file with metadata)
+* memes/snake.albumimage (a renamed video)
+
+Files in web content:
+
+* index.html
+* memes/index.html
+* memes/96x96-badger.jpg (from img)
+* memes/96x96-mushroom.jpg (from img)
+* memes/96x96-snake.jpg (from img, hacked up to use totem-video-thumbnailer :-) )
+* memes/badger/index.html (including comments)
+* memes/badger.jpg
+* memes/mushroom/index.html
+* memes/mushroom.gif
+* memes/snake/index.html
+* memes/snake.mov
+
+ispage("memes/badger") (etc.) must be true, to make the above rendering
+happen, so albumimage needs to be a "page" extension.
+
+To not confuse other plugins, album should probably have a filter() hook
+that turns .albumimage files into HTML? That'd probably be a reasonable
+way to get them rendered anyway.
+
+do=edit&page=memes/badger needs to not put the JPG in a text box: somehow
+divert or override the normal edit CGI by telling it that .albumimage
+files are not editable in the usual way?
+
+Every image needs to depend on, and link to, the next and previous images,
+which is a bit tricky. In previous thinking about this I'd been applying
+the overly strict constraint that the ordered sequence of pages in each
+album must be known at scan time. However, that's not *necessarily* needed:
+the album and each photo could collect an unordered superset of dependencies
+at scan time, and at rebuild time that could be refined to be the exact set,
+in order. Perhaps restricting to "the images in an album A must match A/*"
+would be useful; then the unordered superset could just be "A/*". Your
+"albums via tags" idea would be nice too though, particularly for feature
+parity with e.g. Facebook: "photos of Joey" -> "tags/joey and albumimage()"
+maybe?
+
+If images are allowed to be considered to be part of more than one album,
+then a pretty and usable UI becomes harder - "next/previous" expands into
+"next photo in holidays/2009/germany / next photo in tagged/smcv / ..."
+and it could get quite hard to navigate. Perhaps next/previous links could
+be displayed only for the closest ancestor (in URL space) that is an
+album, or something?
+
+Requiring renaming is awkward for non-technical Windows/Mac users, with both
+platforms' defaults being to hide extensions; however, this could be
+circumvented by adding some sort of hook in attachment to turn things into
+a .albumimage at upload time, and declaring that using git/svn/... without
+extensions visible is a "don't do that then" situation :-)
+
+Ideally attachment could also be configured to upload into a specified
+underlay, so that photos don't have to be in your source-code control
+(you might want that, but I don't!).
+
+Things that would be nice, and are probably possible:
+
+* make the "Edit page" link on viewers divert to album-specific CGI instead
+  of just failing or not appearing
+* some way to deep-link to memes/badger.jpg with a wikilink, without knowing a
+  priori that it's secretly a JPEG
-- 
cgit v1.2.3


From 786dcf15c4117f9ae6b000318ac9809399df4d69 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@gnu.kitenet.net>
Date: Mon, 5 Oct 2009 16:47:12 -0400
Subject: responses, questions, ideas

---
 doc/plugins/contrib/album/discussion.mdwn | 45 ++++++++++++++++++++++++++++++-
 1 file changed, 44 insertions(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/album/discussion.mdwn b/doc/plugins/contrib/album/discussion.mdwn
index a613bb2d2..5c8e74fa6 100644
--- a/doc/plugins/contrib/album/discussion.mdwn
+++ b/doc/plugins/contrib/album/discussion.mdwn
@@ -76,6 +76,12 @@ code or tried it yet, but here goes. --[[Joey]]
 > though (although they don't necessarily have to be full wikilinks).
 > -s
 
+>> I think that with the new dependency types system, the dependencies for
+>> these can be presence dependencies, which will probably help with
+>> avoiding rebuilds of a page if the next/prev page is changed.
+>> (Unless you use img to make the thumbnails for those links, then it
+>> would rebuild the thumbnails anyway. Have not looked at the code.) --[[Joey]] 
+
 * And doesn't each viewer page really depend on every other page in the
   same albumsection? If a new page is added, the next/prev links
   may need to be updated, for example. If so, there will be much
@@ -97,6 +103,11 @@ code or tried it yet, but here goes. --[[Joey]]
 >
 > (This stalled my attempt at a trail plugin, too.) -s
 
+>> Not sure I understand why these need to look at pagespecs at scan time?
+>> Also, note that it is fairly doable to detect if a pagespec uses such
+>> metadata. Er, I mean, I have a cheezy hack in `add_depends` now that does
+>> it to deal with a similar case. --[[Joey]] 
+
 * One thing I do like about having individual pages per image is
   that they can each have their own comments, etc.
 
@@ -131,6 +142,15 @@ code or tried it yet, but here goes. --[[Joey]]
 > page, so you can batch-edit the whole lot by editing one file (this
 > does mean that editing the album necessarily causes each of its viewers
 > to be rebuilt, but in practice that happens anyway). -s
+>
+>> Yes, that would make some sense.. It also allows putting one image in
+>> two albums, with different caption etc. (Maybe for different audiences.)
+>>
+>> It would probably be possible to add a new dependency type, and thus
+>> make ikiwiki smart about noticing whether the metadata has actually
+>> changed, and only update those viewers where it has. But the dependency
+>> type stuff is still very new, and not plugin friendly .. so only just
+>> possible, --[[Joey]] 
 
 ----
 
@@ -140,6 +160,10 @@ Suppose that each viewer is a JPEG-or-GIF-or-something, with extension
 ".albumimage". We have a gallery "memes" with three images, badger,
 mushroom and snake.
 
+> An alternative might be to use ".album.jpg", and ".album.gif"
+> etc as the htmlize extensions. May need some fixes to ikiwiki to support
+> that. --[[Joey]] 
+
 Files in git repo:
 
 * index.mdwn
@@ -172,6 +196,10 @@ To not confuse other plugins, album should probably have a filter() hook
 that turns .albumimage files into HTML? That'd probably be a reasonable
 way to get them rendered anyway.
 
+> I guess that is needed to avoid preprocess, scan, etc trying to process
+> the image, as well as eg, smiley trying to munge it in sanitize.
+> --[[Joey]] 
+
 do=edit&page=memes/badger needs to not put the JPG in a text box: somehow
 divert or override the normal edit CGI by telling it that .albumimage
 files are not editable in the usual way?
@@ -182,7 +210,14 @@ the overly strict constraint that the ordered sequence of pages in each
 album must be known at scan time. However, that's not *necessarily* needed:
 the album and each photo could collect an unordered superset of dependencies
 at scan time, and at rebuild time that could be refined to be the exact set,
-in order. Perhaps restricting to "the images in an album A must match A/*"
+in order.
+
+> Why do you need to collect this info at scan time? You can determine it
+> at build time via `pagespec_match_list`, surely .. maybe with some
+> memoization to avoid each image in an album building the same list.
+> I sense that I may be missing a subtelty though. --[[Joey]] 
+
+Perhaps restricting to "the images in an album A must match A/*"
 would be useful; then the unordered superset could just be "A/*". Your
 "albums via tags" idea would be nice too though, particularly for feature
 parity with e.g. Facebook: "photos of Joey" -> "tags/joey and albumimage()"
@@ -195,12 +230,20 @@ and it could get quite hard to navigate. Perhaps next/previous links could
 be displayed only for the closest ancestor (in URL space) that is an
 album, or something?
 
+> Ugh, yeah, that is a problem. Perhaps wanting to support that was just
+> too ambitious. --[[Joey]] 
+
 Requiring renaming is awkward for non-technical Windows/Mac users, with both
 platforms' defaults being to hide extensions; however, this could be
 circumvented by adding some sort of hook in attachment to turn things into
 a .albumimage at upload time, and declaring that using git/svn/... without
 extensions visible is a "don't do that then" situation :-)
 
+> Or extend `pagetype` so it can do the necessary matching without
+> renaming. Maybe by allowing a subdirectory to be specified along
+> with an extension. (Or allow specifying a full pagespec,
+> but I hesitate to seriously suggest that.) --[[Joey]] 
+
 Ideally attachment could also be configured to upload into a specified
 underlay, so that photos don't have to be in your source-code control
 (you might want that, but I don't!).
-- 
cgit v1.2.3


From 22ed3f388b6433c512ca7a026d868861ea1990ea Mon Sep 17 00:00:00 2001
From: Jogo <Jogo@web>
Date: Sun, 11 Oct 2009 04:34:17 -0400
Subject:

---
 doc/plugins/contrib/groupfile.mdwn | 105 +++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 doc/plugins/contrib/groupfile.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/groupfile.mdwn b/doc/plugins/contrib/groupfile.mdwn
new file mode 100644
index 000000000..e5c0ded42
--- /dev/null
+++ b/doc/plugins/contrib/groupfile.mdwn
@@ -0,0 +1,105 @@
+[[!template id=plugin name=groupfile core=0 author="[[Jogo]]"]]
+
+This plugin add a `group(groupname)` function to [[ikiwiki/PageSpec]], which is true
+only if the actual user is member of the group named `groupname`.
+
+Groups membership are read from a file. The syntax of this file is very close to
+usual `/etc/passwd` Unix file : the group's name, followed by a colon, followed by
+a coma separated list of user's names. For exemple :
+
+    dev:toto,foo
+    i18n:zorba
+
+-----
+
+    #!/usr/bin/perl
+    # GroupFile plugin.
+    # by Joseph Boudou <jogo at matabio dot net>
+    
+    package IkiWiki::Plugin::groupfile;
+    
+    use warnings;
+    use strict;
+    use IkiWiki 3.00;
+    
+    sub import {
+        hook(type => 'getsetup', id => 'groups', call => \&get_setup);
+    }
+    
+    sub get_setup () {
+        return (
+            plugin => {
+                safe    => 0,
+                rebuild => 0,
+            },
+            group_file => {
+                type        => 'string',
+                example     => '/etc/ikiwiki/group',
+                description => 'group file location',
+                safe        => 0,
+                rebuild     => 0,
+            },
+        );
+    }
+    
+    my $users_of = 0;
+    
+    sub get_groups () {
+        if (not $users_of) {
+    
+            if (not defined $config{group_file}) {
+                return 'group_file option not set';
+            }
+    
+            open my $file, '<', $config{group_file}
+                or return 'Unable to open group_file';
+    
+            $users_of = {};
+            READ:
+            while (<$file>) {
+                next READ if (/^\s*$/);
+    
+                if (/^(\w+):([\w,]+)/) {
+                    %{ $users_of->{$1} } = map { $_ => 1 } split /,/, $2;
+                }
+                else {
+                    $users_of = "Error at group_file:$.";
+                    last READ;
+                }
+            }
+    
+            close $file;
+        }
+    
+        return $users_of;
+    }
+    
+    package IkiWiki::PageSpec;
+    
+    sub match_group ($$;@) {
+        shift;
+        my $group  = shift;
+        my %params = @_;
+    
+        if (not exists $params{user}) {
+            return IkiWiki::ErrorReason->new('no user specified');
+        }
+        if (not defined $params{user}) {
+            return IkiWiki::FailReason->new('not logged in');
+        }
+    
+        my $users_of = IkiWiki::Plugin::groupfile::get_groups();
+        if (not ref $users_of) {
+            return IkiWiki::ErrorReason->new($users_of);
+        }
+    
+        if (exists $users_of->{$group}{ $params{user} }) {
+            return IkiWiki::SuccessReason->new("user is member of $group");
+        }
+        else {
+            return IkiWiki::FailReason->new(
+                "user $params{user} isn't member of $group");
+        }
+    }
+    
+    1
-- 
cgit v1.2.3


From cd5bf7eb7f74c2414a87c77141ed0c502ff7f464 Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Thu, 15 Oct 2009 23:16:52 -0400
Subject: comments after trying to implement joey's idea

---
 doc/plugins/contrib/album/discussion.mdwn | 134 ++++++++++++++++++++++++++----
 1 file changed, 119 insertions(+), 15 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/album/discussion.mdwn b/doc/plugins/contrib/album/discussion.mdwn
index 5c8e74fa6..156cd7ad8 100644
--- a/doc/plugins/contrib/album/discussion.mdwn
+++ b/doc/plugins/contrib/album/discussion.mdwn
@@ -68,6 +68,9 @@ code or tried it yet, but here goes. --[[Joey]]
 > you (since the requirements for that CGI interface change depending
 > on the implementation). I agree that this is ugly, though. -s
 
+>> Would you accept a version where the albumimage "viewer" pages
+>> could be 0 bytes long, at least until metadata gets added? -s
+
 * With each viewer page having next/prev links, I can see how you
   were having the scalability issues with ikiwiki's data structures
   earlier!
@@ -80,7 +83,7 @@ code or tried it yet, but here goes. --[[Joey]]
 >> these can be presence dependencies, which will probably help with
 >> avoiding rebuilds of a page if the next/prev page is changed.
 >> (Unless you use img to make the thumbnails for those links, then it
->> would rebuild the thumbnails anyway. Have not looked at the code.) --[[Joey]] 
+>> would rebuild the thumbnails anyway. Have not looked at the code.) --[[Joey]]
 
 * And doesn't each viewer page really depend on every other page in the
   same albumsection? If a new page is added, the next/prev links
@@ -108,6 +111,11 @@ code or tried it yet, but here goes. --[[Joey]]
 >> metadata. Er, I mean, I have a cheezy hack in `add_depends` now that does
 >> it to deal with a similar case. --[[Joey]] 
 
+>>> I think I was misunderstanding how early you have to call `add_depends`?
+>>> The critical thing I missed was that if you're scanning a page, you're
+>>> going to rebuild it in a moment anyway, so it doesn't matter if you
+>>> have no idea what it depends on until the rebuild phase. -s
+
 * One thing I do like about having individual pages per image is
   that they can each have their own comments, etc.
 
@@ -121,9 +129,25 @@ code or tried it yet, but here goes. --[[Joey]]
   album. Think tags. So it seems it would be better to have the album
   directive control what pages it includes (a la inline).
 
-> See note above about pagespecs not being very safe early on.
-> You did merge my inline-with-pagenames feature, which is safe to use
-> at scan time, though.
+> I'm inclined to fix this by constraining images to be subpages of exactly
+> one album: if they're subpages of 2+ nested albums then they're only
+> considered to be in the deepest-nested one (i.e. longest URL), and if
+> they're not in any album then that's a usage error. This would
+> also make prev/next links sane.
+>
+> If you want to reference images from elsewhere in the wiki and display
+> them as if in an album, then you can use an ordinary inline with
+> the same template that the album would use, and I'll make sure the
+> templates are set up so this works.
+>
+> (Implementation detail: this means that an image X/Y/Z/W/V, where X and
+> Y are albums, Z does not exist and W exists but is not an album,
+> would have a content dependency on Y, a presence dependency on Z
+> and a content dependency on W.)
+>
+> Perhaps I should just restrict to having the album images be direct
+> subpages of the album, although that would mean breaking some URLs
+> on the existing website I'm doing all this work for... -s
 
 * Putting a few of the above thoughts together, my ideal album system
   seems to be one where I can just drop the images into a directory and
@@ -137,15 +161,57 @@ code or tried it yet, but here goes. --[[Joey]]
 > Putting a JPEG in the web form is not an option from my point of
 > view :-) but perhaps there could just be a "web-editable" flag supplied
 > by plugins, and things could be changed to respect it.
->
+
+>> Replying to myself: would you accept patches to support
+>> `hook(type => 'htmlize', editable => 0, ...)` in editpage? This would
+>> essentially mean "this is an opaque binary: you can delete it
+>> or rename it, and it might have its own special editing UI, but you
+>> can never get it in a web form".
+>>
+>> On the other hand, that essentially means we need to reimplement
+>> editpage in order to edit the sidecar files that contain the metadata.
+>> Having already done one partial reimplementation of editpage (for
+>> comments) I'm in no hurry to do another.
+>>
+>> I suppose another possibility would be to register hook
+>> functions to be called by editpage when it loads and saves the
+>> file. In this case, the loading hook would be to discard
+>> the binary and use filter() instead, and the saving conversion
+>> would be to write the edited content into the metadata sidecar
+>> (creating it if necessary).
+>>
+>> I'd also need to make editpage (and also comments!) not allow the
+>> creation of a file of type albumjpg, albumgif etc., which is something
+>> I previously missed; and I'd need to make attachment able to
+>> upload-and-rename.
+>> -s
+
 > In a way, what you really want for metadata is to have it in the album
 > page, so you can batch-edit the whole lot by editing one file (this
 > does mean that editing the album necessarily causes each of its viewers
 > to be rebuilt, but in practice that happens anyway). -s
->
->> Yes, that would make some sense.. It also allows putting one image in
->> two albums, with different caption etc. (Maybe for different audiences.)
+
+>> Replying to myself: in practice that *doesn't* happen anyway. Having
+>> the metadata in the album page is somewhat harmful because it means
+>> that changing the title of one image causes every viewer in the album
+>> to be rebuilt, whereas if you have a metadata file per image, only
+>> the album itself, plus the next and previous viewers, need
+>> rebuilding. So, I think a file per image is the way to go.
 >>
+>> Ideally we'd have some way to "batch-edit" the metadata of all
+>> images in an album at once, except that would make conflict
+>> resolution much more complicated to deal with; maybe just
+>> give up and scream about mid-air collisions in that case?
+>> (That's apparently good enough for Bugzilla, but not really
+>> for ikiwiki). -s
+
+>> Yes, [all metadata in one file] would make some sense.. It also allows putting one image in
+>> two albums, with different caption etc. (Maybe for different audiences.)
+>> --[[Joey]]
+
+>>> Eek. No, that's not what I had in mind at all; the metadata ends up
+>>> in the "viewer" page, so it's necessarily the same for all albums. -s
+
 >> It would probably be possible to add a new dependency type, and thus
 >> make ikiwiki smart about noticing whether the metadata has actually
 >> changed, and only update those viewers where it has. But the dependency
@@ -164,23 +230,26 @@ mushroom and snake.
 > etc as the htmlize extensions. May need some fixes to ikiwiki to support
 > that. --[[Joey]] 
 
+>> foo.albumjpg (etc.) for images, and foo._albummeta (with
+>> `keepextension => 1`) for sidecar metadata files, seems viable. -s
+
 Files in git repo:
 
 * index.mdwn
 * memes.mdwn
-* memes/badger.albumimage (a renamed JPEG)
+* memes/badger.albumjpg (a renamed JPEG)
 * memes/badger/comment_1._comment
 * memes/badger/comment_2._comment
-* memes/mushroom.albumimage (a renamed GIF)
-* memes/mushroom.meta (sidecar file with metadata)
-* memes/snake.albumimage (a renamed video)
+* memes/mushroom.albumgif (a renamed GIF)
+* memes/mushroom._albummeta (sidecar file with metadata)
+* memes/snake.albummov (a renamed video)
 
 Files in web content:
 
 * index.html
 * memes/index.html
 * memes/96x96-badger.jpg (from img)
-* memes/96x96-mushroom.jpg (from img)
+* memes/96x96-mushroom.gif (from img)
 * memes/96x96-snake.jpg (from img, hacked up to use totem-video-thumbnailer :-) )
 * memes/badger/index.html (including comments)
 * memes/badger.jpg
@@ -200,10 +269,28 @@ way to get them rendered anyway.
 > the image, as well as eg, smiley trying to munge it in sanitize.
 > --[[Joey]] 
 
+>> As long as nothing has a filter() hook that assumes it's already
+>> text... filters are run in arbitrary order. We seem to be OK so far
+>> though.
+>>
+>> If this is the route I take, I propose to have the result of filter()
+>> be the contents of the sidecar metadata file (empty string if none),
+>> with the `\[[!albumimage]]` directive (which no longer requires
+>> arguments) prepended if not already present. This would mean that
+>> meta directives in the metadata file would work as normal, and it
+>> would be possible to insert text both before and after the viewer
+>> if desired. The result of filter() would also be a sensible starting
+>> point for editing, and the result of editing could be diverted into
+>> the metadata file. -s
+
 do=edit&page=memes/badger needs to not put the JPG in a text box: somehow
 divert or override the normal edit CGI by telling it that .albumimage
 files are not editable in the usual way?
 
+> Something I missed here is that editpage also needs to be told that
+> creating new files of type albumjpg, albumgif etc. is not allowed
+> either! -s
+
 Every image needs to depend on, and link to, the next and previous images,
 which is a bit tricky. In previous thinking about this I'd been applying
 the overly strict constraint that the ordered sequence of pages in each
@@ -217,6 +304,9 @@ in order.
 > memoization to avoid each image in an album building the same list.
 > I sense that I may be missing a subtelty though. --[[Joey]] 
 
+>> I think I was misunderstanding how early you have to call `add_depends`
+>> as mentioned above. -s
+
 Perhaps restricting to "the images in an album A must match A/*"
 would be useful; then the unordered superset could just be "A/*". Your
 "albums via tags" idea would be nice too though, particularly for feature
@@ -233,6 +323,9 @@ album, or something?
 > Ugh, yeah, that is a problem. Perhaps wanting to support that was just
 > too ambitious. --[[Joey]] 
 
+>> I propose to restrict to having images be subpages of albums, as
+>> described above. -s
+
 Requiring renaming is awkward for non-technical Windows/Mac users, with both
 platforms' defaults being to hide extensions; however, this could be
 circumvented by adding some sort of hook in attachment to turn things into
@@ -244,13 +337,24 @@ extensions visible is a "don't do that then" situation :-)
 > with an extension. (Or allow specifying a full pagespec,
 > but I hesitate to seriously suggest that.) --[[Joey]] 
 
+>> I think that might be a terrifying idea for another day. If we can
+>> mutate the extension during the `attach` upload, that'd be enough;
+>> I don't think people who are skilled enough to use git/svn/...,
+>> but not skilled enough to tell Explorer to show file extensions,
+>> represent a major use case. -s
+
 Ideally attachment could also be configured to upload into a specified
 underlay, so that photos don't have to be in your source-code control
 (you might want that, but I don't!).
 
+> Replying to myself: perhaps best done as an orthogonal extension
+> to attach? -s
+
 Things that would be nice, and are probably possible:
 
 * make the "Edit page" link on viewers divert to album-specific CGI instead
-  of just failing or not appearing
+  of just failing or not appearing (probably possible via pagetemplate)
+
 * some way to deep-link to memes/badger.jpg with a wikilink, without knowing a
-  priori that it's secretly a JPEG
+  priori that it's secretly a JPEG (probably harder than it looks - you'd
+  have to make a directive for it and it's probably not worth it)
-- 
cgit v1.2.3


From 969ce8c5f889f8f2696c3ed4995f021b2a6539e1 Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Thu, 15 Oct 2009 23:22:18 -0400
Subject: add a bit more attribution so it's clearer what Joey wrote

---
 doc/plugins/contrib/album/discussion.mdwn | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/album/discussion.mdwn b/doc/plugins/contrib/album/discussion.mdwn
index 156cd7ad8..50d6c8ddd 100644
--- a/doc/plugins/contrib/album/discussion.mdwn
+++ b/doc/plugins/contrib/album/discussion.mdwn
@@ -60,7 +60,7 @@ code or tried it yet, but here goes. --[[Joey]]
 * Needing to create the albumimage "viewer" pages for each photo
   seems like it will become a pain. Everyone will need to come up
   with their own automation for it, and then there's the question
-  of how to automate it when uploading attachments.
+  of how to automate it when uploading attachments. -J
 
 > There's already a script (ikiwiki-album) to populate a git
 > checkout with skeleton "viewer" pages; I was planning to make a
@@ -73,7 +73,7 @@ code or tried it yet, but here goes. --[[Joey]]
 
 * With each viewer page having next/prev links, I can see how you
   were having the scalability issues with ikiwiki's data structures
-  earlier!
+  earlier! -J
 
 > Yeah, I think they're a basic requirement from a UI point of view
 > though (although they don't necessarily have to be full wikilinks).
@@ -88,7 +88,7 @@ code or tried it yet, but here goes. --[[Joey]]
 * And doesn't each viewer page really depend on every other page in the
   same albumsection? If a new page is added, the next/prev links
   may need to be updated, for example. If so, there will be much
-  unnecessary rebuilding.
+  unnecessary rebuilding. -J
 
 > albumsections are just a way to insert headings into the flow of
 > photos, so they don't actually affect dependencies.
@@ -117,7 +117,7 @@ code or tried it yet, but here goes. --[[Joey]]
 >>> have no idea what it depends on until the rebuild phase. -s
 
 * One thing I do like about having individual pages per image is
-  that they can each have their own comments, etc.
+  that they can each have their own comments, etc. -J
 
 > Yes; also, they can be wikilinked. I consider those to be
 > UI requirements. -s
@@ -127,7 +127,7 @@ code or tried it yet, but here goes. --[[Joey]]
   album, but then anyone who can write to any other page on the wiki can
   add an image to it. 2: I may want an image to appear in more than one
   album. Think tags. So it seems it would be better to have the album
-  directive control what pages it includes (a la inline).
+  directive control what pages it includes (a la inline). -J
 
 > I'm inclined to fix this by constraining images to be subpages of exactly
 > one album: if they're subpages of 2+ nested albums then they're only
@@ -156,7 +156,7 @@ code or tried it yet, but here goes. --[[Joey]]
   etc. (Real pity we can't just put arbitrary metadata into the images
   themselves.) This is almost pointing toward making the images first-class
   wiki page sources. Hey, it worked for po! :) But the metadata and editing
-  problems probably don't really allow that.
+  problems probably don't really allow that. -J
 
 > Putting a JPEG in the web form is not an option from my point of
 > view :-) but perhaps there could just be a "web-editable" flag supplied
-- 
cgit v1.2.3


From bc4b8e4e239e56fedcc3cf065f7c6cbd224f7525 Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Thu, 15 Oct 2009 23:27:53 -0400
Subject: not another hidden requirement...

---
 doc/plugins/contrib/album/discussion.mdwn | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/album/discussion.mdwn b/doc/plugins/contrib/album/discussion.mdwn
index 50d6c8ddd..9720589b4 100644
--- a/doc/plugins/contrib/album/discussion.mdwn
+++ b/doc/plugins/contrib/album/discussion.mdwn
@@ -69,7 +69,16 @@ code or tried it yet, but here goes. --[[Joey]]
 > on the implementation). I agree that this is ugly, though. -s
 
 >> Would you accept a version where the albumimage "viewer" pages
->> could be 0 bytes long, at least until metadata gets added? -s
+>> could be 0 bytes long, at least until metadata gets added?
+>>
+>> The more I think about the "binaries as first-class pages" approach,
+>> the more subtle interactions I notice with other plugins. I
+>> think I'm up to needing changes to editpage, comments, attachment
+>> and recentchanges, plus adjustments to img and Render (to reduce
+>> duplication when thumbnailing an image with a strange extension
+>> while simultaneously changing the extension, and to hardlink/copy
+>> an image with a strange extension to a differing target filename
+>> with the normal extension, respectively). -s
 
 * With each viewer page having next/prev links, I can see how you
   were having the scalability issues with ikiwiki's data structures
@@ -350,6 +359,10 @@ underlay, so that photos don't have to be in your source-code control
 > Replying to myself: perhaps best done as an orthogonal extension
 > to attach? -s
 
+> Yet another non-obvious thing this design would need to do is to find
+> some way to have each change to memes/badger._albummeta show up as a
+> change to memes/badger in `recentchanges`. -s
+
 Things that would be nice, and are probably possible:
 
 * make the "Edit page" link on viewers divert to album-specific CGI instead
-- 
cgit v1.2.3


From 4dd50ba1bc4cb86c408ff45bbe06069e511e28fc Mon Sep 17 00:00:00 2001
From: Jon Dowland <jon@alcopop.org>
Date: Wed, 28 Oct 2009 13:52:05 +0000
Subject: update URL to mediawiki plugin

---
 doc/plugins/contrib/mediawiki.mdwn | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/mediawiki.mdwn b/doc/plugins/contrib/mediawiki.mdwn
index 7bf1ba0df..13c2d04b2 100644
--- a/doc/plugins/contrib/mediawiki.mdwn
+++ b/doc/plugins/contrib/mediawiki.mdwn
@@ -1,7 +1,10 @@
 [[!template id=plugin name=mediawiki author="[[sabr]]"]]
 [[!tag type/format]]
 
-[The Mediawiki plugin](http://u32.net/Mediawiki_Plugin/) allows ikiwiki to
-process pages written using MediaWiki markup.
+The Mediawiki plugin allows ikiwiki to process pages written using MediaWiki
+markup.
 
-Available at <http://alcopop.org/~jon/mediawiki.pm>
+Available at <http://github.com/jmtd/mediawiki.pm>.
+
+This plugin originally lived at <http://u32.net/Mediawiki_Plugin/>, but that
+website has disappeared.
-- 
cgit v1.2.3


From 9f30da3e1cb4fef022e1ad4802a6406e61c524d4 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Mon, 30 Nov 2009 21:55:06 -0500
Subject: xslt plugin

---
 doc/plugins/contrib/xslt.mdwn | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 doc/plugins/contrib/xslt.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/xslt.mdwn b/doc/plugins/contrib/xslt.mdwn
new file mode 100644
index 000000000..406d42f4e
--- /dev/null
+++ b/doc/plugins/contrib/xslt.mdwn
@@ -0,0 +1,37 @@
+## NAME
+
+IkiWiki::Plugin::xslt - ikiwiki directive to process an XML file with XSLT
+
+## SYNOPSIS
+
+\[[!xslt file="data1.xml" stylesheet="style1.xsl"]]
+
+## DESCRIPTION
+
+IkiWiki::Plugin::xslt is an IkiWiki plugin implementing a directive
+to process an input XML data file with XSLT, and output the result in
+the page where the directive was called.
+
+It is expected that the XSLT stylesheet will output valid HTML markup.
+
+## OPTIONS
+
+There are two arguments to this directive.
+
+* **file:**
+  The file which contains XML data to be processed.  This file is searched for using the usual IkiWiki mechanism, thus finding the file first in the same directory as the page, then in the directory above, and so on.
+
+* **stylesheet:**
+  The file which contains XSLT stylesheet to apply to the XML data.  This file is searched for using the usual IkiWiki mechanism, thus finding the file first in the same directory as the page, then in the directory above, and so on.
+
+## PREREQUISITES
+
+    IkiWiki
+    XML::LibXML
+    XML::LibXSLT
+
+## DOWNLOAD
+
+* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/xslt.pm>
+* git repo at git://github.com/rubykat/ikiplugins.git
+
-- 
cgit v1.2.3


From d57ec1c6a4d2e05d2570fb273c7682d383b3b7d9 Mon Sep 17 00:00:00 2001
From: "http://jmtd.livejournal.com/" <http://jmtd.livejournal.com/@web>
Date: Tue, 1 Dec 2009 11:30:03 -0500
Subject: add plugin template

---
 doc/plugins/contrib/xslt.mdwn | 1 +
 1 file changed, 1 insertion(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/xslt.mdwn b/doc/plugins/contrib/xslt.mdwn
index 406d42f4e..e26f58e38 100644
--- a/doc/plugins/contrib/xslt.mdwn
+++ b/doc/plugins/contrib/xslt.mdwn
@@ -1,3 +1,4 @@
+[[!template id=plugin name=xslt author="rubykat"]]
 ## NAME
 
 IkiWiki::Plugin::xslt - ikiwiki directive to process an XML file with XSLT
-- 
cgit v1.2.3


From db746519ebca6495342d836a77c0664977ee0d99 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@gnu.kitenet.net>
Date: Tue, 1 Dec 2009 16:04:18 -0500
Subject: security and comments

---
 doc/plugins/contrib/xslt/discussion.mdwn | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)
 create mode 100644 doc/plugins/contrib/xslt/discussion.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/xslt/discussion.mdwn b/doc/plugins/contrib/xslt/discussion.mdwn
new file mode 100644
index 000000000..a549681de
--- /dev/null
+++ b/doc/plugins/contrib/xslt/discussion.mdwn
@@ -0,0 +1,16 @@
+## security
+
+I'm curious what the security implications of having this plugin on a
+publically writable wiki are.
+
+First, it looks like the way it looks up the stylesheet file will happily
+use a regular .mdwn wiki page as the stylsheet. Which means any user can
+create a stylesheet and have it be used, without needing permission to
+upload arbitrary files. That probably needs to be fixed; one way would be
+to mandate that the `srcfile` has a `.xsl` extension.
+
+Secondly, if an attacker is able to upload a stylesheet file somehow, could
+this be used to attack the server where it is built? I know that xslt is
+really a full programming language, so I assume at least DOS attacks are
+possible. Can it also read other arbitrary files, run other programs, etc?
+--[[Joey]] 
-- 
cgit v1.2.3


From 3ca05b15d6c47446e89128b405b9ffce8a418a3c Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Tue, 1 Dec 2009 18:30:25 -0500
Subject: reply to comment

---
 doc/plugins/contrib/xslt/discussion.mdwn | 6 ++++++
 1 file changed, 6 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/xslt/discussion.mdwn b/doc/plugins/contrib/xslt/discussion.mdwn
index a549681de..3288150a4 100644
--- a/doc/plugins/contrib/xslt/discussion.mdwn
+++ b/doc/plugins/contrib/xslt/discussion.mdwn
@@ -14,3 +14,9 @@ this be used to attack the server where it is built? I know that xslt is
 really a full programming language, so I assume at least DOS attacks are
 possible. Can it also read other arbitrary files, run other programs, etc?
 --[[Joey]] 
+
+> For the first point, agreed.  It should probably check that the data file has a `.xml` extension also.  Will fix soon.
+
+> For the second point, I think the main concern would be resource usage.  XSLT is a pretty limited language; it can read other XML files, but it can't run other programs so far as I know.
+
+> -- [[KathrynAndersen]]
-- 
cgit v1.2.3


From cbdd0d85078eb8bc9d01698e9cc8ac24e12ca7ea Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Tue, 1 Dec 2009 18:51:10 -0500
Subject: bug fix; now checks extensions.

---
 doc/plugins/contrib/xslt.mdwn | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/xslt.mdwn b/doc/plugins/contrib/xslt.mdwn
index e26f58e38..f98f8378d 100644
--- a/doc/plugins/contrib/xslt.mdwn
+++ b/doc/plugins/contrib/xslt.mdwn
@@ -20,10 +20,10 @@ It is expected that the XSLT stylesheet will output valid HTML markup.
 There are two arguments to this directive.
 
 * **file:**
-  The file which contains XML data to be processed.  This file is searched for using the usual IkiWiki mechanism, thus finding the file first in the same directory as the page, then in the directory above, and so on.
+  The file which contains XML data to be processed. This file *must* have a `.xml` extension (`filename.xml`). This file is searched for using the usual IkiWiki mechanism, thus finding the file first in the same directory as the page, then in the directory above, and so on.
 
 * **stylesheet:**
-  The file which contains XSLT stylesheet to apply to the XML data.  This file is searched for using the usual IkiWiki mechanism, thus finding the file first in the same directory as the page, then in the directory above, and so on.
+  The file which contains XSLT stylesheet to apply to the XML data.  This file *must* have a `.xsl` extension (`filename.xsl`). This file is searched for using the usual IkiWiki mechanism, thus finding the file first in the same directory as the page, then in the directory above, and so on.
 
 ## PREREQUISITES
 
-- 
cgit v1.2.3


From 18840f67e991e48e1c78bf848ce3dd50a649569b Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Tue, 1 Dec 2009 18:51:48 -0500
Subject: now have fixed xslt plugin

---
 doc/plugins/contrib/xslt/discussion.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/xslt/discussion.mdwn b/doc/plugins/contrib/xslt/discussion.mdwn
index 3288150a4..9cda02f88 100644
--- a/doc/plugins/contrib/xslt/discussion.mdwn
+++ b/doc/plugins/contrib/xslt/discussion.mdwn
@@ -15,7 +15,7 @@ really a full programming language, so I assume at least DOS attacks are
 possible. Can it also read other arbitrary files, run other programs, etc?
 --[[Joey]] 
 
-> For the first point, agreed.  It should probably check that the data file has a `.xml` extension also.  Will fix soon.
+> For the first point, agreed.  It should probably check that the data file has a `.xml` extension also.  Have now fixed.
 
 > For the second point, I think the main concern would be resource usage.  XSLT is a pretty limited language; it can read other XML files, but it can't run other programs so far as I know.
 
-- 
cgit v1.2.3


From 6eb35262d5c2cd3a9b24029d958cc24743ccd64f Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Tue, 1 Dec 2009 20:55:25 -0500
Subject: clearing up a bit of confusion about who I am

---
 doc/plugins/contrib/xslt.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/xslt.mdwn b/doc/plugins/contrib/xslt.mdwn
index f98f8378d..c30e618ea 100644
--- a/doc/plugins/contrib/xslt.mdwn
+++ b/doc/plugins/contrib/xslt.mdwn
@@ -1,4 +1,4 @@
-[[!template id=plugin name=xslt author="rubykat"]]
+[[!template id=plugin name=xslt author="[[rubykat]]"]]
 ## NAME
 
 IkiWiki::Plugin::xslt - ikiwiki directive to process an XML file with XSLT
-- 
cgit v1.2.3


From 5d68ee9e4e920ef3756c7489fd84eafd1b332f87 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 2 Dec 2009 00:43:47 -0500
Subject: here be a plugin for processing POD!

---
 doc/plugins/contrib/pod.mdwn | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)
 create mode 100644 doc/plugins/contrib/pod.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/pod.mdwn b/doc/plugins/contrib/pod.mdwn
new file mode 100644
index 000000000..648e3b0c2
--- /dev/null
+++ b/doc/plugins/contrib/pod.mdwn
@@ -0,0 +1,35 @@
+## NAME
+
+IkiWiki::Plugin::pod - process pages written in POD format.
+
+## SYNOPSIS
+
+In the ikiwiki setup file, enable this plugin by adding it to the
+list of active plugins.
+
+    add_plugins => [qw{goodstuff pod ....}],
+
+## DESCRIPTION
+
+IkiWiki::Plugin::pod is an IkiWiki plugin enabling ikiwiki to
+process pages written in POD (Plain Old Documentation) format.
+This will treat files with a `.pod` or `.pm` extension as files
+which contain POD markup.
+
+## OPTIONS
+
+The following options can be set in the ikiwiki setup file.
+
+* **pod_index:** If true, this will generate an index (table of contents) for the page.
+* **pod_toplink:** The label to be used for links back to the top of the page.  If this is empty, then no top-links will be generated.
+
+## PREREQUISITES
+
+    IkiWiki
+    Pod::Xhtml
+    IO::String
+
+## DOWNLOAD
+
+* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/pod.pm>
+* git repo at git://github.com/rubykat/ikiplugins.git
-- 
cgit v1.2.3


From 11a6112b561a5624b30cb587a067d35e0098c21d Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 2 Dec 2009 00:45:23 -0500
Subject: added the proper template thingie

---
 doc/plugins/contrib/pod.mdwn | 1 +
 1 file changed, 1 insertion(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/pod.mdwn b/doc/plugins/contrib/pod.mdwn
index 648e3b0c2..5ca1b3347 100644
--- a/doc/plugins/contrib/pod.mdwn
+++ b/doc/plugins/contrib/pod.mdwn
@@ -1,3 +1,4 @@
+[[!template id=plugin name=pod author="[[rubykat]]"]]
 ## NAME
 
 IkiWiki::Plugin::pod - process pages written in POD format.
-- 
cgit v1.2.3


From c4b7d046690a7d35f5f6dc73fcbc83b72bc95f42 Mon Sep 17 00:00:00 2001
From: "http://lj.rossia.org/users/imz/" <http://lj.rossia.org/users/imz/@web>
Date: Wed, 2 Dec 2009 13:08:42 -0500
Subject: minor: a link to describe the  format

---
 doc/plugins/contrib/pod.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/pod.mdwn b/doc/plugins/contrib/pod.mdwn
index 5ca1b3347..dafffa844 100644
--- a/doc/plugins/contrib/pod.mdwn
+++ b/doc/plugins/contrib/pod.mdwn
@@ -13,7 +13,7 @@ list of active plugins.
 ## DESCRIPTION
 
 IkiWiki::Plugin::pod is an IkiWiki plugin enabling ikiwiki to
-process pages written in POD (Plain Old Documentation) format.
+process pages written in POD ([Plain Old Documentation](http://en.wikipedia.org/wiki/Plain_Old_Documentation)) format.
 This will treat files with a `.pod` or `.pm` extension as files
 which contain POD markup.
 
-- 
cgit v1.2.3


From 658da70f6aa52331389566cd1824e8342264dfe5 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Fri, 4 Dec 2009 04:09:44 -0500
Subject: added field plugin

---
 doc/plugins/contrib/field.mdwn | 97 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 doc/plugins/contrib/field.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field.mdwn b/doc/plugins/contrib/field.mdwn
new file mode 100644
index 000000000..f7c2f4b1b
--- /dev/null
+++ b/doc/plugins/contrib/field.mdwn
@@ -0,0 +1,97 @@
+[[!template id=plugin name=pod author="[[rubykat]]"]]
+[[!toc]]
+## NAME
+
+IkiWiki::Plugin::field - front-end for per-page record fields.
+
+## SYNOPSIS
+
+    # activate the plugin
+    add_plugins => [qw{goodstuff field ....}],
+
+    # simple registration
+    field_register => [qw{meta}],
+
+## DESCRIPTION
+
+This plugin is meant to be used in conjunction with other plugins
+in order to provide a uniform interface to access 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.
+
+Plugins can register a function which will return the value of a "field" for
+a given page.  This can be used in three ways:
+
+* In page templates; all registered fields will be passed to the page template in the "pagetemplate" processing.
+* In PageSpecs; the "field" function can be used to match the value of a field in a page.
+* By other plugins, using the field_get_value function, to get the value of a field for a page, and do with it what they will.
+
+## OPTIONS
+
+The following options can be set in the ikiwiki setup file.
+
+**field_register**
+
+A list of plugin-IDs to register.  This assumes that the plugins in
+question store data in the %pagestatus hash using the ID of that plugin,
+and thus the field values are looked for there.
+
+This is the simplest form of registration, but the advantage is that it
+doesn't require the plugin to be modified in order for it to be
+registered with the "field" plugin.
+
+## PageSpec
+
+The "field" PageSpec function can be used to match the value of a field for a page.
+
+field(*name* *glob*)
+
+For example:
+
+field(bar Foo*) will match if the "bar" field starts with "Foo".
+
+## FUNCTIONS
+
+### field_register
+
+field_register(id=>$id);
+
+Register a plugin as having field data.  The above form is the simplest, where the field value
+is looked up in the %pagestatus hash under the plugin-id.
+
+Additional Options:
+
+**call=>&myfunc**
+
+A reference to a function to call rather than just looking up the value in the %pagestatus hash.
+It takes two arguments: the name of the field, and the name of the page.  It is expected to return
+the value of that field, or undef if there is no field by that name.
+
+    sub myfunc ($$) {
+	my $field = shift;
+	my $page = shift;
+
+	...
+
+	return $value;
+    }
+
+**first=>1**
+
+Set this to be called first in the sequence of calls looking for values.  Since the first found
+value is the one which is returned, ordering is significant.
+
+**last=>1**
+
+Set this to be called last in the sequence of calls looking for values.  Since the first found
+value is the one which is returned, ordering is significant.
+
+### field_get_value($field, $page)
+
+Returns the value of the field for that page, or undef if none is found.
+
+## DOWNLOAD
+
+* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/field.pm>
+* git repo at git://github.com/rubykat/ikiplugins.git
-- 
cgit v1.2.3


From 2a4f37b4622bd5ce8e2c153fff2ae5d1d57f57de Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Fri, 4 Dec 2009 04:11:12 -0500
Subject: oops, fixed name

---
 doc/plugins/contrib/field.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field.mdwn b/doc/plugins/contrib/field.mdwn
index f7c2f4b1b..745a36bcd 100644
--- a/doc/plugins/contrib/field.mdwn
+++ b/doc/plugins/contrib/field.mdwn
@@ -1,4 +1,4 @@
-[[!template id=plugin name=pod author="[[rubykat]]"]]
+[[!template id=plugin name=field author="[[rubykat]]"]]
 [[!toc]]
 ## NAME
 
-- 
cgit v1.2.3


From a3803f3cd82af36b77a8ee718f9057515adf05ea Mon Sep 17 00:00:00 2001
From: "http://www.google.com/profiles/schmonz"
 <http://www.google.com/profiles/schmonz@web>
Date: Fri, 11 Dec 2009 21:59:08 -0500
Subject: on my unixauth branch now

---
 doc/plugins/contrib/unixauth.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/unixauth.mdwn b/doc/plugins/contrib/unixauth.mdwn
index 137195139..c97312b59 100644
--- a/doc/plugins/contrib/unixauth.mdwn
+++ b/doc/plugins/contrib/unixauth.mdwn
@@ -1,7 +1,7 @@
 [[!template id=plugin name=unixauth core=0 author="[[schmonz]]"]]
 [[!tag type/auth]]
 
-[[!template id=gitbranch branch=schmonz author="[[schmonz]]"]]
+[[!template id=gitbranch branch=unixauth author="[[schmonz]]"]]
 
 This plugin authenticates users against the Unix user database. It presents a similar UI to [[plugins/passwordauth]], but simpler, as there's no need to be able to register or change one's password.
 
-- 
cgit v1.2.3


From 407a94c6a6d5ea125f5c31787799c864e2c1b7f0 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 23 Dec 2009 15:07:11 +0000
Subject: added tag

---
 doc/plugins/contrib/pod.mdwn | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/pod.mdwn b/doc/plugins/contrib/pod.mdwn
index dafffa844..d6fdf4b63 100644
--- a/doc/plugins/contrib/pod.mdwn
+++ b/doc/plugins/contrib/pod.mdwn
@@ -34,3 +34,6 @@ The following options can be set in the ikiwiki setup file.
 
 * browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/pod.pm>
 * git repo at git://github.com/rubykat/ikiplugins.git
+
+----
+[[!taglink format]]
-- 
cgit v1.2.3


From 85eab3e9ff30ba42307a53bf22ef72ce87e18616 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 23 Dec 2009 15:08:14 +0000
Subject: try again with tag

---
 doc/plugins/contrib/pod.mdwn | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/pod.mdwn b/doc/plugins/contrib/pod.mdwn
index d6fdf4b63..19b0111df 100644
--- a/doc/plugins/contrib/pod.mdwn
+++ b/doc/plugins/contrib/pod.mdwn
@@ -1,4 +1,5 @@
 [[!template id=plugin name=pod author="[[rubykat]]"]]
+[[!tag format]]
 ## NAME
 
 IkiWiki::Plugin::pod - process pages written in POD format.
@@ -35,5 +36,3 @@ The following options can be set in the ikiwiki setup file.
 * browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/pod.pm>
 * git repo at git://github.com/rubykat/ikiplugins.git
 
-----
-[[!taglink format]]
-- 
cgit v1.2.3


From 01e744af0f099fcf28d9cf0bc0f090262c092bdf Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 23 Dec 2009 15:09:59 +0000
Subject: third time lucky?

---
 doc/plugins/contrib/pod.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/pod.mdwn b/doc/plugins/contrib/pod.mdwn
index 19b0111df..97a9c648a 100644
--- a/doc/plugins/contrib/pod.mdwn
+++ b/doc/plugins/contrib/pod.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=pod author="[[rubykat]]"]]
-[[!tag format]]
+[[!tag type/format]]
 ## NAME
 
 IkiWiki::Plugin::pod - process pages written in POD format.
-- 
cgit v1.2.3


From c7e822a4962c36a3f26e1f0413734b2e67e2e607 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 23 Dec 2009 15:13:04 +0000
Subject: added tag

---
 doc/plugins/contrib/field.mdwn | 1 +
 1 file changed, 1 insertion(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field.mdwn b/doc/plugins/contrib/field.mdwn
index 745a36bcd..a43bf24b2 100644
--- a/doc/plugins/contrib/field.mdwn
+++ b/doc/plugins/contrib/field.mdwn
@@ -1,4 +1,5 @@
 [[!template id=plugin name=field author="[[rubykat]]"]]
+[[!tag type/meta]]
 [[!toc]]
 ## NAME
 
-- 
cgit v1.2.3


From c4a2d93115b6a7826b21f13b9d29bd947551c6c6 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 23 Dec 2009 15:14:57 +0000
Subject: added tag

---
 doc/plugins/contrib/xslt.mdwn | 1 +
 1 file changed, 1 insertion(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/xslt.mdwn b/doc/plugins/contrib/xslt.mdwn
index c30e618ea..80c956c58 100644
--- a/doc/plugins/contrib/xslt.mdwn
+++ b/doc/plugins/contrib/xslt.mdwn
@@ -1,4 +1,5 @@
 [[!template id=plugin name=xslt author="[[rubykat]]"]]
+[[!tag type/chrome]]
 ## NAME
 
 IkiWiki::Plugin::xslt - ikiwiki directive to process an XML file with XSLT
-- 
cgit v1.2.3


From 0c89eabcf5a7f9dd881abc8a8cb5f2271ec4e01e Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 13 Jan 2010 00:37:56 +0000
Subject: more options for field configuration, additional pagespec test

---
 doc/plugins/contrib/field.mdwn | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field.mdwn b/doc/plugins/contrib/field.mdwn
index a43bf24b2..09646d28a 100644
--- a/doc/plugins/contrib/field.mdwn
+++ b/doc/plugins/contrib/field.mdwn
@@ -13,6 +13,9 @@ IkiWiki::Plugin::field - front-end for per-page record fields.
     # simple registration
     field_register => [qw{meta}],
 
+    # allow the config to be queried as a field
+    field_allow_config => 1,
+
 ## DESCRIPTION
 
 This plugin is meant to be used in conjunction with other plugins
@@ -32,8 +35,17 @@ a given page.  This can be used in three ways:
 
 The following options can be set in the ikiwiki setup file.
 
+**field_allow_config**
+
+    field_allow_config => 1,
+
+Allow the $config hash to be queried like any other field; the 
+keys of the config hash are the field names.
+
 **field_register**
 
+    field_register => [qw{meta}],
+
 A list of plugin-IDs to register.  This assumes that the plugins in
 question store data in the %pagestatus hash using the ID of that plugin,
 and thus the field values are looked for there.
@@ -46,12 +58,17 @@ registered with the "field" plugin.
 
 The "field" PageSpec function can be used to match the value of a field for a page.
 
-field(*name* *glob*)
+**field(*name* *glob*)**
 
 For example:
 
 field(bar Foo*) will match if the "bar" field starts with "Foo".
 
+**destfield(*name* *glob*)**
+
+is the same, except that it tests the destination page (that is, in cases
+when the source page is being included in another page).
+
 ## FUNCTIONS
 
 ### field_register
-- 
cgit v1.2.3


From 9ccd1ba41bff43c1a5d06197b454c8748224e30f Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 13 Jan 2010 02:20:34 +0000
Subject: ymlfront: backend for structured data

---
 doc/plugins/contrib/ymlfront.mdwn | 99 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 doc/plugins/contrib/ymlfront.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/ymlfront.mdwn b/doc/plugins/contrib/ymlfront.mdwn
new file mode 100644
index 000000000..f4438f23c
--- /dev/null
+++ b/doc/plugins/contrib/ymlfront.mdwn
@@ -0,0 +1,99 @@
+[[!template id=plugin name=ymlfront author="[[rubykat]]"]]
+[[!tag type/meta]]
+[[!toc]]
+## NAME
+
+IkiWiki::Plugin::ymlfront - add YAML-format data to a page
+
+## SYNOPSIS
+
+    # activate the plugin
+    add_plugins => [qw{goodstuff ymlfront ....}],
+
+## 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.
+
+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.
+
+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.
+
+### Accessing the Data
+
+There are three ways to access the data given in the YAML section.
+
+* [[getfield]] plugin
+
+  The **getfield** plugin can display the data as individual variable values.
+
+  For example:
+
+    	---
+    	title: Foo does not work
+    	Urgency: High
+    	Status: Assigned
+    	AssignedTo: Fred Nurk
+    	Version: 1.2.3
+    	---
+    	# {{$title}}
+
+    	**Urgency:** {{$Urgency}}\\
+    	**Status:** {{$Status}}\\
+    	**Assigned To:** {{$AssignedTo}}\\
+    	**Version:** {{$Version}}
+
+    When running on the Sprongle system, the Foo function returns incorrect data.
+
+* [[ftemplate]] plugin
+
+  The **ftemplate** plugin is like the [[plugins/template]] plugin, but it is also aware of [[field]] values.
+
+  For example:
+
+    	---
+    	title: Foo does not work
+    	Urgency: High
+    	Status: Assigned
+    	AssignedTo: Fred Nurk
+    	Version: 1.2.3
+    	---
+    	\[[!ftemplate id="bug_display_template"]]
+
+    	When running on the Sprongle system, the Foo function returns incorrect data.
+
+* write your own plugin
+
+  In conjunction with the [[field]] plugin, you can write your own plugin to access the data.
+
+## PREREQUISITES
+
+    IkiWiki
+    IkiWiki::Plugin::field
+    YAML::Any
+
+## DOWNLOAD
+
+* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/ymlfront.pm>
+* git repo at git://github.com/rubykat/ikiplugins.git
-- 
cgit v1.2.3


From ccc8e8868269bf2751596e04f792c388acb85c12 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 13 Jan 2010 02:27:59 +0000
Subject: getfield: query field (meta-data) values

---
 doc/plugins/contrib/getfield.mdwn | 85 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 doc/plugins/contrib/getfield.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/getfield.mdwn b/doc/plugins/contrib/getfield.mdwn
new file mode 100644
index 000000000..ed03dc439
--- /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
-- 
cgit v1.2.3


From 7d997f1007b240c14c04ff73b09a2a62fa3e64ad Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 13 Jan 2010 02:36:28 +0000
Subject: ftemplate: field-aware structured template plugin

---
 doc/plugins/contrib/ftemplate.mdwn | 94 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 doc/plugins/contrib/ftemplate.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/ftemplate.mdwn b/doc/plugins/contrib/ftemplate.mdwn
new file mode 100644
index 000000000..bcc6f2c67
--- /dev/null
+++ b/doc/plugins/contrib/ftemplate.mdwn
@@ -0,0 +1,94 @@
+[[!template id=plugin name=ftemplate author="[[rubykat]]"]]
+[[!tag type/meta type/format]]
+[[!toc]]
+## NAME
+
+IkiWiki::Plugin::ftemplate - field-aware structured template plugin
+
+## SYNOPSIS
+
+    # activate the plugin
+    add_plugins => [qw{goodstuff ftemplate ....}],
+
+## DESCRIPTION
+
+This plugin provides the **ftemplate** directive.  This is like
+the [[ikiwiki/directive/template]] directive, with the addition that one does not
+have to provide all the values in the call to the template,
+because ftemplate can query structured data ("fields") using
+the [[field]] plugin.
+
+Templates are files that can be filled out and inserted into pages in
+the wiki, by using the ftemplate directive. The directive has an id
+parameter that identifies the template to use.
+
+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 is, as with the
+[[plugins/template]] plugin, 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.
+
+### EXAMPLES
+
+#### Example 1
+
+PageA:
+
+    [[!meta title="I Am Page A"]]
+    [[!meta description="A is for Apple."]]
+    [[!meta author="Fred Nurk"]]
+    [[!ftemplate id="mytemplate"]]
+
+Template "mytemplate":
+
+    # <TMPL_VAR NAME="TITLE">
+    by <TMPL_VAR NAME="AUTHOR">
+
+    **Summary:** <TMPL_VAR NAME="DESCRIPTION">
+
+This will give:
+
+    <h1>I Am Page A</h1>
+    <p>by Fred Nurk</p>
+    <p><strong>Summary:</strong> A is for Apple.
+
+#### Example 2: Overriding values
+
+PageB:
+
+    [[!meta title="I Am Page B"]]
+    [[!meta description="B is for Banana."]]
+    [[!meta author="Fred Nurk"]]
+    [[!ftemplate id="mytemplate" title="Bananananananas"]]
+
+This will give:
+
+    <h1>Bananananananas</h1>
+    <p>by Fred Nurk</p>
+    <p><strong>Summary:</strong> B is for Banana.
+
+### LIMITATIONS
+
+One cannot query the values of fields on pages other than the current
+page.
+
+## PREREQUISITES
+
+    IkiWiki
+    IkiWiki::Plugin::field
+    HTML::Template
+    Encode
+
+## DOWNLOAD
+
+* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/ftemplate.pm>
+* git repo at git://github.com/rubykat/ikiplugins.git
-- 
cgit v1.2.3


From a3527672769b93eeb4a70fbe9f316c986706c375 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 13 Jan 2010 02:37:27 +0000
Subject: fixed title

---
 doc/plugins/contrib/ftemplate.mdwn | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/ftemplate.mdwn b/doc/plugins/contrib/ftemplate.mdwn
index bcc6f2c67..fba51e1c2 100644
--- a/doc/plugins/contrib/ftemplate.mdwn
+++ b/doc/plugins/contrib/ftemplate.mdwn
@@ -43,10 +43,10 @@ them work as wiki pages.
 
 PageA:
 
-    [[!meta title="I Am Page A"]]
-    [[!meta description="A is for Apple."]]
-    [[!meta author="Fred Nurk"]]
-    [[!ftemplate id="mytemplate"]]
+    \[[!meta title="I Am Page A"]]
+    \[[!meta description="A is for Apple."]]
+    \[[!meta author="Fred Nurk"]]
+    \[[!ftemplate id="mytemplate"]]
 
 Template "mytemplate":
 
@@ -65,10 +65,10 @@ This will give:
 
 PageB:
 
-    [[!meta title="I Am Page B"]]
-    [[!meta description="B is for Banana."]]
-    [[!meta author="Fred Nurk"]]
-    [[!ftemplate id="mytemplate" title="Bananananananas"]]
+    \[[!meta title="I Am Page B"]]
+    \[[!meta description="B is for Banana."]]
+    \[[!meta author="Fred Nurk"]]
+    \[[!ftemplate id="mytemplate" title="Bananananananas"]]
 
 This will give:
 
-- 
cgit v1.2.3


From 2cbf60a431d41b3cb0767f1c0fb1ecf50103bcb0 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 13 Jan 2010 02:38:33 +0000
Subject: correcting link

---
 doc/plugins/contrib/getfield.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/getfield.mdwn b/doc/plugins/contrib/getfield.mdwn
index ed03dc439..5e6b01113 100644
--- a/doc/plugins/contrib/getfield.mdwn
+++ b/doc/plugins/contrib/getfield.mdwn
@@ -81,5 +81,5 @@ page or the destination page.
 
 ## DOWNLOAD
 
-* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/field.pm>
+* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/getfield.pm>
 * git repo at git://github.com/rubykat/ikiplugins.git
-- 
cgit v1.2.3


From f90827f29bc1682bf3682375972f5cc836049dc7 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 13 Jan 2010 02:47:59 +0000
Subject: this is sort of format too

---
 doc/plugins/contrib/getfield.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/getfield.mdwn b/doc/plugins/contrib/getfield.mdwn
index 5e6b01113..302569f4b 100644
--- a/doc/plugins/contrib/getfield.mdwn
+++ b/doc/plugins/contrib/getfield.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=getfield author="[[rubykat]]"]]
-[[!tag type/meta]]
+[[!tag type/meta type/format]]
 [[!toc]]
 ## NAME
 
-- 
cgit v1.2.3


From a1138ae820d3ea121cbd28552a3300631179b0a5 Mon Sep 17 00:00:00 2001
From: simonraven <simonraven@web>
Date: Sat, 16 Jan 2010 05:19:42 +0000
Subject: the pod bold thingy didn't work, making it a markdown one

---
 doc/plugins/contrib/getfield.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/getfield.mdwn b/doc/plugins/contrib/getfield.mdwn
index 302569f4b..929f70485 100644
--- a/doc/plugins/contrib/getfield.mdwn
+++ b/doc/plugins/contrib/getfield.mdwn
@@ -18,7 +18,7 @@ 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.
+This plugin is meant to be used in conjunction with the **field** plugin.
 
 ### USAGE
 
-- 
cgit v1.2.3


From 353f722dc439a14d7e74dab9ca2818f955ff4d41 Mon Sep 17 00:00:00 2001
From: simonraven <simonraven@web>
Date: Sat, 16 Jan 2010 05:29:53 +0000
Subject:

---
 doc/plugins/contrib/getfield/discussion.mdwn | 3 +++
 1 file changed, 3 insertions(+)
 create mode 100644 doc/plugins/contrib/getfield/discussion.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/getfield/discussion.mdwn b/doc/plugins/contrib/getfield/discussion.mdwn
new file mode 100644
index 000000000..61b9f5378
--- /dev/null
+++ b/doc/plugins/contrib/getfield/discussion.mdwn
@@ -0,0 +1,3 @@
+## Templating, and other uses
+
+Like you mentioned in [[ftemplate]] IIRC, it'll only work on the same page. If it can be made to work anywhere, or from a specific place in the wiki - configurable, possibly - you'll have something very similar to mediawiki's templates. I can already think of a few uses for this combined with [[template]] ;) . --[[SR|users/simonraven]]
-- 
cgit v1.2.3


From 3b2772967fdb125bb8160f968729681b7af13269 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Sat, 16 Jan 2010 08:08:46 +0000
Subject: responded to discussion

---
 doc/plugins/contrib/getfield/discussion.mdwn | 9 +++++++++
 1 file changed, 9 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/getfield/discussion.mdwn b/doc/plugins/contrib/getfield/discussion.mdwn
index 61b9f5378..78462197a 100644
--- a/doc/plugins/contrib/getfield/discussion.mdwn
+++ b/doc/plugins/contrib/getfield/discussion.mdwn
@@ -1,3 +1,12 @@
 ## Templating, and other uses
 
 Like you mentioned in [[ftemplate]] IIRC, it'll only work on the same page. If it can be made to work anywhere, or from a specific place in the wiki - configurable, possibly - you'll have something very similar to mediawiki's templates. I can already think of a few uses for this combined with [[template]] ;) . --[[SR|users/simonraven]]
+
+> Yes, I mentioned "only current page" in the "LIMITATIONS" section.
+
+> What do you think would be a good syntax for querying other pages?
+> It needs to resolve to a single page, though I guess using "bestlink" to find the closest page would mean that one didn't have to spell out the whole page.
+
+> I'm also working on a "report" plugin, which will basically apply a template like [[ftemplate]] does, but to a list of pages given from a pagespec, rather than the current page.
+
+> -- [[users/KathrynAndersen]]
-- 
cgit v1.2.3


From e3a09318a0686a7e3d01206f56ca6019c3c198e0 Mon Sep 17 00:00:00 2001
From: simonraven <simonraven@web>
Date: Sat, 16 Jan 2010 08:42:56 +0000
Subject:

---
 doc/plugins/contrib/getfield/discussion.mdwn | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/getfield/discussion.mdwn b/doc/plugins/contrib/getfield/discussion.mdwn
index 78462197a..f3c844e94 100644
--- a/doc/plugins/contrib/getfield/discussion.mdwn
+++ b/doc/plugins/contrib/getfield/discussion.mdwn
@@ -7,6 +7,10 @@ Like you mentioned in [[ftemplate]] IIRC, it'll only work on the same page. If i
 > What do you think would be a good syntax for querying other pages?
 > It needs to resolve to a single page, though I guess using "bestlink" to find the closest page would mean that one didn't have to spell out the whole page.
 
+>> I don't know the internals very well, I think that's how other plugins do it. *goes to check* Usually it's a `foreach` loop, and use a `pagestate{foo}` to check the page's status/state. There's also some stuff like 'pagespec_match_list($params{page}` ... they do slightly different thing depending on need. --[[SR|users/simonraven]]
+
 > I'm also working on a "report" plugin, which will basically apply a template like [[ftemplate]] does, but to a list of pages given from a pagespec, rather than the current page.
 
 > -- [[users/KathrynAndersen]]
+
+>> Ooh, sounds nice :) . --[[SR|users/simonraven]]
-- 
cgit v1.2.3


From 354468d280354234d9c8c91333534c9784f427cf Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Sun, 17 Jan 2010 00:10:55 +0000
Subject: respond: markup, not internals

---
 doc/plugins/contrib/getfield/discussion.mdwn | 5 +++++
 1 file changed, 5 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/getfield/discussion.mdwn b/doc/plugins/contrib/getfield/discussion.mdwn
index f3c844e94..37d65d851 100644
--- a/doc/plugins/contrib/getfield/discussion.mdwn
+++ b/doc/plugins/contrib/getfield/discussion.mdwn
@@ -9,6 +9,11 @@ Like you mentioned in [[ftemplate]] IIRC, it'll only work on the same page. If i
 
 >> I don't know the internals very well, I think that's how other plugins do it. *goes to check* Usually it's a `foreach` loop, and use a `pagestate{foo}` to check the page's status/state. There's also some stuff like 'pagespec_match_list($params{page}` ... they do slightly different thing depending on need. --[[SR|users/simonraven]]
 
+>>> No, I meant what markup I should use; the actual implementation probably wouldn't be too difficult.
+
+>>> The current markup is {{$*fieldname*}}; what you're wanting, perhaps it should be represented like {{$*pagename*:*fieldname*}}, or {{$*pagename*::*fieldname*}} or something else...
+>>> -- [[KathrynAndersen]]
+
 > I'm also working on a "report" plugin, which will basically apply a template like [[ftemplate]] does, but to a list of pages given from a pagespec, rather than the current page.
 
 > -- [[users/KathrynAndersen]]
-- 
cgit v1.2.3


From b3363aa89f840fd42b8a621b011326ef41b73513 Mon Sep 17 00:00:00 2001
From: simonraven <simonraven@web>
Date: Sun, 17 Jan 2010 09:28:07 +0000
Subject:

---
 doc/plugins/contrib/getfield/discussion.mdwn | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/getfield/discussion.mdwn b/doc/plugins/contrib/getfield/discussion.mdwn
index 37d65d851..9f1337046 100644
--- a/doc/plugins/contrib/getfield/discussion.mdwn
+++ b/doc/plugins/contrib/getfield/discussion.mdwn
@@ -14,6 +14,8 @@ Like you mentioned in [[ftemplate]] IIRC, it'll only work on the same page. If i
 >>> The current markup is {{$*fieldname*}}; what you're wanting, perhaps it should be represented like {{$*pagename*:*fieldname*}}, or {{$*pagename*::*fieldname*}} or something else...
 >>> -- [[KathrynAndersen]]
 
+>>>> Oh. Hmm. I like your idea actually, or alternately, in keeping more with other plugins, doing it like {{pagename/fieldname}}. The meaning is less clear that way, but avoids potential issues with filename clashes that have a colon in them. It also keeps a certain logic - at least to me. Either way, I think both are good choices.
+
 > I'm also working on a "report" plugin, which will basically apply a template like [[ftemplate]] does, but to a list of pages given from a pagespec, rather than the current page.
 
 > -- [[users/KathrynAndersen]]
-- 
cgit v1.2.3


From 2137d1f68c694af6135d0d84b59bbfbcffe36669 Mon Sep 17 00:00:00 2001
From: simonraven <simonraven@web>
Date: Sun, 17 Jan 2010 09:31:07 +0000
Subject:

---
 doc/plugins/contrib/getfield/discussion.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/getfield/discussion.mdwn b/doc/plugins/contrib/getfield/discussion.mdwn
index 9f1337046..42338a3c7 100644
--- a/doc/plugins/contrib/getfield/discussion.mdwn
+++ b/doc/plugins/contrib/getfield/discussion.mdwn
@@ -14,7 +14,7 @@ Like you mentioned in [[ftemplate]] IIRC, it'll only work on the same page. If i
 >>> The current markup is {{$*fieldname*}}; what you're wanting, perhaps it should be represented like {{$*pagename*:*fieldname*}}, or {{$*pagename*::*fieldname*}} or something else...
 >>> -- [[KathrynAndersen]]
 
->>>> Oh. Hmm. I like your idea actually, or alternately, in keeping more with other plugins, doing it like {{pagename/fieldname}}. The meaning is less clear that way, but avoids potential issues with filename clashes that have a colon in them. It also keeps a certain logic - at least to me. Either way, I think both are good choices.
+>>>> Oh. Hmm. I like your idea actually, or alternately, in keeping more with other plugins, doing it like {{pagename/fieldname}}. The meaning of the separator is less clear with /, but avoids potential issues with filename clashes that have a colon in them. It also keeps a certain logic - at least to me. Either way, I think both are good choices. [[SR|users/simonraven]]
 
 > I'm also working on a "report" plugin, which will basically apply a template like [[ftemplate]] does, but to a list of pages given from a pagespec, rather than the current page.
 
-- 
cgit v1.2.3


From fa0bbaab21a456f8115d9af508fef06443b8d275 Mon Sep 17 00:00:00 2001
From: "http://oblomov.myopenid.com/" <http://oblomov.myopenid.com/@web>
Date: Sun, 17 Jan 2010 09:56:26 +0000
Subject: Suggest # as page-field separator

---
 doc/plugins/contrib/getfield/discussion.mdwn | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/getfield/discussion.mdwn b/doc/plugins/contrib/getfield/discussion.mdwn
index 42338a3c7..900ca65b2 100644
--- a/doc/plugins/contrib/getfield/discussion.mdwn
+++ b/doc/plugins/contrib/getfield/discussion.mdwn
@@ -16,6 +16,9 @@ Like you mentioned in [[ftemplate]] IIRC, it'll only work on the same page. If i
 
 >>>> Oh. Hmm. I like your idea actually, or alternately, in keeping more with other plugins, doing it like {{pagename/fieldname}}. The meaning of the separator is less clear with /, but avoids potential issues with filename clashes that have a colon in them. It also keeps a certain logic - at least to me. Either way, I think both are good choices. [[SR|users/simonraven]]
 
+>>>>> What about using {{pagename#fieldname}}? The meaning of the hash in URLs sort of fits with what is needed here (reference to a 'named' thing within the page) and it won't conflict with actual hash usages (unless we expect different named parts of pages to define different values for the same field ...)
+>>>>> -- [[Oblomov]]
+
 > I'm also working on a "report" plugin, which will basically apply a template like [[ftemplate]] does, but to a list of pages given from a pagespec, rather than the current page.
 
 > -- [[users/KathrynAndersen]]
-- 
cgit v1.2.3


From 9c0c8b57fb9ccaf21888a7eb9e93dc0d312773e0 Mon Sep 17 00:00:00 2001
From: simonraven <simonraven@web>
Date: Sun, 17 Jan 2010 17:27:51 +0000
Subject:

---
 doc/plugins/contrib/getfield/discussion.mdwn | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/getfield/discussion.mdwn b/doc/plugins/contrib/getfield/discussion.mdwn
index 900ca65b2..ce6246034 100644
--- a/doc/plugins/contrib/getfield/discussion.mdwn
+++ b/doc/plugins/contrib/getfield/discussion.mdwn
@@ -18,6 +18,8 @@ Like you mentioned in [[ftemplate]] IIRC, it'll only work on the same page. If i
 
 >>>>> What about using {{pagename#fieldname}}? The meaning of the hash in URLs sort of fits with what is needed here (reference to a 'named' thing within the page) and it won't conflict with actual hash usages (unless we expect different named parts of pages to define different values for the same field ...)
 >>>>> -- [[Oblomov]]
+>>>>>> That's a good one too. --[[simonraven]]
+
 
 > I'm also working on a "report" plugin, which will basically apply a template like [[ftemplate]] does, but to a list of pages given from a pagespec, rather than the current page.
 
-- 
cgit v1.2.3


From bcde9b74120d0572d41447d798917ae02134e059 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Sun, 24 Jan 2010 02:52:57 +0000
Subject: new report plugin

---
 doc/plugins/contrib/report.mdwn | 166 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 166 insertions(+)
 create mode 100644 doc/plugins/contrib/report.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/report.mdwn b/doc/plugins/contrib/report.mdwn
new file mode 100644
index 000000000..7130bcb5f
--- /dev/null
+++ b/doc/plugins/contrib/report.mdwn
@@ -0,0 +1,166 @@
+[[!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 "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
+
+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"]]
+
+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.
+
+## PREREQUISITES
+
+    IkiWiki
+    IkiWiki::Plugin::field
+    HTML::Template
+    Encode
+
+## DOWNLOAD
+
+* browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/report.pm>
+* git repo at git://github.com/rubykat/ikiplugins.git
-- 
cgit v1.2.3


From 27d2d7115df82908396d460d92857fd0990c556d Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Sun, 24 Jan 2010 02:59:11 +0000
Subject: note that report is now released

---
 doc/plugins/contrib/getfield/discussion.mdwn | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/getfield/discussion.mdwn b/doc/plugins/contrib/getfield/discussion.mdwn
index ce6246034..015e9f5a1 100644
--- a/doc/plugins/contrib/getfield/discussion.mdwn
+++ b/doc/plugins/contrib/getfield/discussion.mdwn
@@ -26,3 +26,6 @@ Like you mentioned in [[ftemplate]] IIRC, it'll only work on the same page. If i
 > -- [[users/KathrynAndersen]]
 
 >> Ooh, sounds nice :) . --[[SR|users/simonraven]]
+
+>>> I've now released the [[plugins/contrib/report]] plugin.  I've been using it on my site; the holdup on releasing was because I hadn't yet written the docs for it. I hope you find it useful.
+>>> -- [[users/KathrynAndersen]]
-- 
cgit v1.2.3


From f6b2edef642ccda83a4c96aeeb2e146202707a67 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Sun, 24 Jan 2010 09:38:40 +0000
Subject: new release of getfield; can now get values from other pages as well
 as current page

---
 doc/plugins/contrib/getfield.mdwn | 60 ++++++++++++++++++++++++++++++++++-----
 1 file changed, 53 insertions(+), 7 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/getfield.mdwn b/doc/plugins/contrib/getfield.mdwn
index 929f70485..0a92894f1 100644
--- a/doc/plugins/contrib/getfield.mdwn
+++ b/doc/plugins/contrib/getfield.mdwn
@@ -18,13 +18,13 @@ 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 **field** plugin.
+This plugin is meant to be used in conjunction with the [[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:
+use the markup inside other directives.  There are four forms:
 
 * {{$*fieldname*}}
 
@@ -39,6 +39,26 @@ use the markup inside other directives.  There are two forms:
 
     	<h1>My Long and Complicated Title With Potential For Spelling Mistakes</h1>
 
+* {{$*pagename*#*fieldname*}}
+
+  This queries the value of *fieldname* for the page *pagename*.
+
+  For example:
+
+  On PageFoo:
+
+    \[[!meta title="I Am Page Foo"]]
+
+    Stuff about Foo.
+
+  On PageBar:
+
+    For more info, see \[[{{$PageFoo#title}}|PageFoo]].
+
+  When PageBar is displayed:
+
+    &lt;p&gt;For more info, see &lt;a href="PageFoo"&gt;I Am Page Foo&lt;/a&gt;.&lt;/p&gt;
+
 * {{+$*fieldname*+}}
 
   This queries the value of *fieldname* for the destination page; that is,
@@ -68,17 +88,43 @@ use the markup inside other directives.  There are two forms:
     	<h1>I Am Page B</h1>
     	<p>Stuff about A.</p>
 
+* {{+$*pagename*#*fieldname*+}}
+
+  This queries the value of *fieldname* for the page *pagename*; the
+  only difference between this and {{$*pagename*#*fieldname*}} is
+  that the full name of *pagename* is calculated relative to the
+  destination page rather than the source page.
+
+  I can't really think of a reason why this should be needed, but
+  this format has been added for completeness.
+
+### No Value Found
+
+If no value is found for the given field, then the field name is returned.
+
+For example:
+
+On PageFoo:
+
+    \[[!meta title="Foo"]]
+    My title is {{$title}}.
+    
+    My description is {{$description}}.
+
+When PageFoo is displayed:
+
+    <p>My title is Foo.</p>
+    
+    <p>My description is description.</p>
+
+This is because "description" hasn't been defined for that page.
+
 ### 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/getfield.pm>
-- 
cgit v1.2.3


From e9ee3d7d85e792ee6720696abe62f25cdd7f945a Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Sun, 24 Jan 2010 09:41:44 +0000
Subject: note new version of getfield

---
 doc/plugins/contrib/getfield/discussion.mdwn | 1 +
 1 file changed, 1 insertion(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/getfield/discussion.mdwn b/doc/plugins/contrib/getfield/discussion.mdwn
index 015e9f5a1..5f7fffead 100644
--- a/doc/plugins/contrib/getfield/discussion.mdwn
+++ b/doc/plugins/contrib/getfield/discussion.mdwn
@@ -19,6 +19,7 @@ Like you mentioned in [[ftemplate]] IIRC, it'll only work on the same page. If i
 >>>>> What about using {{pagename#fieldname}}? The meaning of the hash in URLs sort of fits with what is needed here (reference to a 'named' thing within the page) and it won't conflict with actual hash usages (unless we expect different named parts of pages to define different values for the same field ...)
 >>>>> -- [[Oblomov]]
 >>>>>> That's a good one too. --[[simonraven]]
+>>>>>>> Done!  I used {{$*pagename*#*fieldname*}} for the format. -- [[users/KathrynAndersen]]
 
 
 > I'm also working on a "report" plugin, which will basically apply a template like [[ftemplate]] does, but to a list of pages given from a pagespec, rather than the current page.
-- 
cgit v1.2.3


From 04a99c84406d7b1552b15fc0b5ea598644f94c23 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@gnu.kitenet.net>
Date: Fri, 12 Feb 2010 03:38:00 -0500
Subject: plugin tag reorg

---
 doc/plugins/404.mdwn            |  2 +-
 doc/plugins/aggregate.mdwn      |  2 +-
 doc/plugins/autoindex.mdwn      |  2 +-
 doc/plugins/calendar.mdwn       |  2 +-
 doc/plugins/color.mdwn          |  2 +-
 doc/plugins/comments.mdwn       |  2 +-
 doc/plugins/contrib/postal.mdwn |  2 +-
 doc/plugins/cutpaste.mdwn       |  2 +-
 doc/plugins/ddate.mdwn          |  1 +
 doc/plugins/filecheck.mdwn      |  2 +-
 doc/plugins/format.mdwn         |  2 +-
 doc/plugins/fortune.mdwn        |  1 +
 doc/plugins/goto.mdwn           |  2 +-
 doc/plugins/graphviz.mdwn       |  2 +-
 doc/plugins/haiku.mdwn          |  1 +
 doc/plugins/img.mdwn            |  2 +-
 doc/plugins/mirrorlist.mdwn     |  2 +-
 doc/plugins/more.mdwn           |  2 +-
 doc/plugins/poll.mdwn           |  2 +-
 doc/plugins/polygen.mdwn        |  1 +
 doc/plugins/prettydate.mdwn     |  1 +
 doc/plugins/relativedate.mdwn   |  1 +
 doc/plugins/repolist.mdwn       |  2 +-
 doc/plugins/shortcut.mdwn       |  2 +-
 doc/plugins/sparkline.mdwn      |  2 +-
 doc/plugins/table.mdwn          |  2 +-
 doc/plugins/template.mdwn       |  2 +-
 doc/plugins/testpagespec.mdwn   |  2 +-
 doc/plugins/teximg.mdwn         |  2 +-
 doc/plugins/toc.mdwn            |  2 +-
 doc/plugins/toggle.mdwn         |  2 +-
 doc/plugins/type/chrome.mdwn    |  2 +-
 doc/plugins/type/useful.mdwn    |  1 -
 doc/plugins/type/widget.mdwn    |  2 ++
 doc/plugins/underlay.mdwn       | 18 +++++++++---------
 doc/plugins/wmd.mdwn            |  2 +-
 36 files changed, 44 insertions(+), 37 deletions(-)
 delete mode 100644 doc/plugins/type/useful.mdwn
 create mode 100644 doc/plugins/type/widget.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/404.mdwn b/doc/plugins/404.mdwn
index ad332ee04..53dace3c9 100644
--- a/doc/plugins/404.mdwn
+++ b/doc/plugins/404.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=404 author="[[Simon_McVittie|smcv]]"]]
-[[!tag type/useful]]
+[[!tag type/web]]
 
 This plugin lets you use the IkiWiki CGI script as an Apache 404 handler,
 to give the behaviour of various other wiki engines where visiting a
diff --git a/doc/plugins/aggregate.mdwn b/doc/plugins/aggregate.mdwn
index e2efcd83f..bb828b05c 100644
--- a/doc/plugins/aggregate.mdwn
+++ b/doc/plugins/aggregate.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=aggregate author="[[Joey]]"]]
-[[!tag type/useful]]
+[[!tag type/special-purpose]]
 
 This plugin allows content from other feeds to be aggregated into the
 wiki. To specify feeds to aggregate, use the
diff --git a/doc/plugins/autoindex.mdwn b/doc/plugins/autoindex.mdwn
index 03e2d12f3..d1133e4f5 100644
--- a/doc/plugins/autoindex.mdwn
+++ b/doc/plugins/autoindex.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=autoindex core=0 author="[[Joey]]"]]
-[[!tag type/useful]]
+[[!tag type/special-purpose]]
 
 This plugin searches for [[SubPages|ikiwiki/subpage]] with a missing parent
 page, and generates the parent pages. The generated page content is
diff --git a/doc/plugins/calendar.mdwn b/doc/plugins/calendar.mdwn
index bc1bc6c71..49fd90627 100644
--- a/doc/plugins/calendar.mdwn
+++ b/doc/plugins/calendar.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=calendar author="[[ManojSrivastava]]"]]
-[[!tag type/chrome]]
+[[!tag type/widget]]
 
 This plugin provides a [[ikiwiki/directive/calendar]] [[ikiwiki/directive]].
 The directive displays a calendar, similar to the typical calendars shown on
diff --git a/doc/plugins/color.mdwn b/doc/plugins/color.mdwn
index dbb8b870c..d639bf563 100644
--- a/doc/plugins/color.mdwn
+++ b/doc/plugins/color.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=color core=0 author="[[ptecza]]"]]
-[[!tag type/chrome]]
+[[!tag type/widget]]
 
 This plugin provides a [[ikiwiki/directive/color]] [[ikiwiki/directive]].
 The directive can be used to color a piece of text on a page.
diff --git a/doc/plugins/comments.mdwn b/doc/plugins/comments.mdwn
index f933d32be..775ef75a0 100644
--- a/doc/plugins/comments.mdwn
+++ b/doc/plugins/comments.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=comments author="[[Simon_McVittie|smcv]]"]]
-[[!tag type/useful]]
+[[!tag type/web]]
 
 This plugin adds "blog-style" comments. Unlike the wiki-style freeform 
 Discussion pages, these comments are posted by a simple form, cannot later
diff --git a/doc/plugins/contrib/postal.mdwn b/doc/plugins/contrib/postal.mdwn
index b2f875393..c522f8bcb 100644
--- a/doc/plugins/contrib/postal.mdwn
+++ b/doc/plugins/contrib/postal.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=postal author="[[DavidBremner]]"]]
-[[!tag type/useful]]
+[[!tag type/special-purpose]]
 
 The `postal` plugin allows users to send mail to
 a special address to comment on a page. It uses the [[mailbox]]
diff --git a/doc/plugins/cutpaste.mdwn b/doc/plugins/cutpaste.mdwn
index f74f8a269..ea3665c44 100644
--- a/doc/plugins/cutpaste.mdwn
+++ b/doc/plugins/cutpaste.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=cutpaste author="[[Enrico]]"]]
-[[!tag type/chrome]]
+[[!tag type/widget]]
 
 This plugin provides the [[ikiwiki/directive/cut]],
 [[ikiwiki/directive/copy]] and [[ikiwiki/directive/paste]]
diff --git a/doc/plugins/ddate.mdwn b/doc/plugins/ddate.mdwn
index 741606a6e..17bb16cff 100644
--- a/doc/plugins/ddate.mdwn
+++ b/doc/plugins/ddate.mdwn
@@ -1,6 +1,7 @@
 [[!template id=plugin name=ddate author="[[Joey]]"]]
 [[!tag type/fun]]
 [[!tag type/date]]
+[[!tag type/chrome]]
 
 Enables use of Discordian dates. `--timeformat` can be used to change
 the date format; see `ddate(1)`.
diff --git a/doc/plugins/filecheck.mdwn b/doc/plugins/filecheck.mdwn
index f4563d58e..e5f68b29c 100644
--- a/doc/plugins/filecheck.mdwn
+++ b/doc/plugins/filecheck.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=filecheck core=0 author="[[Joey]]"]]
-[[!tag type/useful]]
+[[!tag type/special-purpose]]
 
 This plugin enhances the regular [[ikiwiki/PageSpec]] syntax with
 some additional tests, for things like file size, mime type, and virus
diff --git a/doc/plugins/format.mdwn b/doc/plugins/format.mdwn
index 5ec0842ae..b41d365aa 100644
--- a/doc/plugins/format.mdwn
+++ b/doc/plugins/format.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=format core=0 author="[[Joey]]"]]
-[[!tag type/useful]]
+[[!tag type/widget]]
 
 This plugin allows mixing different page formats together, by embedding
 text formatted one way inside a page formatted another way. This is done
diff --git a/doc/plugins/fortune.mdwn b/doc/plugins/fortune.mdwn
index 9966f456d..3cb125ac1 100644
--- a/doc/plugins/fortune.mdwn
+++ b/doc/plugins/fortune.mdwn
@@ -1,5 +1,6 @@
 [[!template id=plugin name=fortune author="[[Joey]]"]]
 [[!tag type/fun]]
+[[!tag type/widget]]
 
 This plugin implements the [[ikiwiki/directive/fortune]] [[ikiwiki/directive]].
 This directive  uses the `fortune` program to insert a fortune into the page.
diff --git a/doc/plugins/goto.mdwn b/doc/plugins/goto.mdwn
index 9c401c5d2..8e1de7a10 100644
--- a/doc/plugins/goto.mdwn
+++ b/doc/plugins/goto.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=goto author="[[Simon_McVittie|smcv]]"]]
-[[!tag type/useful]]
+[[!tag type/web]]
 
 This plugin adds a `do=goto` mode for the IkiWiki CGI script. It's mainly
 for internal use by the [[404]], [[comments]] and [[recentchanges]]
diff --git a/doc/plugins/graphviz.mdwn b/doc/plugins/graphviz.mdwn
index 8237ae9dc..65130ae8c 100644
--- a/doc/plugins/graphviz.mdwn
+++ b/doc/plugins/graphviz.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=graphviz author="[[JoshTriplett]]"]]
-[[!tag type/chrome]]
+[[!tag type/widget]]
 
 This plugin provides the [[ikiwiki/directive/graph]] [[ikiwiki/directive]].
 This directive allows embedding [graphviz](http://www.graphviz.org/) graphs in a
diff --git a/doc/plugins/haiku.mdwn b/doc/plugins/haiku.mdwn
index 74eac1c29..448733d95 100644
--- a/doc/plugins/haiku.mdwn
+++ b/doc/plugins/haiku.mdwn
@@ -1,5 +1,6 @@
 [[!template id=plugin name=haiku author="[[Joey]]"]]
 [[!tag type/fun]]
+[[!tag type/widget]]
 
 This plugin provides a [[ikiwiki/directive/haiku]] [[ikiwiki/directive]].
 The directive allows inserting a randomly generated haiku into a wiki page.
diff --git a/doc/plugins/img.mdwn b/doc/plugins/img.mdwn
index 114438765..a6cd90f28 100644
--- a/doc/plugins/img.mdwn
+++ b/doc/plugins/img.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=img author="Christian Mock"]]
-[[!tag type/chrome]]
+[[!tag type/widget]]
 
 This plugin provides the [[ikiwiki/directive/img]] [[ikiwiki/directive]].
 While ikiwiki supports inlining full-size images by making a
diff --git a/doc/plugins/mirrorlist.mdwn b/doc/plugins/mirrorlist.mdwn
index b371e8eb7..6e4964ed1 100644
--- a/doc/plugins/mirrorlist.mdwn
+++ b/doc/plugins/mirrorlist.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=mirror author="[[Joey]]"]]
-[[!tag type/special-purpose]]
+[[!tag type/chrome]]
 
 This plugin allows adding links a list of mirrors to each page in the
 wiki. For each mirror, a name and an url should be specified. Pages are
diff --git a/doc/plugins/more.mdwn b/doc/plugins/more.mdwn
index 81a9e67e8..a0664e843 100644
--- a/doc/plugins/more.mdwn
+++ b/doc/plugins/more.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=more author="Ben"]]
-[[!tag type/chrome]]
+[[!tag type/widget]]
 
 This plugin provides the [[ikiwiki/directive/more]] [[ikiwiki/directive]],
 which is a way to have a "more" link on a post in a blog, that leads to the
diff --git a/doc/plugins/poll.mdwn b/doc/plugins/poll.mdwn
index 510f67798..099cb399c 100644
--- a/doc/plugins/poll.mdwn
+++ b/doc/plugins/poll.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=poll author="[[Joey]]"]]
-[[!tag type/web]]
+[[!tag type/widget]]
 
 This plugin provides the [[ikiwiki/directive/poll]] [[ikiwiki/directive]],
 which allows inserting an online poll into a page.
diff --git a/doc/plugins/polygen.mdwn b/doc/plugins/polygen.mdwn
index 6045c1ec9..f9cea1f4d 100644
--- a/doc/plugins/polygen.mdwn
+++ b/doc/plugins/polygen.mdwn
@@ -1,5 +1,6 @@
 [[!template id=plugin name=polygen author="Enrico Zini"]]
 [[!tag type/fun]]
+[[!tag type/widget]]
 
 This plugin provides the [[ikiwiki/directive/polygen]] [[ikiwiki/directive]],
 which allows inserting text generated by polygen into a wiki page.
diff --git a/doc/plugins/prettydate.mdwn b/doc/plugins/prettydate.mdwn
index 11ad4252f..149b7c29c 100644
--- a/doc/plugins/prettydate.mdwn
+++ b/doc/plugins/prettydate.mdwn
@@ -1,5 +1,6 @@
 [[!template id=plugin name=prettydate author="[[Joey]]"]]
 [[!tag type/date]]
+[[!tag type/chrome]]
 
 Enabling this plugin changes the dates displayed on pages in the wiki to
 a format that is nice and easy to read. Examples: "late Wednesday evening, 
diff --git a/doc/plugins/relativedate.mdwn b/doc/plugins/relativedate.mdwn
index 50c96c5d7..d6e8eb08b 100644
--- a/doc/plugins/relativedate.mdwn
+++ b/doc/plugins/relativedate.mdwn
@@ -1,5 +1,6 @@
 [[!template id=plugin name=relativedate author="[[Joey]]"]]
 [[!tag type/date]]
+[[!tag type/chrome]]
 
 This plugin lets dates be displayed in relative form. Examples: "2 days ago", 
 "1 month and 3 days ago", "30 minutes ago". Hovering over the date will
diff --git a/doc/plugins/repolist.mdwn b/doc/plugins/repolist.mdwn
index 9b3a7575e..efd9c9352 100644
--- a/doc/plugins/repolist.mdwn
+++ b/doc/plugins/repolist.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=repolist author="[[Joey]]"]]
-[[!tag type/useful]]
+[[!tag type/web]]
 
 This plugin allows you to configure ikiwiki with the location of
 [[rcs]] repositories for your wiki's source. This is done via the
diff --git a/doc/plugins/shortcut.mdwn b/doc/plugins/shortcut.mdwn
index 68896f4d3..1e8e85ed8 100644
--- a/doc/plugins/shortcut.mdwn
+++ b/doc/plugins/shortcut.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=shortcut author="[[Joey]]"]]
-[[!tag type/useful]]
+[[!tag type/widget]]
 
 This plugin provides the [[ikiwiki/directive/shortcut]] [[ikiwiki/directive]].
 It allows external links to commonly linked to sites to be made
diff --git a/doc/plugins/sparkline.mdwn b/doc/plugins/sparkline.mdwn
index bcc5daec6..ee3928d7e 100644
--- a/doc/plugins/sparkline.mdwn
+++ b/doc/plugins/sparkline.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=sparkline author="[[Joey]]"]]
-[[!tag type/chrome]]
+[[!tag type/widget]]
 
 This plugin provides the [[ikiwiki/directive/sparkline]]
 [[ikiwiki/directive]], which allows for easily embedding sparklines into
diff --git a/doc/plugins/table.mdwn b/doc/plugins/table.mdwn
index fb830044f..fe66f90a8 100644
--- a/doc/plugins/table.mdwn
+++ b/doc/plugins/table.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=table author="[[VictorMoral]]"]]
-[[!tag type/useful]]
+[[!tag type/widget]]
 
 This plugin provides the [[ikiwiki/directive/table]] [[ikiwiki/directive]].
 It can build HTML tables from data in CSV (comma-separated values)
diff --git a/doc/plugins/template.mdwn b/doc/plugins/template.mdwn
index 6675207b2..da775f232 100644
--- a/doc/plugins/template.mdwn
+++ b/doc/plugins/template.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=template author="[[Joey]]"]]
-[[!tag type/useful]]
+[[!tag type/widget]]
 
 This plugin provides the [[ikiwiki/directive/template]] [[ikiwiki/directive]].
 With this plugin, you can set up templates, and cause them to be filled out
diff --git a/doc/plugins/testpagespec.mdwn b/doc/plugins/testpagespec.mdwn
index dabcb0bec..8180d5d4b 100644
--- a/doc/plugins/testpagespec.mdwn
+++ b/doc/plugins/testpagespec.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=testpagespec author="[[Joey]]"]]
-[[!tag type/useful]]
+[[!tag type/special-purpose]]
 
 This plugin provides a [[ikiwiki/directive/testpagespec]] [[ikiwiki/directive]].
 The directive allows testing a [[ikiwiki/PageSpec]] to see if it matches a
diff --git a/doc/plugins/teximg.mdwn b/doc/plugins/teximg.mdwn
index ae052837f..f3cade85f 100644
--- a/doc/plugins/teximg.mdwn
+++ b/doc/plugins/teximg.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=teximg author="[[PatrickWinnertz]]"]]
-[[!tag type/chrome type/slow]]
+[[!tag type/widget type/slow]]
 
 This plugin provides a [[ikiwiki/directive/teximg]] [[ikiwiki/directive]],
 that renders LaTeX formulas into images.
diff --git a/doc/plugins/toc.mdwn b/doc/plugins/toc.mdwn
index 2b7686681..a0ad3a5d0 100644
--- a/doc/plugins/toc.mdwn
+++ b/doc/plugins/toc.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=toc author="[[Joey]]"]]
-[[!tag type/chrome]]
+[[!tag type/widget]]
 
 This plugin provides the [[ikiwiki/directive/toc]] [[ikiwiki/directive]],
 which adds a table of contents to a page.
diff --git a/doc/plugins/toggle.mdwn b/doc/plugins/toggle.mdwn
index 69ac613e0..d1500eba0 100644
--- a/doc/plugins/toggle.mdwn
+++ b/doc/plugins/toggle.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=toggle author="[[Joey]]"]]
-[[!tag type/chrome]]
+[[!tag type/widget]]
 
 This plugin provides the [[ikiwiki/directive/toggle]] and
 [[ikiwiki/directive/toggleable]] [[directives|ikiwiki/directive]].
diff --git a/doc/plugins/type/chrome.mdwn b/doc/plugins/type/chrome.mdwn
index d3f0eb3d3..a1c6d0728 100644
--- a/doc/plugins/type/chrome.mdwn
+++ b/doc/plugins/type/chrome.mdwn
@@ -1 +1 @@
-These plugins affect the look and feel of the wiki.
+These plugins affect the look and feel of the overall wiki.
diff --git a/doc/plugins/type/useful.mdwn b/doc/plugins/type/useful.mdwn
deleted file mode 100644
index 92fcf5af1..000000000
--- a/doc/plugins/type/useful.mdwn
+++ /dev/null
@@ -1 +0,0 @@
-These plugins perform various miscellaneous useful functions.
diff --git a/doc/plugins/type/widget.mdwn b/doc/plugins/type/widget.mdwn
new file mode 100644
index 000000000..875829d0b
--- /dev/null
+++ b/doc/plugins/type/widget.mdwn
@@ -0,0 +1,2 @@
+These plugins allow inserting various things into pages via a
+[[ikiwiki/directive]].
diff --git a/doc/plugins/underlay.mdwn b/doc/plugins/underlay.mdwn
index f7eafee7c..8836a394c 100644
--- a/doc/plugins/underlay.mdwn
+++ b/doc/plugins/underlay.mdwn
@@ -1,17 +1,17 @@
 [[!template id=plugin name=underlay author="[[Simon_McVittie|smcv]]"]]
-[[!tag type/useful]]
+[[!tag type/special-purpose]]
 
-This plugin adds an `add_underlays` option to the setup file.
-Its value is a list of underlay directories whose content is added to the wiki.
+This plugin adds an `add_underlays` option to the setup file. Its value is
+a list of underlay directories whose content is added to the wiki.
 
 Multiple underlays are normally set up automatically by other plugins (for
-instance, the images used by the [[plugins/smiley]] plugin), but they can also be
-used as a way to pull in external files that you don't want in revision control,
-like photos or software releases.
+instance, the images used by the [[plugins/smiley]] plugin), but they can
+also be used as a way to pull in external files that you don't want in
+revision control, like photos or software releases.
 
-Directories in `add_underlays` should usually be absolute. If relative, they're
-interpreted as relative to the parent directory of the basewiki underlay, which
-is probably not particularly useful in this context.
+Directories in `add_underlays` should usually be absolute. If relative,
+they're interpreted as relative to the parent directory of the basewiki
+underlay, which is probably not particularly useful in this context.
 
 --
 
diff --git a/doc/plugins/wmd.mdwn b/doc/plugins/wmd.mdwn
index dc9a30703..96c6e2e6c 100644
--- a/doc/plugins/wmd.mdwn
+++ b/doc/plugins/wmd.mdwn
@@ -1,5 +1,5 @@
 [[!template id=plugin name=wmd author="[[Will]]"]]
-[[!tag type/chrome]]
+[[!tag type/web]]
 
 [WMD](http://wmd-editor.com/) is a What You See Is What You Mean editor for
 [[mdwn]]. This plugin makes WMD be used for editing pages in the wiki.
-- 
cgit v1.2.3


From 4be426ab1ad01a2a90151d741f737d41a12a6cbe Mon Sep 17 00:00:00 2001
From: Jon Dowland <jmtd@debian.org>
Date: Mon, 1 Mar 2010 10:28:59 +0000
Subject: wl from report to field plugin pages

---
 doc/plugins/contrib/report.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/report.mdwn b/doc/plugins/contrib/report.mdwn
index 7130bcb5f..e8cbd0486 100644
--- a/doc/plugins/contrib/report.mdwn
+++ b/doc/plugins/contrib/report.mdwn
@@ -18,7 +18,7 @@ IkiWiki::Plugin::report - Produce templated reports from page field data.
 
 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 "field" plugin.
+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.
-- 
cgit v1.2.3


From 0284ccf5eb6163d4fe49ac829a1f976336bc5908 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Mon, 1 Mar 2010 14:43:55 +0000
Subject: fixed typo

---
 doc/plugins/contrib/report.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/report.mdwn b/doc/plugins/contrib/report.mdwn
index e8cbd0486..c364d4a3a 100644
--- a/doc/plugins/contrib/report.mdwn
+++ b/doc/plugins/contrib/report.mdwn
@@ -89,7 +89,7 @@ The "mood_summary" template might be like this:
     ## <TMPL_VAR NAME="HEADER1">
     </TMPL_IF>
     ### <TMPL_VAR NAME="TITLE">
-    (<TMPL_VAR NAME="DATE">) \[[<TMPL_VAR NAME="PAGE"]]
+    (<TMPL_VAR NAME="DATE">) \[[<TMPL_VAR NAME="PAGE">]]
     <TMPL_VAR NAME="DESCRIPTION">
     
 ### Advanced Options
-- 
cgit v1.2.3


From 0f433ed01c58978ba6d7845d5aaebb1ec8cefc9e Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Wed, 17 Mar 2010 00:42:38 +0000
Subject: link to highlight

---
 doc/plugins/contrib/highlightcode.mdwn | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/highlightcode.mdwn b/doc/plugins/contrib/highlightcode.mdwn
index 8abb76583..f1df204bb 100644
--- a/doc/plugins/contrib/highlightcode.mdwn
+++ b/doc/plugins/contrib/highlightcode.mdwn
@@ -1,6 +1,8 @@
 [[!template id=plugin name=highlightcode author="[[sabr]]"]]
 [[!tag type/format]]
 
+(An alternative to this plugin, [[plugins/highlight]], is now provided with IkiWiki. --[[smcv]])
+
 A small plugin to allow Ikiwiki to display source files complete with syntax highlighting. Files with recognized extensions (i.e. my-file.cpp) are be rendered just like any other Ikiwiki page. You can even edit your source files with Ikiwiki's editor.
 
 It uses the Syntax::Highlight::Engine::Kate Perl module to do the highlighting.
-- 
cgit v1.2.3


From 0f28f310472a333134af63a18b73372f044b8278 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@gnu.kitenet.net>
Date: Fri, 26 Mar 2010 00:12:22 -0400
Subject: security?

---
 doc/plugins/contrib/pod/discussion.mdwn | 8 ++++++++
 1 file changed, 8 insertions(+)
 create mode 100644 doc/plugins/contrib/pod/discussion.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/pod/discussion.mdwn b/doc/plugins/contrib/pod/discussion.mdwn
new file mode 100644
index 000000000..8f4b625ee
--- /dev/null
+++ b/doc/plugins/contrib/pod/discussion.mdwn
@@ -0,0 +1,8 @@
+My one concern about this plugin is the `=for` markup in POD.
+
+> Some format names that formatters currently are known to
+> accept include "roff", "man", "latex", "tex", "text", and "html".
+
+I don't know which of these [[!cpan Pod::Xml]] supports. If it currently
+supports, or later support latex, that could be problimatic since that
+could maybe be used to include files or run code. --[[Joey]]
-- 
cgit v1.2.3


From 3cea3eb5da0a8f09a495deea9f2a2c73dc76deab Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Fri, 26 Mar 2010 04:30:43 +0000
Subject: response

---
 doc/plugins/contrib/pod/discussion.mdwn | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/pod/discussion.mdwn b/doc/plugins/contrib/pod/discussion.mdwn
index 8f4b625ee..76e858680 100644
--- a/doc/plugins/contrib/pod/discussion.mdwn
+++ b/doc/plugins/contrib/pod/discussion.mdwn
@@ -3,6 +3,8 @@ My one concern about this plugin is the `=for` markup in POD.
 > Some format names that formatters currently are known to
 > accept include "roff", "man", "latex", "tex", "text", and "html".
 
-I don't know which of these [[!cpan Pod::Xml]] supports. If it currently
+I don't know which of these [[!cpan Pod::Xhtml]] supports. If it currently
 supports, or later support latex, that could be problimatic since that
 could maybe be used to include files or run code. --[[Joey]]
+
+> I don't know, either; the documentation for [[!cpan Pod:Xhtml]] is silent on this subject. --[[KathrynAndersen]]
-- 
cgit v1.2.3


From d88af43011193bb0eef79b749ae9a93eda5d266e Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Fri, 26 Mar 2010 13:20:33 +0000
Subject: brief review of field; fieldsort plugin

---
 doc/plugins/contrib/field/discussion.mdwn | 62 +++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 doc/plugins/contrib/field/discussion.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn
new file mode 100644
index 000000000..fc1759fab
--- /dev/null
+++ b/doc/plugins/contrib/field/discussion.mdwn
@@ -0,0 +1,62 @@
+Having tried out `field`, some comments (from [[smcv]]):
+
+The general concept looks great.
+
+The `pagetemplate` hook seems quite namespace-polluting: on a site containing
+a list of books, I'd like to have an `author` field, but that would collide
+with IkiWiki's use of `<TMPL_VAR AUTHOR>` for the author of the *page*
+(i.e. me). Perhaps it'd be better if the pagetemplate hook was only active for
+`<TMPL_VAR FIELD_AUTHOR>` or something? (For those who want the current
+behaviour, an auxiliary plugin would be easy.)
+
+From a coding style point of view, the `$CamelCase` variable names aren't
+IkiWiki style, and the `match_foo` functions look as though they could benefit
+from being thin wrappers around a common `&IkiWiki::Plugin::field::match`
+function (see `meta` for a similar approach).
+
+I think the documentation would probably be clearer in a less manpage-like
+and more ikiwiki-like style?
+
+If one of my branches from [[todo/allow_plugins_to_add_sorting_methods]] is
+accepted, a `field()` cmp type would mean that [[plugins/contrib/report]] can
+stop reimplementing sorting. Here's the implementation I'm using, with
+your "sortspec" concept (a sort-hook would be very similar): if merged,
+I think it should just be part of `field` rather than a separate plugin.
+
+	# Copyright © 2010 Simon McVittie, released under GNU LGPL >= 2.1
+	package IkiWiki::Plugin::fieldsort;
+	use warnings;
+	use strict;
+	use IkiWiki 3.00;
+	use IkiWiki::Plugin::field;
+
+	sub import {
+		hook(type => "getsetup", id => "fieldsort",  call => \&getsetup);
+	}
+
+	sub getsetup () {
+		return
+			plugin => {
+				safe => 1,
+				rebuild => undef,
+			},
+	}
+
+	package IkiWiki::PageSpec;
+
+	sub check_cmp_field {
+		if (!length $_[0]) {
+			error("sort=field requires a parameter");
+		}
+	}
+
+	sub cmp_field {
+		my $left = IkiWiki::Plugin::field::field_get_value($_[2], $_[0]);
+		my $right = IkiWiki::Plugin::field::field_get_value($_[2], $_[1]);
+
+		$left = "" unless defined $left;
+		$right = "" unless defined $right;
+		return $left cmp $right;
+	}
+
+	1;
-- 
cgit v1.2.3


From bea828a2f6b455c46f2b5d6c16805958a2e3412a Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Fri, 26 Mar 2010 13:30:52 +0000
Subject: doesn't field+template already cover this?

---
 doc/plugins/contrib/ftemplate/discussion.mdwn | 6 ++++++
 1 file changed, 6 insertions(+)
 create mode 100644 doc/plugins/contrib/ftemplate/discussion.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/ftemplate/discussion.mdwn b/doc/plugins/contrib/ftemplate/discussion.mdwn
new file mode 100644
index 000000000..851ccf960
--- /dev/null
+++ b/doc/plugins/contrib/ftemplate/discussion.mdwn
@@ -0,0 +1,6 @@
+Is this actually necessary? Doesn't the combination of [[plugins/template]]
+with [[plugins/contrib/field]]'s `pagetemplate` hook provide the same
+functionality? I suppose one missing thing is that `ftemplate` looks in
+the "system" templates directories, not just in the wiki, but that
+seems orthogonal (and might even be a good enhancement to `template`).
+--[[smcv]]
-- 
cgit v1.2.3


From fffd7e7e026f61e03b2fa052acdf7130889f6343 Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Fri, 26 Mar 2010 13:43:37 +0000
Subject: oh, my mistake... this *is* necessary, but could perhaps be done
 better?

---
 doc/plugins/contrib/ftemplate/discussion.mdwn | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/ftemplate/discussion.mdwn b/doc/plugins/contrib/ftemplate/discussion.mdwn
index 851ccf960..eb2ec6f13 100644
--- a/doc/plugins/contrib/ftemplate/discussion.mdwn
+++ b/doc/plugins/contrib/ftemplate/discussion.mdwn
@@ -1,6 +1,13 @@
-Is this actually necessary? Doesn't the combination of [[plugins/template]]
-with [[plugins/contrib/field]]'s `pagetemplate` hook provide the same
-functionality? I suppose one missing thing is that `ftemplate` looks in
+I initially thought this wasn't actually necessary - the combination
+of [[plugins/template]] with [[plugins/contrib/field]]'s `pagetemplate`
+hook ought to provide the same functionality. However, `template`
+doesn't run `pagetemplate` hooks; a more general version of this
+plugin would be to have a variant of `template` that runs `pagetemplate`
+hooks (probably easiest to just patch `template` to implement a
+second directive, or have a special parameter `run_hooks="yes"`,
+or something).
+
+Another missing thing is that `ftemplate` looks in
 the "system" templates directories, not just in the wiki, but that
-seems orthogonal (and might even be a good enhancement to `template`).
+seems orthogonal (and might be a good enhancement to `template` anyway).
 --[[smcv]]
-- 
cgit v1.2.3


From b9958fe3cf1a27b58d3e2bd59c76553eb0046782 Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Fri, 26 Mar 2010 14:09:04 +0000
Subject: brief review of report

---
 doc/plugins/contrib/report/discussion.mdwn | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)
 create mode 100644 doc/plugins/contrib/report/discussion.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/report/discussion.mdwn b/doc/plugins/contrib/report/discussion.mdwn
new file mode 100644
index 000000000..6b1e28f6a
--- /dev/null
+++ b/doc/plugins/contrib/report/discussion.mdwn
@@ -0,0 +1,23 @@
+Wow, this plugin does a lot... it seems to be `inline` (but without the feeds
+or the ability to not have `archive="yes"`), plus part of
+[[plugins/contrib/trail]], plus some sorting, plus an ingenious workaround
+for template evaluation being relatively stateless.
+
+A large part of this plugin would just fall off if one of the versions of
+[[todo/allow_add_plugins_to_add_sorting_methods]] was merged, which was a
+large part of the idea of that feature request :-) To make use of that
+you'd have to use `pagespec_match_list` in the trail case too, but that's
+easy enough - just add `list => [@the_trail_pages]` to the arguments.
+
+Another large part would fall off if this plugin required, and internally
+invoked, `inline` (like my `comments` plugin does) - `inline` runs
+`pagetemplate` hooks, and in particular, it'll run the `field` hook.
+Alternatively, this plugin could invoke `pagetemplate` hooks itself,
+removing the special case for `field`.
+
+Perhaps the `headers` thing could migrate into inline somehow? That might
+lead to making inline too big, though.
+
+Is the intention that the `trail` part is a performance hack, or a way
+to select pages? How does it relate to [[todo/wikitrails]] or
+[[plugins/contrib/trail]]? --[[smcv]]
-- 
cgit v1.2.3


From 3c98cf653f6d6950a425620acf0279df902d004b Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Fri, 26 Mar 2010 15:09:11 +0000
Subject: fix link

---
 doc/plugins/contrib/report/discussion.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/report/discussion.mdwn b/doc/plugins/contrib/report/discussion.mdwn
index 6b1e28f6a..918d0779b 100644
--- a/doc/plugins/contrib/report/discussion.mdwn
+++ b/doc/plugins/contrib/report/discussion.mdwn
@@ -4,7 +4,7 @@ or the ability to not have `archive="yes"`), plus part of
 for template evaluation being relatively stateless.
 
 A large part of this plugin would just fall off if one of the versions of
-[[todo/allow_add_plugins_to_add_sorting_methods]] was merged, which was a
+"[[todo/allow_plugins_to_add_sorting_methods]]" was merged, which was a
 large part of the idea of that feature request :-) To make use of that
 you'd have to use `pagespec_match_list` in the trail case too, but that's
 easy enough - just add `list => [@the_trail_pages]` to the arguments.
-- 
cgit v1.2.3


From ba05b907e3563f9aa25a4322abd9ab2d5b56b36b Mon Sep 17 00:00:00 2001
From: "http://oneingray.myopenid.com/" <http://oneingray.myopenid.com/@web>
Date: Sun, 28 Mar 2010 15:58:37 +0000
Subject: More wishlist items for the `xslt` plugin.

---
 doc/plugins/contrib/xslt/discussion.mdwn | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/xslt/discussion.mdwn b/doc/plugins/contrib/xslt/discussion.mdwn
index 9cda02f88..72cce083c 100644
--- a/doc/plugins/contrib/xslt/discussion.mdwn
+++ b/doc/plugins/contrib/xslt/discussion.mdwn
@@ -20,3 +20,30 @@ possible. Can it also read other arbitrary files, run other programs, etc?
 > For the second point, I think the main concern would be resource usage.  XSLT is a pretty limited language; it can read other XML files, but it can't run other programs so far as I know.
 
 > -- [[KathrynAndersen]]
+
+>> XSLT is, indeed, a Turing-complete programming language.
+   However, [XML::LibXSLT][] provides a set of functions to help
+   to minimize the damage that may be caused by running a random
+   program.
+
+>> In particular, `max_depth ()` allows for the maximum
+   recursion depth to be set, while
+   `read_file ()`, `write_file ()`, `create_dir ()`,
+   `read_net ()` and `write_net ()`
+   are the callbacks that allow any of the possible file
+   operations to be denied.
+
+>> To be honest, I'd prefer for the `read_file ()` callback to
+   only grant access to the files below the Ikiwiki source
+   directory, and for all the `write_`&hellip; and
+   &hellip;`_net` callbacks to deny the access unconditionally.
+
+>> One more wishlist item: allow the set of locations to take
+   `.xsl` files from to be preconfigured, so that, e.&nbsp;g.,
+   one could allow (preasumably trusted) system stylesheets,
+   while disallowing any stylesheets that are placed on the Wiki
+   itself.
+
+>> &mdash;&nbsp;Ivan Shmakov, 2010-03-28Z.
+
+[XML::LibXSLT]: http://search.cpan.org/~PAJAS/XML-LibXSLT/LibXSLT.pm
-- 
cgit v1.2.3


From 386e464188d817f90e1cb6535da2db6bcfaa3fa0 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Tue, 30 Mar 2010 05:31:10 +0000
Subject: quick response

---
 doc/plugins/contrib/field/discussion.mdwn | 6 ++++++
 1 file changed, 6 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn
index fc1759fab..4bb285a50 100644
--- a/doc/plugins/contrib/field/discussion.mdwn
+++ b/doc/plugins/contrib/field/discussion.mdwn
@@ -9,6 +9,10 @@ with IkiWiki's use of `<TMPL_VAR AUTHOR>` for the author of the *page*
 `<TMPL_VAR FIELD_AUTHOR>` or something? (For those who want the current
 behaviour, an auxiliary plugin would be easy.)
 
+> No, please.  The idea is to be *able* to override field names if one wishes to, and choose, for yourself, non-colliding field names if one wishes not to.  I don't wish to lose the power of being able to, say, define a page title with YAML format if I want to, or to write a site-specific plugin which calculates a page title, or other nifty things.
+>It's not like one is going to lose the fields defined by the meta plugin; if "author" is defined by \[[!meta author=...]] then that's what will be found by "field" (provided the "meta" plugin is registered; that's what the "field_register" option is for).
+>--[[KathrynAndersen]]
+
 From a coding style point of view, the `$CamelCase` variable names aren't
 IkiWiki style, and the `match_foo` functions look as though they could benefit
 from being thin wrappers around a common `&IkiWiki::Plugin::field::match`
@@ -17,6 +21,8 @@ function (see `meta` for a similar approach).
 I think the documentation would probably be clearer in a less manpage-like
 and more ikiwiki-like style?
 
+> I don't think ikiwiki *has* a "style" for docs, does it?  So I followed the Perl Module style. And I'm rather baffled as to why having the docs laid out in clear sections... make them less clear. --[[KathrynAndersen]]
+
 If one of my branches from [[todo/allow_plugins_to_add_sorting_methods]] is
 accepted, a `field()` cmp type would mean that [[plugins/contrib/report]] can
 stop reimplementing sorting. Here's the implementation I'm using, with
-- 
cgit v1.2.3


From 2d1e4cce45024f6b2c384eaf7b5276c448cb3a05 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Tue, 30 Mar 2010 05:38:31 +0000
Subject: response

---
 doc/plugins/contrib/ftemplate/discussion.mdwn | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/ftemplate/discussion.mdwn b/doc/plugins/contrib/ftemplate/discussion.mdwn
index eb2ec6f13..adb66ee6a 100644
--- a/doc/plugins/contrib/ftemplate/discussion.mdwn
+++ b/doc/plugins/contrib/ftemplate/discussion.mdwn
@@ -7,7 +7,11 @@ hooks (probably easiest to just patch `template` to implement a
 second directive, or have a special parameter `run_hooks="yes"`,
 or something).
 
+> I got the impression that `pagetemplate` hooks are intended to be completely independent of `template` variables; page-template is for the actual `page.tmpl` template, while `template` is for other templates which are used inside the page content.  So I don't understand why one would need a run_hooks option. --[[KathrynAndersen]]
+
 Another missing thing is that `ftemplate` looks in
 the "system" templates directories, not just in the wiki, but that
 seems orthogonal (and might be a good enhancement to `template` anyway).
 --[[smcv]]
+
+> Yes, I added that because I wanted the option of not having to make all my templates work as wiki pages also. --[[KathrynAndersen]]
-- 
cgit v1.2.3


From 90c444d9f197a5a9b87d3e70248279ac68e351a6 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Tue, 30 Mar 2010 06:44:04 +0000
Subject: response

---
 doc/plugins/contrib/report/discussion.mdwn | 11 +++++++++++
 1 file changed, 11 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/report/discussion.mdwn b/doc/plugins/contrib/report/discussion.mdwn
index 918d0779b..42a1009cb 100644
--- a/doc/plugins/contrib/report/discussion.mdwn
+++ b/doc/plugins/contrib/report/discussion.mdwn
@@ -18,6 +18,17 @@ removing the special case for `field`.
 Perhaps the `headers` thing could migrate into inline somehow? That might
 lead to making inline too big, though.
 
+> I think inline is *already* too big, honestly. --[[KathrynAndersen]]
+
 Is the intention that the `trail` part is a performance hack, or a way
 to select pages? How does it relate to [[todo/wikitrails]] or
 [[plugins/contrib/trail]]? --[[smcv]]
+
+> The `trail` part is *both* a performance hack, and a way to select pages.  I have over 5000 pages on my site, I need all the performance hacks I can get.
+> For the performance hack, it is a way of reducing the need to iterate through every single page in the wiki in order to find matching pages.
+> For the way-to-select-pages, yes, it is intended to be similar to [[todo/wikitrails]] and [[plugins/contrib/trail]] (and will be more similar with the new release which will be happening soon; it will add prev_* and next_* variables).
+> The idea is that, rather than having to add special "trail" links on PageA to indicate that a page is part of the trail,
+> it takes advantage of the `%links` hash, which already contains, for each page, an array of the links from that page to other pages.  No need for special markup, just use what's there; a trail is defined as "all the pages linked to from page X", and since it's an array, it has an order already.
+> But to avoid that being too limiting, one can use a `pages=...` pagespec to filter that list to a subset; only the pages one is interested in.
+> And one can also sort it, if one so desires.
+> --[[KathrynAndersen]] 
-- 
cgit v1.2.3


From 026355cfa24dc911a247dcafca10c6ea74ae515b Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Tue, 30 Mar 2010 12:09:59 +0000
Subject: respond and attempt to invoke Joey :-)

---
 doc/plugins/contrib/ftemplate/discussion.mdwn | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/ftemplate/discussion.mdwn b/doc/plugins/contrib/ftemplate/discussion.mdwn
index adb66ee6a..de4b35ef0 100644
--- a/doc/plugins/contrib/ftemplate/discussion.mdwn
+++ b/doc/plugins/contrib/ftemplate/discussion.mdwn
@@ -9,9 +9,24 @@ or something).
 
 > I got the impression that `pagetemplate` hooks are intended to be completely independent of `template` variables; page-template is for the actual `page.tmpl` template, while `template` is for other templates which are used inside the page content.  So I don't understand why one would need a run_hooks option. --[[KathrynAndersen]]
 
+>> `Render`, `inline`, `comments` and `recentchanges` run `pagetemplate`
+>> hooks, as does anything that uses `IkiWiki::misctemplate`. From that
+>> quick survey, it seems as though `template` is the only thing that
+>> uses `HTML::Template` but *doesn't* run `pagetemplate` hooks?
+>>
+>> It just seems strange to me that `field` needs to have its own
+>> of `template` (this), its own variant of `inline` (`report`),
+>> and so on - I'd tend to lean more towards having `field`
+>> enhance the existing plugins. I'm not an ikiwiki committer,
+>> mind... Joey, your opinion would be appreciated! --[[smcv]]
+
 Another missing thing is that `ftemplate` looks in
 the "system" templates directories, not just in the wiki, but that
 seems orthogonal (and might be a good enhancement to `template` anyway).
 --[[smcv]]
 
 > Yes, I added that because I wanted the option of not having to make all my templates work as wiki pages also. --[[KathrynAndersen]]
+
+>> Yeah, that's something that annoys me about `template` too. I've
+>> opened a todo: [[todo/user-defined_templates_outside_the_wiki]].
+>> --s
-- 
cgit v1.2.3


From 0503bf7c8824d941b26da4c91b4ee1f721fcf54c Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Tue, 30 Mar 2010 12:10:40 +0000
Subject:

---
 doc/plugins/contrib/ftemplate/discussion.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/ftemplate/discussion.mdwn b/doc/plugins/contrib/ftemplate/discussion.mdwn
index de4b35ef0..6a1d9f685 100644
--- a/doc/plugins/contrib/ftemplate/discussion.mdwn
+++ b/doc/plugins/contrib/ftemplate/discussion.mdwn
@@ -15,7 +15,7 @@ or something).
 >> uses `HTML::Template` but *doesn't* run `pagetemplate` hooks?
 >>
 >> It just seems strange to me that `field` needs to have its own
->> of `template` (this), its own variant of `inline` (`report`),
+>> variant of `template` (this), its own variant of `inline` (`report`),
 >> and so on - I'd tend to lean more towards having `field`
 >> enhance the existing plugins. I'm not an ikiwiki committer,
 >> mind... Joey, your opinion would be appreciated! --[[smcv]]
-- 
cgit v1.2.3


From edcea2b98100aa1ff18b91038a33e2ea55f13850 Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Tue, 30 Mar 2010 12:27:18 +0000
Subject: respond

---
 doc/plugins/contrib/report/discussion.mdwn | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/report/discussion.mdwn b/doc/plugins/contrib/report/discussion.mdwn
index 42a1009cb..a6cb6f8bd 100644
--- a/doc/plugins/contrib/report/discussion.mdwn
+++ b/doc/plugins/contrib/report/discussion.mdwn
@@ -20,6 +20,13 @@ lead to making inline too big, though.
 
 > I think inline is *already* too big, honestly. --[[KathrynAndersen]]
 
+>> A fair point; perhaps my complaint should be that *inline* does
+>> too many orthogonal things. I suppose the headers feature wouldn't
+>> really make sense in an inline that didn't have `archive="yes"`,
+>> so it'd make sense to recommend this plugin as a replacement
+>> for inlining with archive=yes (for which I now realise "inline"
+>> is the wrong verb anyway :-) ) --s
+
 Is the intention that the `trail` part is a performance hack, or a way
 to select pages? How does it relate to [[todo/wikitrails]] or
 [[plugins/contrib/trail]]? --[[smcv]]
@@ -32,3 +39,18 @@ to select pages? How does it relate to [[todo/wikitrails]] or
 > But to avoid that being too limiting, one can use a `pages=...` pagespec to filter that list to a subset; only the pages one is interested in.
 > And one can also sort it, if one so desires.
 > --[[KathrynAndersen]] 
+
+>> That's an interesting approach to trails; I'd missed the fact that
+>> links are already ordered.
+>>
+>> This does have the same problems as tags, though: see
+>> [[bugs/tagged()_matching_wikilinks]] and
+>> [[todo/matching_different_kinds_of_links]]. I suppose the question
+>> now is whether new code should be consistent with `tag` (and
+>> potentially be fixed at the same time as tag itself), or try to
+>> avoid those problems?
+>>
+>> The combination of `trail` with another pagespec in this plugin
+>> does provide a neat way for it to work around having unwanted
+>> pages in the report, by limiting by a suitable tag or subdirectory
+>> or something. --s
-- 
cgit v1.2.3


From bb8b941bfc3d3564324a23bba14dc8112d8ea6c7 Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Tue, 30 Mar 2010 12:48:03 +0000
Subject: respond; correct license of fieldsort plugin to match IkiWiki

---
 doc/plugins/contrib/field/discussion.mdwn | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn
index 4bb285a50..7e94a4029 100644
--- a/doc/plugins/contrib/field/discussion.mdwn
+++ b/doc/plugins/contrib/field/discussion.mdwn
@@ -13,6 +13,19 @@ behaviour, an auxiliary plugin would be easy.)
 >It's not like one is going to lose the fields defined by the meta plugin; if "author" is defined by \[[!meta author=...]] then that's what will be found by "field" (provided the "meta" plugin is registered; that's what the "field_register" option is for).
 >--[[KathrynAndersen]]
 
+>> Hmm. I suppose if you put the title (or whatever) in the YAML, then
+>> "almost" all the places in IkiWiki that respect titles will do the
+>> right thing due to the pagetemplate hook, with the exception being
+>> anything that has special side-effects inside `meta` (like `date`),
+>> or anything that looks in `$pagestate{foo}{meta}` directly
+>> (like `map`). Is your plan that `meta` should register itself by
+>> default, and `map` and friends should be adapted to
+>> work based on `getfield()` instead of `$pagestate{foo}{meta}`, then?
+>>
+>> (On the site I mentioned, I'm using an unmodified version of `field`,
+>> and currently working around the collision by tagging books' pages
+>> with `bookauthor` instead of `author` in the YAML.) --s
+
 From a coding style point of view, the `$CamelCase` variable names aren't
 IkiWiki style, and the `match_foo` functions look as though they could benefit
 from being thin wrappers around a common `&IkiWiki::Plugin::field::match`
@@ -23,13 +36,20 @@ and more ikiwiki-like style?
 
 > I don't think ikiwiki *has* a "style" for docs, does it?  So I followed the Perl Module style. And I'm rather baffled as to why having the docs laid out in clear sections... make them less clear. --[[KathrynAndersen]]
 
+>> I keep getting distracted by the big shouty headings :-)
+>> I suppose what I was really getting at was that when this plugin
+>> is merged, its docs will end up split between its plugin
+>> page, [[plugins/write]] and [[ikiwiki/PageSpec]]; on some of the
+>> contrib plugins I've added I've tried to separate the docs
+>> according to how they'll hopefully be laid out after merge. --s
+
 If one of my branches from [[todo/allow_plugins_to_add_sorting_methods]] is
 accepted, a `field()` cmp type would mean that [[plugins/contrib/report]] can
 stop reimplementing sorting. Here's the implementation I'm using, with
 your "sortspec" concept (a sort-hook would be very similar): if merged,
 I think it should just be part of `field` rather than a separate plugin.
 
-	# Copyright © 2010 Simon McVittie, released under GNU LGPL >= 2.1
+	# Copyright © 2010 Simon McVittie, released under GNU GPL >= 2
 	package IkiWiki::Plugin::fieldsort;
 	use warnings;
 	use strict;
-- 
cgit v1.2.3


From fc5445b90677489642e4ae8d5b2f6c54cdd847c5 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 31 Mar 2010 03:01:41 +0000
Subject: response

---
 doc/plugins/contrib/ftemplate/discussion.mdwn | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/ftemplate/discussion.mdwn b/doc/plugins/contrib/ftemplate/discussion.mdwn
index 6a1d9f685..eb84dd09b 100644
--- a/doc/plugins/contrib/ftemplate/discussion.mdwn
+++ b/doc/plugins/contrib/ftemplate/discussion.mdwn
@@ -20,6 +20,8 @@ or something).
 >> enhance the existing plugins. I'm not an ikiwiki committer,
 >> mind... Joey, your opinion would be appreciated! --[[smcv]]
 
+>>> I did it that way basically because I needed the functionality ASAP, and I didn't want to step on anyone's toes, so I made them as separate plugins.  If Joey wants to integrate the functionality into IkiWiki proper, I would be very happy, but I don't want to put pressure on him. --[[KathrynAndersen]]
+
 Another missing thing is that `ftemplate` looks in
 the "system" templates directories, not just in the wiki, but that
 seems orthogonal (and might be a good enhancement to `template` anyway).
-- 
cgit v1.2.3


From 4eed0abc8c181a027fa802d209fd95d8c10ee9f0 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Thu, 1 Apr 2010 00:23:31 +0000
Subject: response; thoughts about inline and tags

---
 doc/plugins/contrib/report/discussion.mdwn | 6 ++++++
 1 file changed, 6 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/report/discussion.mdwn b/doc/plugins/contrib/report/discussion.mdwn
index a6cb6f8bd..953509297 100644
--- a/doc/plugins/contrib/report/discussion.mdwn
+++ b/doc/plugins/contrib/report/discussion.mdwn
@@ -27,6 +27,8 @@ lead to making inline too big, though.
 >> for inlining with archive=yes (for which I now realise "inline"
 >> is the wrong verb anyway :-) ) --s
 
+>>> I think *inline* would be a bit less unwieldy if there was some way of factoring out the feed stuff into a separate plugin, but I don't know if that's possible. --K.A.
+
 Is the intention that the `trail` part is a performance hack, or a way
 to select pages? How does it relate to [[todo/wikitrails]] or
 [[plugins/contrib/trail]]? --[[smcv]]
@@ -54,3 +56,7 @@ to select pages? How does it relate to [[todo/wikitrails]] or
 >> does provide a neat way for it to work around having unwanted
 >> pages in the report, by limiting by a suitable tag or subdirectory
 >> or something. --s
+
+>>> Either that, or somehow combine tagging with fields, such that one could declare a tag, and it would create both a link and a field with a given value.  (I've been working on something like that, but it still has bugs).
+>>> That way, the test for whether something is tagged would be something like "link(tag/foo) and field(tag foo)".
+>>> --K.A.
-- 
cgit v1.2.3


From 63bc057690d388a81e643d4556c6a001d886b59c Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Thu, 1 Apr 2010 01:35:35 +0000
Subject:

---
 doc/plugins/contrib/report/discussion.mdwn | 7 +++++++
 1 file changed, 7 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/report/discussion.mdwn b/doc/plugins/contrib/report/discussion.mdwn
index 953509297..a257198c0 100644
--- a/doc/plugins/contrib/report/discussion.mdwn
+++ b/doc/plugins/contrib/report/discussion.mdwn
@@ -60,3 +60,10 @@ to select pages? How does it relate to [[todo/wikitrails]] or
 >>> Either that, or somehow combine tagging with fields, such that one could declare a tag, and it would create both a link and a field with a given value.  (I've been working on something like that, but it still has bugs).
 >>> That way, the test for whether something is tagged would be something like "link(tag/foo) and field(tag foo)".
 >>> --K.A.
+
+>>>> I can see that this'd work well for 1:1 relationships like next
+>>>> and previous, but I don't think that'd work for pages with more than
+>>>> one tag - as far as I can see, `field`'s data model is that each
+>>>> page has no more than one value for each field?
+>>>> [[todo/Matching_different_kinds_of_links]] has some thoughts about
+>>>> how it could be implemented, though. --s
-- 
cgit v1.2.3


From a682df9a1f14ea873c7103f80108330840a15cd0 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Thu, 1 Apr 2010 07:22:37 +0000
Subject: considering tags and fields

---
 doc/plugins/contrib/report/discussion.mdwn | 6 ++++++
 1 file changed, 6 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/report/discussion.mdwn b/doc/plugins/contrib/report/discussion.mdwn
index a257198c0..e23a4ced4 100644
--- a/doc/plugins/contrib/report/discussion.mdwn
+++ b/doc/plugins/contrib/report/discussion.mdwn
@@ -67,3 +67,9 @@ to select pages? How does it relate to [[todo/wikitrails]] or
 >>>> page has no more than one value for each field?
 >>>> [[todo/Matching_different_kinds_of_links]] has some thoughts about
 >>>> how it could be implemented, though. --s
+
+>>>>> You have a point there.  I'm not sure what would be better: to add the concept of arrays/sets to `field`, or to think of tags as a special case.  Problem is, I find tags as they currently exist to be too limiting.  I prefer something that can be used for Faceted Tagging <http://en.wikipedia.org/wiki/Faceted_classification>; that is, things like Author:Fred Nurk, Genre:Historical, Rating:Good, and so on.  Of course, that doesn't mean that each tag is limited to only one value, either; just to take the above examples, something might have more than one author, or have multiple genres (such as Historical + Romance).
+
+>>>>> It might be that adding arrays to the `field` plugin is a good way to go: after all, even though field=value is the most common, with the flexibility of things like YAML, one could define all sorts of things.  What I'm not so sure about is how to return the values when queried, since some things would be expecting scalars all the time.  Ah, perhaps I could use wantarray?
+>>>>> Is there a way of checking a HTML::Template template to see if it expecting an array for a particular value?
+>>>>> --[[KathrynAndersen]]
-- 
cgit v1.2.3


From 0dad28b3530d70830456a3f8d57b0e3f3d52ee2d Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Sat, 3 Apr 2010 00:45:16 +0000
Subject: reduced difference

---
 doc/plugins/contrib/ftemplate/discussion.mdwn | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/ftemplate/discussion.mdwn b/doc/plugins/contrib/ftemplate/discussion.mdwn
index eb84dd09b..1e0bca5d8 100644
--- a/doc/plugins/contrib/ftemplate/discussion.mdwn
+++ b/doc/plugins/contrib/ftemplate/discussion.mdwn
@@ -29,6 +29,5 @@ seems orthogonal (and might be a good enhancement to `template` anyway).
 
 > Yes, I added that because I wanted the option of not having to make all my templates work as wiki pages also. --[[KathrynAndersen]]
 
->> Yeah, that's something that annoys me about `template` too. I've
->> opened a todo: [[todo/user-defined_templates_outside_the_wiki]].
->> --s
+>> Joey has added support for
+>> [[todo/user-defined_templates_outside_the_wiki]] now. --s
-- 
cgit v1.2.3


From 20040772cecbddf07ab6369a22ab2fe1ad794b48 Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Sun, 4 Apr 2010 00:27:20 +0000
Subject: update fieldsort plugin to be compatible with the latest version of
 my branch

---
 doc/plugins/contrib/field/discussion.mdwn | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn
index 7e94a4029..ad17f87e6 100644
--- a/doc/plugins/contrib/field/discussion.mdwn
+++ b/doc/plugins/contrib/field/discussion.mdwn
@@ -68,15 +68,13 @@ I think it should just be part of `field` rather than a separate plugin.
 			},
 	}
 
-	package IkiWiki::PageSpec;
+	package IkiWiki::SortSpec;
 
-	sub check_cmp_field {
+	sub cmp_field {
 		if (!length $_[0]) {
 			error("sort=field requires a parameter");
 		}
-	}
 
-	sub cmp_field {
 		my $left = IkiWiki::Plugin::field::field_get_value($_[2], $_[0]);
 		my $right = IkiWiki::Plugin::field::field_get_value($_[2], $_[1]);
 
-- 
cgit v1.2.3


From 834936a408d0d9f481071fbcaefc67273eabb60c Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Sun, 4 Apr 2010 14:03:51 +0000
Subject: bug report + patch: unnecessary YAML::Any dependency

---
 doc/plugins/contrib/field/discussion.mdwn | 8 ++++++++
 1 file changed, 8 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn
index ad17f87e6..c2b75a76d 100644
--- a/doc/plugins/contrib/field/discussion.mdwn
+++ b/doc/plugins/contrib/field/discussion.mdwn
@@ -84,3 +84,11 @@ I think it should just be part of `field` rather than a separate plugin.
 	}
 
 	1;
+
+-------
+
+Bug report: `field` has an unnecessary `use YAML::Any`, presumably from before
+you separated out `ymlfront`. Trivial patch available from
+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>)
+--[[smcv]]
-- 
cgit v1.2.3


From f6dde92957f8b21d8823f2e51d9e3c48bbad7146 Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Sun, 4 Apr 2010 14:05:42 +0000
Subject: advertise some bugfixes

---
 doc/plugins/contrib/ymlfront/discussion.mdwn | 4 ++++
 1 file changed, 4 insertions(+)
 create mode 100644 doc/plugins/contrib/ymlfront/discussion.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/ymlfront/discussion.mdwn b/doc/plugins/contrib/ymlfront/discussion.mdwn
new file mode 100644
index 000000000..f437624b6
--- /dev/null
+++ b/doc/plugins/contrib/ymlfront/discussion.mdwn
@@ -0,0 +1,4 @@
+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]]
-- 
cgit v1.2.3


From 5f8df5828834c0163d04ad3b949888d78e37ae73 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Tue, 6 Apr 2010 03:59:09 +0000
Subject:

---
 doc/plugins/contrib/ymlfront/discussion.mdwn | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/ymlfront/discussion.mdwn b/doc/plugins/contrib/ymlfront/discussion.mdwn
index f437624b6..ce3b2b483 100644
--- a/doc/plugins/contrib/ymlfront/discussion.mdwn
+++ b/doc/plugins/contrib/ymlfront/discussion.mdwn
@@ -2,3 +2,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]]
+
+> 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]]
-- 
cgit v1.2.3


From 06f58b1b888a6cea1a9a5cce9e098428f0adab75 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Tue, 6 Apr 2010 04:00:47 +0000
Subject: response

---
 doc/plugins/contrib/field/discussion.mdwn | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn
index c2b75a76d..af5bfd6c9 100644
--- a/doc/plugins/contrib/field/discussion.mdwn
+++ b/doc/plugins/contrib/field/discussion.mdwn
@@ -92,3 +92,5 @@ you separated out `ymlfront`. Trivial patch available from
 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>)
 --[[smcv]]
+
+> Can do for the field plugin (delete one line? Easy.)  Will push when I get to a better connection.  --[[KathrynAndersen]]
-- 
cgit v1.2.3


From 2efec70c7e55f9426d7051ffebc6c1eb55afb16b Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Tue, 6 Apr 2010 10:47:28 +0000
Subject: oops, branch returned now

---
 doc/plugins/contrib/ymlfront/discussion.mdwn | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/ymlfront/discussion.mdwn b/doc/plugins/contrib/ymlfront/discussion.mdwn
index ce3b2b483..3ad02af29 100644
--- a/doc/plugins/contrib/ymlfront/discussion.mdwn
+++ b/doc/plugins/contrib/ymlfront/discussion.mdwn
@@ -5,3 +5,7 @@ Joey's code in IkiWiki::Setup::Yaml. Please consider merging :-) --[[smcv]]
 
 > 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]]
+
+>> 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]]
-- 
cgit v1.2.3


From 089a7faff8defe98ffc593702be93f8f35d2153a Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@gnu.kitenet.net>
Date: Tue, 6 Apr 2010 13:25:26 -0400
Subject: first question

---
 doc/plugins/contrib/field/discussion.mdwn | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn
index af5bfd6c9..646a5f3f4 100644
--- a/doc/plugins/contrib/field/discussion.mdwn
+++ b/doc/plugins/contrib/field/discussion.mdwn
@@ -94,3 +94,18 @@ field-etc branch in git://git.pseudorandom.co.uk/git/smcv/ikiwiki.git (gitweb:
 --[[smcv]]
 
 > Can do for the field plugin (delete one line? Easy.)  Will push when I get to a better connection.  --[[KathrynAndersen]]
+
+----
+
+Disclaimer: I've only looked at this plugin and ymlfront, not other related
+stuff yet. (I quite like ymlfront, so I looked at this as its dependency. :)
+I also don't want to annoy you with a lot of design discussion 
+if your main goal was to write a plugin that did exactly what you wanted.
+
+My first question is: Why we need another plugin storing metadata
+about the page, when we already have the meta plugin? Much of the
+complication around the field plugin has to do with it accessing info
+belonging to the meta plugin, and generalizing that to be able to access
+info stored by other plugins too. (But I don't see any other plugins that
+currently store such info). Then too, it raises points of confusion like
+smcv's discuission of field author vs meta author above. --[[Joey]] 
-- 
cgit v1.2.3


From 6fd59908ba8f6999f63c94c918f8c309ed108f74 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@gnu.kitenet.net>
Date: Tue, 6 Apr 2010 14:06:29 -0400
Subject: comment

---
 doc/plugins/contrib/pod/discussion.mdwn | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/pod/discussion.mdwn b/doc/plugins/contrib/pod/discussion.mdwn
index 76e858680..9187b1350 100644
--- a/doc/plugins/contrib/pod/discussion.mdwn
+++ b/doc/plugins/contrib/pod/discussion.mdwn
@@ -8,3 +8,7 @@ supports, or later support latex, that could be problimatic since that
 could maybe be used to include files or run code. --[[Joey]]
 
 > I don't know, either; the documentation for [[!cpan Pod:Xhtml]] is silent on this subject. --[[KathrynAndersen]]
+
+>> I'm afraid the only approach is to audit the existing code in the perl
+>> module(s), and then hope nothing is added to them later that opens a
+>> security hole. --[[Joey]] 
-- 
cgit v1.2.3


From 121405e8aa80e7ceb5283b0ff8c9865458a6dd52 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Tue, 6 Apr 2010 23:09:59 +0000
Subject: response to Joey and smcv

---
 doc/plugins/contrib/field/discussion.mdwn | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn
index 646a5f3f4..b243e2dfe 100644
--- a/doc/plugins/contrib/field/discussion.mdwn
+++ b/doc/plugins/contrib/field/discussion.mdwn
@@ -21,7 +21,9 @@ behaviour, an auxiliary plugin would be easy.)
 >> (like `map`). Is your plan that `meta` should register itself by
 >> default, and `map` and friends should be adapted to
 >> work based on `getfield()` instead of `$pagestate{foo}{meta}`, then?
->>
+
+>>> Based on `field_get_value()`, yes.  That would be my ideal.  Do you think I should implement that as an ikiwiki branch? --[[KathrynAndersen]]
+
 >> (On the site I mentioned, I'm using an unmodified version of `field`,
 >> and currently working around the collision by tagging books' pages
 >> with `bookauthor` instead of `author` in the YAML.) --s
@@ -94,6 +96,7 @@ field-etc branch in git://git.pseudorandom.co.uk/git/smcv/ikiwiki.git (gitweb:
 --[[smcv]]
 
 > Can do for the field plugin (delete one line? Easy.)  Will push when I get to a better connection.  --[[KathrynAndersen]]
+>> Done! -K.A.
 
 ----
 
@@ -109,3 +112,16 @@ belonging to the meta plugin, and generalizing that to be able to access
 info stored by other plugins too. (But I don't see any other plugins that
 currently store such info). Then too, it raises points of confusion like
 smcv's discuission of field author vs meta author above. --[[Joey]] 
+
+> The point is exactly in the generalization, to provide a uniform interface for accessing structured data, no matter what the source of it, whether that be the meta plugin or some other plugin.
+
+> There were a few reasons for this:
+
+>1. In converting my site over from PmWiki, I needed something that was equivalent to PmWiki's Page-Text-Variables (which is how PmWiki implements structured data).
+>2. I also wanted an equivalent of PmWiki's Page-Variables, which, rather than being simple variables, are the return-value of a function.  This gives one a lot of power, because one can do calculations, derive one thing from another.  Heck, just being able to have a "basename" variable is useful.
+>3. I noticed that in the discussion about structured data, it was mired down in disagreements about what form the structured data should take; I wanted to overcome that hurdle by decoupling the form from the content.
+>4. I actually use this to solve (1), because, while I do use ymlfront, initially my pages were in PmWiki format (I wrote (another) unreleased plugin which parses PmWiki format) including PmWiki's Page-Text-Variables for structured data.  So I needed something that could deal with multiple formats.
+
+> So, yes, it does cater to mostly my personal needs, but I think it is more generally useful, also.
+> --[[KathrynAndersen]]
+
-- 
cgit v1.2.3


From 1158fe8f4400943d7a24350c6ac8fee6a95c2bed Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Wed, 7 Apr 2010 02:55:50 +0000
Subject: further discussion, point out potential XSS

---
 doc/plugins/contrib/field/discussion.mdwn | 110 ++++++++++++++++++++++++++++++
 1 file changed, 110 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn
index b243e2dfe..16b40cf06 100644
--- a/doc/plugins/contrib/field/discussion.mdwn
+++ b/doc/plugins/contrib/field/discussion.mdwn
@@ -24,10 +24,64 @@ behaviour, an auxiliary plugin would be easy.)
 
 >>> Based on `field_get_value()`, yes.  That would be my ideal.  Do you think I should implement that as an ikiwiki branch? --[[KathrynAndersen]]
 
+>>>> This doesn't solve cases where certain fields are treated specially; for
+>>>> instance, putting a `\[[!meta permalink]]` on a page is not the same as
+>>>> putting it in `ymlfront` (in the latter case you won't get your
+>>>> `<link>` header), and putting `\[[!meta date]]` is not the same as putting
+>>>> `date` in `ymlfront` (in the latter case, `%pagectime` won't be changed).
+>>>>
+>>>> One way to resolve that would be to have `ymlfront`, or similar, be a
+>>>> front-end for `meta` rather than for `field`, and call
+>>>> `IkiWiki::Plugin::meta::preprocess` (or a refactored-out function that's
+>>>> similar).
+>>>>
+>>>> There are also some cross-site scripting issues (see below)... --[[smcv]]
+
 >> (On the site I mentioned, I'm using an unmodified version of `field`,
 >> and currently working around the collision by tagging books' pages
 >> with `bookauthor` instead of `author` in the YAML.) --s
 
+>> Revisiting this after more thought, the problem here is similar to the
+>> possibility that a wiki user adds a `meta` shortcut
+>> to [[shortcuts]], or conversely, that a plugin adds a `cpan` directive
+>> that conflicts with the `cpan` shortcut that pages already use. (In the
+>> case of shortcuts, this is resolved by having plugin-defined directives
+>> always win.) For plugin-defined meta keywords this is the plugin
+>> author's/wiki admin's problem - just don't enable conflicting plugins! -
+>> but it gets scary when you start introducing things like `ymlfront`, which
+>> allow arbitrary, wiki-user-defined fields, even ones that subvert
+>> other plugins' assumptions.
+>>
+>> The `pagetemplate` hook is particularly alarming because page templates are
+>> evaluated in many contexts, not all of which are subject to the
+>> htmlscrubber or escaping; because the output from `field` isn't filtered,
+>> prefixed or delimited, when combined with an arbitrary-key-setting plugin
+>> like `ymlfront` it can interfere with other plugins' expectations
+>> and potentially cause cross-site scripting exploits. For instance, `inline`
+>> has a `pagetemplate` hook which defines the `FEEDLINKS` template variable
+>> to be a blob of HTML to put in the `<head>` of the page. As a result, this
+>> YAML would be bad:
+>>
+>>     ---
+>>     FEEDLINKS: <script>alert('code injection detected')</script>
+>>     ---
+>>
+>> (It might require a different case combination due to implementation
+>> details, I'm not sure.)
+>>
+>> It's difficult for `field` to do anything about this, because it doesn't
+>> know whether a field is meant to be plain text, HTML, a URL, or something
+>> else.
+>>
+>> If `field`'s `pagetemplate` hook did something more limiting - like
+>> only emitting template variables starting with `field_`, or from some
+>> finite set, or something - then this would cease to be a problem, I think?
+>>
+>> `ftemplate` and `getfield` don't have this problem, as far as I can see,
+>> because their output is in contexts where the user could equally well have
+>> written raw HTML directly; the user can cause themselves confusion, but
+>> can't cause harmful output. --[[smcv]]
+
 From a coding style point of view, the `$CamelCase` variable names aren't
 IkiWiki style, and the `match_foo` functions look as though they could benefit
 from being thin wrappers around a common `&IkiWiki::Plugin::field::match`
@@ -125,3 +179,59 @@ smcv's discuission of field author vs meta author above. --[[Joey]]
 > So, yes, it does cater to mostly my personal needs, but I think it is more generally useful, also.
 > --[[KathrynAndersen]]
 
+>> Is it fair to say, then, that `field`'s purpose is to take other
+>> plugins' arbitrary per-page data, and present it as a single
+>> merged/flattened string => string map per page? From the plugins
+>> here, things you then use that merged map for include:
+>>
+>> * sorting - stolen by [[todo/allow_plugins_to_add_sorting_methods]]
+>> * substitution into pages with Perl-like syntax - `getfield`
+>> * substitution into wiki-defined templates - the `pagetemplate`
+>>   hook
+>> * substitution into user-defined templates - `ftemplate`
+>>
+>> As I mentioned above, the flattening can cause collisions (and in the
+>> `pagetemplate` case, even security problems).
+>>
+>> I wonder whether conflating Page Text Variables with Page Variables
+>> causes `field` to be more general than it needs to be?
+>> To define a Page Variable (function-like field), you need to write
+>> a plugin containing that Perl function; if we assume that `field`
+>> or something resembling it gets merged into ikiwiki, then it's
+>> reasonable to expect third-party plugins to integrate with whatever
+>> scaffolding there is for these (either in an enabled-by-default
+>> plugin that most people are expected to leave enabled, like `meta`
+>> now, or in the core), and it doesn't seem onerous to expect each
+>> plugin that wants to participate in this mechanism to have code to
+>> do so. While it's still contrib, `field` could just have a special case
+>> for the meta plugin, rather than the converse?
+>>
+>> If Page Text Variables are limited to being simple strings as you
+>> suggest over in [[forum/an_alternative_approach_to_structured_data]],
+>> then they're functionally similar to `meta` fields, so one way to
+>> get their functionality would be to extend `meta` so that
+>>
+>>     \[[!meta badger="mushroom"]]
+>>
+>> (for an unrecognised keyword `badger`) would store
+>> `$pagestate{$page}{meta}{badger} = "mushroom"`? Getting this to
+>> appear in templates might be problematic, because a naive
+>> `pagetemplate` hook would have the same problem that `field` combined
+>> with `ymlfront` currently does.
+>>
+>> One disadvantage that would appear if the function-like and
+>> meta-like fields weren't in the same namespace would be that it
+>> wouldn't be possible to switch a field from being meta-like to being
+>> function-like without changing any wiki content that referenced it.
+>>
+>> Perhaps meta-like fields should just *be* `meta` (with the above
+>> enhancement), as a trivial case of function-like fields? That would
+>> turn `ymlfront` into an alternative syntax for `meta`, I think?
+>> That, in turn, would hopefully solve the special-fields problem,
+>> by just delegating it to meta. I've been glad of the ability to define
+>> new ad-hoc fields with this plugin without having to write an extra plugin
+>> to do so (listing books with a `bookauthor` and sorting them by
+>> `"field(bookauthor) title"`), but that'd be just as easy if `meta`
+>> accepted ad-hoc fields?
+>>
+>> --[[smcv]]
-- 
cgit v1.2.3


From e12cd5f293fea9d85c7e4cdc86e2bf9381d5676a Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Wed, 7 Apr 2010 03:03:40 +0000
Subject: update fieldsort plugin again; remove obsolete bug + fix note
 (thanks!)

---
 doc/plugins/contrib/field/discussion.mdwn | 15 ++-------------
 1 file changed, 2 insertions(+), 13 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn
index 16b40cf06..2ea195e5b 100644
--- a/doc/plugins/contrib/field/discussion.mdwn
+++ b/doc/plugins/contrib/field/discussion.mdwn
@@ -131,8 +131,8 @@ I think it should just be part of `field` rather than a separate plugin.
 			error("sort=field requires a parameter");
 		}
 
-		my $left = IkiWiki::Plugin::field::field_get_value($_[2], $_[0]);
-		my $right = IkiWiki::Plugin::field::field_get_value($_[2], $_[1]);
+		my $left = IkiWiki::Plugin::field::field_get_value($_[0], $a);
+		my $right = IkiWiki::Plugin::field::field_get_value($_[0], $b);
 
 		$left = "" unless defined $left;
 		$right = "" unless defined $right;
@@ -141,17 +141,6 @@ I think it should just be part of `field` rather than a separate plugin.
 
 	1;
 
--------
-
-Bug report: `field` has an unnecessary `use YAML::Any`, presumably from before
-you separated out `ymlfront`. Trivial patch available from
-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>)
---[[smcv]]
-
-> Can do for the field plugin (delete one line? Easy.)  Will push when I get to a better connection.  --[[KathrynAndersen]]
->> Done! -K.A.
-
 ----
 
 Disclaimer: I've only looked at this plugin and ymlfront, not other related
-- 
cgit v1.2.3


From 2e9fae5c11d9fabf6270de18d0c26bc251750b09 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 7 Apr 2010 15:12:39 +0000
Subject: response about XSS, meta and pagetemplates

---
 doc/plugins/contrib/field/discussion.mdwn | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn
index 2ea195e5b..dd9342224 100644
--- a/doc/plugins/contrib/field/discussion.mdwn
+++ b/doc/plugins/contrib/field/discussion.mdwn
@@ -224,3 +224,32 @@ smcv's discuission of field author vs meta author above. --[[Joey]]
 >> accepted ad-hoc fields?
 >>
 >> --[[smcv]]
+
+>>> Your point above about cross-site scripting is a valid one, and something I
+>>> hadn't thought of (oops).
+
+>>> I still want to be able to populate pagetemplate templates with field, because I
+>>> use it for a number of things, such as setting which CSS files to use for a
+>>> given page, and, as I said, for titles.  But apart from the titles, I
+>>> realize I've been setting them in places other than the page data itself.
+>>> (Another unreleased plugin, `concon`, uses Config::Context to be able to
+>>> set variables on a per-site, per-directory and a per-page basis).
+
+>>> The first possible solution is what you suggested above: for field to only
+>>> set values in pagetemplate which are prefixed with *field_*.  I don't think
+>>> this is quite satisfactory, since that would still mean that people could
+>>> put un-scrubbed values into a pagetemplate, albeit they would be values
+>>> named field_foo, etc.
+
+>>> An alternative solution would be to classify field registration as "secure"
+>>> and "insecure".  Sources such as ymlfront would be insecure, sources such
+>>> as concon (or the $config hash) would be secure, since they can't be edited
+>>> as pages.  Then, when doing pagetemplate substitution (but not ftemplate
+>>> substitution) the insecure sources could be HTML-escaped.
+
+>>> Another problem, as you point out, is special-case fields, such as a number of
+>>> those defined by `meta`, which have side-effects associated with them, more
+>>> than just providing a value to pagetemplate.  Perhaps `meta` should deal with
+>>> the side-effects, but use `field` as an interface to get the values of those special fields.
+
+>>> --[[KathrynAndersen]]
-- 
cgit v1.2.3


From e46a3b753463e71d8a24c35a5035cfbc47dd4816 Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Wed, 7 Apr 2010 17:39:04 +0000
Subject: "safe" and "unsafe" too simplistic, I suspect

---
 doc/plugins/contrib/field/discussion.mdwn | 49 ++++++++++++++++++++++++++++++-
 1 file changed, 48 insertions(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn
index dd9342224..24c37cc4c 100644
--- a/doc/plugins/contrib/field/discussion.mdwn
+++ b/doc/plugins/contrib/field/discussion.mdwn
@@ -239,13 +239,60 @@ smcv's discuission of field author vs meta author above. --[[Joey]]
 >>> set values in pagetemplate which are prefixed with *field_*.  I don't think
 >>> this is quite satisfactory, since that would still mean that people could
 >>> put un-scrubbed values into a pagetemplate, albeit they would be values
->>> named field_foo, etc.
+>>> named field_foo, etc. --[[KathrynAndersen]]
+
+>>>> They can already do similar; `PERMALINK` is pre-sanitized to
+>>>> ensure that it's a "safe" URL, but if an extremely confused wiki admin was
+>>>> to put `COPYRIGHT` in their RSS/Atom feed's `<link>`, a malicious user
+>>>> could put an unsafe (e.g. Javascript) URL in there (`COPYRIGHT` *is*
+>>>> HTML-scrubbed, but "javascript:alert('pwned!')" is just text as far as a
+>>>> HTML sanitizer is concerned, so it passes straight through). The solution
+>>>> is to not use variables in situations where that variable would be
+>>>> inappropriate. Because `field` is so generic, the definition of what's
+>>>> appropriate is difficult. --[[smcv]]
 
 >>> An alternative solution would be to classify field registration as "secure"
 >>> and "insecure".  Sources such as ymlfront would be insecure, sources such
 >>> as concon (or the $config hash) would be secure, since they can't be edited
 >>> as pages.  Then, when doing pagetemplate substitution (but not ftemplate
 >>> substitution) the insecure sources could be HTML-escaped.
+>>> --[[KathrynAndersen]]
+
+>>>> Whether you trust the supplier of data seems orthogonal to whether its value
+>>>> is (meant to be) interpreted as plain text, HTML, a URL or what?
+>>>>
+>>>> Even in cases where you trust the supplier, you need to escape things
+>>>> suitably for the context, not for security but for correctness. The
+>>>> definition of the value, and the context it's being used in, changes the
+>>>> processing you need to do. An incomplete list:
+>>>>
+>>>> * HTML used as HTML needs to be html-scrubbed if and only if untrusted
+>>>> * URLs used as URLs need to be put through `safeurl()` if and only if
+>>>>   untrusted
+>>>> * HTML used as plain text needs tags removed regardless
+>>>> * URLs used as plain text are safe
+>>>> * URLs or plain text used in HTML need HTML-escaping (and URLs also need
+>>>>   `safeurl()` if untrusted)
+>>>> * HTML or plain text used in URLs need URL-escaping (and the resulting
+>>>>   URL might need sanitizing too?)
+>>>>
+>>>> I can't immediately think of other data types we'd be interested in beyond
+>>>> text, HTML and URL, but I'm sure there are plenty.
+>>>>
+>>>> One reasonable option would be to declare that `field` takes text-valued
+>>>> fields, in which case either consumers need to escape
+>>>> it with `<TMPL_VAR FIELD_FOO ESCAPE=HTML>`, and not interpret it as a URL
+>>>> without first checking `safeurl`), or the pagetemplate hook needs to
+>>>> pre-escape.
+>>>>
+>>>> Another reasonable option would be to declare that `field` takes raw HTML,
+>>>> in which case consumers need to only use it in contexts that will be
+>>>> HTML-scrubbed (but it becomes unsuitable for using as text - problematic
+>>>> for text-based things like sorting or URLs, and not ideal for searching).
+>>>>
+>>>> You could even let each consumer choose how it's going to use the field,
+>>>> by having the `foo` field generate `TEXT_FOO` and `HTML_FOO` variables?
+>>>> --[[smcv]]
 
 >>> Another problem, as you point out, is special-case fields, such as a number of
 >>> those defined by `meta`, which have side-effects associated with them, more
-- 
cgit v1.2.3


From 15a65ffae67b7eaf2702b3a42edee95daf8f4c89 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 7 Apr 2010 23:29:25 +0000
Subject: further response to smcv on pagetemplates

---
 doc/plugins/contrib/field/discussion.mdwn | 27 +++++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn
index 24c37cc4c..36c2118e7 100644
--- a/doc/plugins/contrib/field/discussion.mdwn
+++ b/doc/plugins/contrib/field/discussion.mdwn
@@ -278,13 +278,34 @@ smcv's discuission of field author vs meta author above. --[[Joey]]
 >>>>
 >>>> I can't immediately think of other data types we'd be interested in beyond
 >>>> text, HTML and URL, but I'm sure there are plenty.
->>>>
+
+>>>>> But isn't this a problem with anything that uses pagetemplates?  Or is
+>>>>> the point that, with plugins other than `field`, they all know,
+>>>>> beforehand, the names of all the fields that they are dealing with, and
+>>>>> thus the writer of the plugin knows which treatment each particular field
+>>>>> needs?  For example, that `meta` knows that `title` needs to be
+>>>>> HTML-escaped, and that `baseurl` doesn't.  In that case, yes, I see the problem.
+>>>>> It's a tricky one.  It isn't as if there's only ever going to be a fixed set of fields that need different treatment, either.  Because the site admin is free to add whatever fields they like to the page template (if they aren't using the default one, that is.  I'm not using the default one myself).
+>>>>> Mind you, for trusted sources, since the person writing the page template and the person providing the variable are the same, they themselves would know whether the value will be treated as HTML, plain text, or a URL, and thus could do the needed escaping themselves when writing down the value.
+
+>>>>> Looking at the content of the default `page.tmpl` let's see what variables fall into which categories:
+>>>>> * Used as URL: BASEURL, EDITURL, PARENTLINKS->URL, RECENTCHANGESURL, HISTORYURL, GETSOURCEURL, PREFSURL, OTHERLANGUAGES->URL, ADDCOMMENTURL, BACKLINKS->URL, MORE_BACKLINKS->URL
+>>>>> * Used as part of a URL: FAVICON, LOCAL_CSS
+>>>>> * Needs to be HTML-escaped: TITLE
+>>>>> * Used as-is (as HTML): FEEDLINKS, RELVCS, META, PERCENTTRANSLATED, SEARCHFORM, COMMENTSLINK, DISCUSSIONLINK, OTHERLANGUAGES->PERCENT, SIDEBAR, CONTENT, COMMENTS, TAGS->LINK, COPYRIGHT, LICENSE, MTIME, EXTRAFOOTER
+
+>>>>> This looks as if only TITLE needs HTML-escaping all the time, and that the URLS all end with "URL" in their name.  Unfortunately the FAVICON and LOCAL_CSS which are part of URLS don't have "URL" in their name, though that's fair enough, since they aren't full URLs.
+
+>>>>>  --K.A.
+
 >>>> One reasonable option would be to declare that `field` takes text-valued
 >>>> fields, in which case either consumers need to escape
 >>>> it with `<TMPL_VAR FIELD_FOO ESCAPE=HTML>`, and not interpret it as a URL
 >>>> without first checking `safeurl`), or the pagetemplate hook needs to
 >>>> pre-escape.
->>>>
+
+>>>>> Since HTML::Template does have the ability to do ESCAPE=HTML/URL/JS, why not take advantage of that? Some things, like TITLE, probably should have ESCAPE=HTML all the time; that would solve the "to escape or not to escape" problem that `meta` has with titles. After all, when one *sorts* by title, one doesn't really want HTML-escaping in it; only when one uses it in a template. -- K.A.
+
 >>>> Another reasonable option would be to declare that `field` takes raw HTML,
 >>>> in which case consumers need to only use it in contexts that will be
 >>>> HTML-scrubbed (but it becomes unsuitable for using as text - problematic
@@ -294,6 +315,8 @@ smcv's discuission of field author vs meta author above. --[[Joey]]
 >>>> by having the `foo` field generate `TEXT_FOO` and `HTML_FOO` variables?
 >>>> --[[smcv]]
 
+>>>>> Something similar is already done in `template` and `ftemplate` with the `raw_` prefix, which determines whether the variable should have `htmlize` run over it first before the value is applied to the template.  Of course, that isn't scrubbing or escaping, because with those templates, the scrubbing is done afterwards as part of the normal processing.
+
 >>> Another problem, as you point out, is special-case fields, such as a number of
 >>> those defined by `meta`, which have side-effects associated with them, more
 >>> than just providing a value to pagetemplate.  Perhaps `meta` should deal with
-- 
cgit v1.2.3


From ce9cf967d01eb8e112c19d9f7b1c9a727717ef30 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 7 Apr 2010 23:33:04 +0000
Subject: formatting

---
 doc/plugins/contrib/field/discussion.mdwn | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn
index 36c2118e7..103e061e5 100644
--- a/doc/plugins/contrib/field/discussion.mdwn
+++ b/doc/plugins/contrib/field/discussion.mdwn
@@ -289,10 +289,11 @@ smcv's discuission of field author vs meta author above. --[[Joey]]
 >>>>> Mind you, for trusted sources, since the person writing the page template and the person providing the variable are the same, they themselves would know whether the value will be treated as HTML, plain text, or a URL, and thus could do the needed escaping themselves when writing down the value.
 
 >>>>> Looking at the content of the default `page.tmpl` let's see what variables fall into which categories:
->>>>> * Used as URL: BASEURL, EDITURL, PARENTLINKS->URL, RECENTCHANGESURL, HISTORYURL, GETSOURCEURL, PREFSURL, OTHERLANGUAGES->URL, ADDCOMMENTURL, BACKLINKS->URL, MORE_BACKLINKS->URL
->>>>> * Used as part of a URL: FAVICON, LOCAL_CSS
->>>>> * Needs to be HTML-escaped: TITLE
->>>>> * Used as-is (as HTML): FEEDLINKS, RELVCS, META, PERCENTTRANSLATED, SEARCHFORM, COMMENTSLINK, DISCUSSIONLINK, OTHERLANGUAGES->PERCENT, SIDEBAR, CONTENT, COMMENTS, TAGS->LINK, COPYRIGHT, LICENSE, MTIME, EXTRAFOOTER
+
+>>>>> * **Used as URL:** BASEURL, EDITURL, PARENTLINKS->URL, RECENTCHANGESURL, HISTORYURL, GETSOURCEURL, PREFSURL, OTHERLANGUAGES->URL, ADDCOMMENTURL, BACKLINKS->URL, MORE_BACKLINKS->URL
+>>>>> * **Used as part of a URL:** FAVICON, LOCAL_CSS
+>>>>> * **Needs to be HTML-escaped:** TITLE
+>>>>> * **Used as-is (as HTML):** FEEDLINKS, RELVCS, META, PERCENTTRANSLATED, SEARCHFORM, COMMENTSLINK, DISCUSSIONLINK, OTHERLANGUAGES->PERCENT, SIDEBAR, CONTENT, COMMENTS, TAGS->LINK, COPYRIGHT, LICENSE, MTIME, EXTRAFOOTER
 
 >>>>> This looks as if only TITLE needs HTML-escaping all the time, and that the URLS all end with "URL" in their name.  Unfortunately the FAVICON and LOCAL_CSS which are part of URLS don't have "URL" in their name, though that's fair enough, since they aren't full URLs.
 
-- 
cgit v1.2.3


From 27cb77cd1919d5c61ba67333a349ab6e54ed5976 Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Sun, 9 May 2010 18:11:51 +0000
Subject: updated branch, using add_autopage to spawn viewer pages

---
 doc/plugins/contrib/album.mdwn | 173 ++++++++++++++++++++++++++---------------
 1 file changed, 110 insertions(+), 63 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/album.mdwn b/doc/plugins/contrib/album.mdwn
index 395c99bce..0393d26dc 100644
--- a/doc/plugins/contrib/album.mdwn
+++ b/doc/plugins/contrib/album.mdwn
@@ -9,9 +9,11 @@ thoughts about this plugin).
 This plugin formats a collection of images into a photo album,
 in the same way as many websites: good examples include the
 PHP application [Gallery](http://gallery.menalto.com/), Flickr,
-and Facebook's Photos "application". I've called it `album`
-to distinguish it from [[contrib/gallery|plugins/contrib/gallery]],
-although `gallery` might well be a better name for this functionality.
+and Facebook's Photos "application".
+
+I've called it `album` to distinguish it from
+[[contrib/gallery|plugins/contrib/gallery]], although `gallery` might well be
+a better name for this functionality.
 
 The web UI I'm trying to achieve consists of one
 [HTML page of thumbnails](http://www.pseudorandom.co.uk/2008/2008-03-08-panic-cell-gig/)
@@ -26,83 +28,128 @@ individual photos can't be bookmarked in a meaningful way, and
 the best it can do as a fallback for non-Javascript browsers
 is to provide a direct link to the image.)
 
-## Writing the viewers
+<h2 id="album"><code>album</code> directive</h2>
+
+Each page containing an `album` directive is treated as a photo album.
+
+Every image attached to an album or its subpages is considered to be part of
+the album. A "viewer" page, with the wiki's default page extension, will be
+generated to display the image, if there isn't already a page of the same
+name as the image: for instance, if `debconf` is an album and
+`debconf/tuesday/p100.jpg` exists, then `debconf/tuesday/p100.mdwn` might
+be created.
+
+There's currently a hard-coded list of extensions that are treated as images:
+`png`, `gif`, `jpg`, `jpeg` or `mov` files. More image and video types could
+be added in future. Videos aren't currently handled very well;
+ideally, something like totem-video-thumbnailer would be used.
+
+The `album` directive also produces an [[ikiwiki/directive/inline]] which
+automatically includes all the viewers for this album, except those that
+will appear in an <a href="#albumsection">albumsection</a> (if every image
+is in a section, then the `album` directive won't have any visible effect).
 
-    \[[!albumimage image=foo.jpg album=myalbum
-        title=...
-        caption=...
-        copyright=...
-        size=...
-        viewertemplate=...
-    ]]
+The `inline` is in `archive` and `quick` mode, but can include some
+extra information about the images, including file size and a thumbnail made
+using [[ikiwiki/directive/img]]). The default template is `albumitem.tmpl`,
+which takes advantage of these things.
 
-Each viewer contains one `\[[!albumimage]]` directive. This
-sets the `image` filename, the `album` in which this image appears,
-and an optional `caption`, and can override the `size` at which to
-display the image and the `viewertemplate` to use to display the
-image.
+<h2 id="albumsection"><code>albumsection</code> directive</h2>
 
-It can also have `title`, `copyright` and `date` parameters, which
-are short-cuts for [[ikiwiki/directive/meta]] directives.
+The `albumsection` directive is used to split an album into sections. It can
+only appear on a page that also has the <a href="#album">album</a> directive.
+
+The `filter` parameter is a [[ikiwiki/PageSpec]] against which viewer pages
+are matched. The `albumsection` directive displays all the images that match
+the filter, and the `album` directive displays any leftover images, like
+this:
+
+    # Holiday photos
+
+    \[[!album]]
+    <!-- replaced with a list of any uncategorized photos, which might be
+         empty -->
 
-The viewer can also have any other content, but typically the
-directive will be the only thing there.
+    ## People
 
-Eventually, there will be a specialized CGI user interface to
-edit all the photos of an album at once, upload a new photo
-(which will attach the photo but also write out a viewer page
-for it), or mark an already-uploaded photo as a member of an
-album (which is done by writing out a viewer page for it).
+    \[[!albumsection filter="tagged(people)"]]
+    <!-- replaced with a list of photos tagged 'people', including
+         any that are also tagged 'landscapes' -->
 
-The `\[[!albumimage]]` directive is replaced by an
+    ## Landscapes
+
+    \[[!albumsection filter="tagged(landscapes)"]]
+    <!-- replaced with a list of photos tagged 'landscapes', including
+         any that are also tagged 'people' -->
+
+<h2 id="albumimage"><code>albumimage</code> directive</h2>
+
+Each viewer page produced by the <a href="#album">album</a> directive
+contains an `albumimage` directive, which is replaced by an
 [[ikiwiki/directive/img]], wrapped in some formatting using a
-template (by default `albumviewer.tmpl`). The template can (and
-should) also include "next photo", "previous photo" and
-"up to gallery" links.
+template (by default it's `albumviewer.tmpl`). That template can also include
+links to the next photo, the previous photo and the album it's in; the default
+template has all of these.
 
-The next/previous links are themselves implemented by
-[[inlining|ikiwiki/directive/inline]] the next or previous
-photo, using a special template (by default `albumnext.tmpl`
-or `albumprev.tmpl`), in `archive`/`quick` mode.
+The next/previous links are themselves implemented by evaluating a template,
+either `albumnext.tmpl` or `albumprev.tmpl` by default.
 
-> With hindsight, using an inline here is wrong - I should just
-> run hooks and fill in the template within the album plugin.
-> inline has some specialized functionality that's overkill
-> here, and its delayed HTML substitution breaks the ability
-> to have previous/up/next links both above and below the
-> photo, for instance. --[[smcv]]
+The directive can also have parameters:
 
-## Writing the album
+* `title`, `copyright` and `date` are short-cuts for the corresponding
+  [[ikiwiki/directive/meta]] directives
 
-The album contains one `\[[!album]]` directive. It may also
-contain any number of `\[[!albumsection]]` directives, for
-example the demo album linked above could look like:
+* `caption` sets a caption which is displayed in the album and viewer
+  pages
 
-    \[[!album]]
-    <!-- replaced with one uncategorized photo -->
+The viewer page can also have other contents before or after the actual
+image viewer.
+
+## Bugs
+
+* The plugin doesn't do anything special to handle albums that are subpages
+  of each other. If, say, `debconf` and `debconf/monday` are both albums,
+  then `debconf/monday/p100.jpg` will currently be assigned to one or the
+  other, arbitrarily.
+
+* The plugin doesn't do anything special to handle photos with similar names.
+  If you have `p100.jpg` and `p100.png`, one will get a viewer page called
+  `p100` and the other will be ignored.
+
+* If there's no `albumimage` in a viewer page, one should probably be appended
+  automatically.
 
-    ## Gamarra
+## TODO
 
-    \[[!albumsection filter="link(gamarra)"]]
-    <!-- all the Gamarra photos -->
+* The documentation should mention how to replicate the appearance of
+  `album` and `albumsection` using an `inline` of viewer pages.
 
-    ## Smokescreen
+* The documentation should mention all the template variables and
+  all the parameters.
 
-    \[[!albumsection filter="link(smokescreen)"]]
-    <!-- all the Smokescreen photos -->
+* The generated viewer page should include most or all of the possible
+  parameters to the `albumimage` directive, with empty values, as a
+  template for editing.
 
-    ...
+* The generated viewer page should extract as much metadata as possible from
+  the photo's EXIF tags (creation/modification dates, author, title, caption,
+  copyright). [[smcv]] has a half-written implementation which runs
+  `scanimage` hooks, and has an `exiftool` plugin using [[!cpan Image::ExifTool]].
 
-The `\[[!album]]` directive is replaced by an
-[[ikiwiki/directive/inline]] which automatically includes every
-page that has an `\[[!albumimage]]` directive linking it to this
-album, except those that will appear in an `\[[!albumsection]]`.
+* There should be an option to reduce the size of photos and write them into
+  an underlay, for this workflow:
 
-The `inline` is in `archive`/`quick` mode, but includes some
-extra information about the images, including file size and a
-thumbnail (again, made using [[ikiwiki/directive/img]]). The
-default template is `albumitem.tmpl`, which takes advantage
-of these things.
+  * your laptop's local ikiwiki has two underlays, `photos` and `webphotos`
+  * `photos` contains full resolution photos with EXIF tags
+  * for each photo that exists in `photos` but not in `webphotos`, the album
+    plugin automatically resamples it down to a web-compatible resolution
+    ([[smcv]] uses up to 640x640), optimizes it with `jpegoptim`, strips out
+    all EXIF tags, and and writes it into the corresponding location
+    in `webphotos`
+  * `webphotos` is what you rsync to the web server
+  * the web server's ikiwiki only has `webphotos` as an underlay
 
-Each `\[[!albumsection]]` is replaced by a similar inline, which
-selects a subset of the photos in the album.
+* Eventually, there could be a specialized CGI user interface to batch-edit
+  all the photos of an album (so for each photo, you get an edit box each for
+  title, author, copyright etc.) - this would work by making programmatic
+  edits to all the `albumimage` directives.
-- 
cgit v1.2.3


From 0594ea04a811a59120ea7e91e94c3389ffcd33ca Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Sun, 9 May 2010 18:13:05 +0000
Subject: clarify

---
 doc/plugins/contrib/album.mdwn | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/album.mdwn b/doc/plugins/contrib/album.mdwn
index 0393d26dc..3cfcb68d4 100644
--- a/doc/plugins/contrib/album.mdwn
+++ b/doc/plugins/contrib/album.mdwn
@@ -134,7 +134,8 @@ image viewer.
 * The generated viewer page should extract as much metadata as possible from
   the photo's EXIF tags (creation/modification dates, author, title, caption,
   copyright). [[smcv]] has a half-written implementation which runs
-  `scanimage` hooks, and has an `exiftool` plugin using [[!cpan Image::ExifTool]].
+  `scanimage` hooks, and has an `exiftool` plugin using [[!cpan Image::ExifTool]]
+  as a reference implementation of that hook.
 
 * There should be an option to reduce the size of photos and write them into
   an underlay, for this workflow:
-- 
cgit v1.2.3


From 3f7ef01ca22963dc253d76a27a711dd18998606c Mon Sep 17 00:00:00 2001
From: "http://smcv.pseudorandom.co.uk/" <http://smcv.pseudorandom.co.uk/@web>
Date: Sun, 9 May 2010 18:27:58 +0000
Subject: respond with better design

---
 doc/plugins/contrib/album/discussion.mdwn | 41 +++++++++++++++++++++++++++----
 1 file changed, 36 insertions(+), 5 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/album/discussion.mdwn b/doc/plugins/contrib/album/discussion.mdwn
index 9720589b4..0356860d8 100644
--- a/doc/plugins/contrib/album/discussion.mdwn
+++ b/doc/plugins/contrib/album/discussion.mdwn
@@ -46,6 +46,10 @@ secondly: barring the CGI interface for editing the album, which would be great,
 >
 > --[[smcv]]
 
+>> In the current version of the branch, the viewer pages are
+>> generated automatically if you didn't generate them yourself,
+>> so `ikiwiki-album` is no longer needed. --[[smcv]]
+
 i'm new to ikiwiki, apologies if this is dealt with elsewhere.  -brush
 
 > This plugin is pretty ambitious, and is unfinished, so I'd recommend
@@ -80,6 +84,10 @@ code or tried it yet, but here goes. --[[Joey]]
 >> an image with a strange extension to a differing target filename
 >> with the normal extension, respectively). -s
 
+>>> Now that we have `add_autofile` I can just create viewer pages
+>>> whenever there's an image to view. The current version of the
+>>> branch does that. -s
+
 * With each viewer page having next/prev links, I can see how you
   were having the scalability issues with ikiwiki's data structures
   earlier! -J
@@ -94,6 +102,8 @@ code or tried it yet, but here goes. --[[Joey]]
 >> (Unless you use img to make the thumbnails for those links, then it
 >> would rebuild the thumbnails anyway. Have not looked at the code.) --[[Joey]]
 
+>>> I do use img. -s
+
 * And doesn't each viewer page really depend on every other page in the
   same albumsection? If a new page is added, the next/prev links
   may need to be updated, for example. If so, there will be much
@@ -142,13 +152,20 @@ code or tried it yet, but here goes. --[[Joey]]
 > one album: if they're subpages of 2+ nested albums then they're only
 > considered to be in the deepest-nested one (i.e. longest URL), and if
 > they're not in any album then that's a usage error. This would
-> also make prev/next links sane.
->
+> also make prev/next links sane. -s
+
+>> The current version constrains images to be in at most one album,
+>> choosing one arbitrarily (dependent on scan order) if albums are
+>> nested. -s
+
 > If you want to reference images from elsewhere in the wiki and display
 > them as if in an album, then you can use an ordinary inline with
 > the same template that the album would use, and I'll make sure the
-> templates are set up so this works.
->
+> templates are set up so this works. -s
+
+>> Still needs documenting, I've put it on the TODO list on the main
+>> page. -s
+
 > (Implementation detail: this means that an image X/Y/Z/W/V, where X and
 > Y are albums, Z does not exist and W exists but is not an album,
 > would have a content dependency on Y, a presence dependency on Z
@@ -158,6 +175,12 @@ code or tried it yet, but here goes. --[[Joey]]
 > subpages of the album, although that would mean breaking some URLs
 > on the existing website I'm doing all this work for... -s
 
+>> The current version of the branch doesn't have this restriction;
+>> perhaps it's a worthwhile simplification, or perhaps it's too
+>> restrictive? I fairly often use directory hierarchies like
+>> `a_festival/saturday/foo.jpg` within an album, which makes
+>> it very easy to write `albumsection` filters. -s
+
 * Putting a few of the above thoughts together, my ideal album system
   seems to be one where I can just drop the images into a directory and
   have them appear in the album index, as well as each generate their own wiki
@@ -195,6 +218,10 @@ code or tried it yet, but here goes. --[[Joey]]
 >> upload-and-rename.
 >> -s
 
+>>> I believe the current branch meets your requirements, by having
+>>> first-class wiki pages spring into existence using `add_autofile`
+>>> to be viewer pages for photos. -s
+
 > In a way, what you really want for metadata is to have it in the album
 > page, so you can batch-edit the whole lot by editing one file (this
 > does mean that editing the album necessarily causes each of its viewers
@@ -214,6 +241,9 @@ code or tried it yet, but here goes. --[[Joey]]
 >> (That's apparently good enough for Bugzilla, but not really
 >> for ikiwiki). -s
 
+>>> This is now in the main page's TODO list; if/when I implement this,
+>>> I intend to make it a specialized CGI interface. -s
+
 >> Yes, [all metadata in one file] would make some sense.. It also allows putting one image in
 >> two albums, with different caption etc. (Maybe for different audiences.)
 >> --[[Joey]]
@@ -229,7 +259,8 @@ code or tried it yet, but here goes. --[[Joey]]
 
 ----
 
-Trying to use the "special extension" design:
+'''I think the "special extension" design is a dead-end, but here's what
+happened when I tried to work out how it would work. --[[smcv]]'''
 
 Suppose that each viewer is a JPEG-or-GIF-or-something, with extension
 ".albumimage". We have a gallery "memes" with three images, badger,
-- 
cgit v1.2.3


From 72d7b8dc54d4dccc3100fddc23b9a245f62d3521 Mon Sep 17 00:00:00 2001
From: BerndZeimetz <BerndZeimetz@web>
Date: Wed, 12 May 2010 09:20:31 +0000
Subject: Add short page about contrib / tracking plugin

---
 doc/plugins/contrib/tracking.mdwn | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)
 create mode 100644 doc/plugins/contrib/tracking.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/tracking.mdwn b/doc/plugins/contrib/tracking.mdwn
new file mode 100644
index 000000000..ee01b261b
--- /dev/null
+++ b/doc/plugins/contrib/tracking.mdwn
@@ -0,0 +1,30 @@
+[[!template id=plugin name=ftemplate author="[[BerndZeimetz]]"]]
+[[!toc]]
+[[!tag plugins]] [[!tag patch]] [[!tag wishlist]]
+
+## NAME
+
+IkiWiki::Plugin::tracking - enable google/piwik visitor tracking
+
+## SYNOPSIS
+
+    # activate the plugin
+    add_plugins => [qw{goodstuff tracking ....}],
+
+    # to use Piwik:
+    piwik_id => '1',
+    piwik_https_url => "https://ssl.example.com/piwik/",
+    piwik_http_url => "http://www.example.com/piwik/",
+
+    # to use Google Analytics:
+    google_analytics_id => "UA-xxxxxx-x"
+
+## DESCRIPTION
+
+This plugin includes the necessary tracking codes for Piwik and/or Google Analytics on all pages. Tracking codes will only be included if the necessary config options are set. The plugin could be enhanced to support goals/profiles and similar things, but I do not plan to do so.
+
+## DOWNLOAD
+
+* single files: [tracking.pm](http://git.recluse.de/?p=users/bzed/ikiwiki.git;a=blob;f=IkiWiki/Plugin/tracking.pm;hb=refs/heads/tracking) [piwik.tmpl](http://git.recluse.de/?p=users/bzed/ikiwiki.git;a=blob;f=templates/piwik.tmpl;hb=refs/heads/tracking) [google_analytics.tmpl](http://git.recluse.de/?p=users/bzed/ikiwiki.git;a=blob;f=templates/google_analytics.tmpl;hb=refs/heads/tracking)
+* browse repository: <http://git.recluse.de/?p=users/bzed/ikiwiki.git;a=shortlog;h=refs/heads/tracking>
+* git repo: `git://git.recluse.de/users/bzed/ikiwiki.git` or <http://git.recluse.de/repos/users/bzed/ikiwiki.git> (Use the tracking branch)
-- 
cgit v1.2.3


From 1805bfbb5dd24ed23418ceee00524f4dd658993e Mon Sep 17 00:00:00 2001
From: BerndZeimetz <BerndZeimetz@web>
Date: Wed, 12 May 2010 09:21:40 +0000
Subject: ... choose the right name....

---
 doc/plugins/contrib/tracking.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/tracking.mdwn b/doc/plugins/contrib/tracking.mdwn
index ee01b261b..06d4120cd 100644
--- a/doc/plugins/contrib/tracking.mdwn
+++ b/doc/plugins/contrib/tracking.mdwn
@@ -1,4 +1,4 @@
-[[!template id=plugin name=ftemplate author="[[BerndZeimetz]]"]]
+[[!template id=plugin name=tracking author="[[BerndZeimetz]]"]]
 [[!toc]]
 [[!tag plugins]] [[!tag patch]] [[!tag wishlist]]
 
-- 
cgit v1.2.3


From 2451d3927863534a863b84d9d90bf277e42711b2 Mon Sep 17 00:00:00 2001
From: jwalck <jwalck@web>
Date: Mon, 17 May 2010 04:03:03 +0000
Subject:

---
 doc/plugins/contrib/flattr.mdwn | 45 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 doc/plugins/contrib/flattr.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/flattr.mdwn b/doc/plugins/contrib/flattr.mdwn
new file mode 100644
index 000000000..d40465971
--- /dev/null
+++ b/doc/plugins/contrib/flattr.mdwn
@@ -0,0 +1,45 @@
+[[!template id=plugin name=flattr author="[[jaywalk]]"]]
+
+[flattr.com](http://flattr.com/) is a flatrate micropayment service, which revolves around the idea of having flattr buttons everywhere that people visiting your site can use to "flattr" you.
+
+This plugin makes it easier to put flattr buttons in ikiwiki. It supports both the static kind as well as the counting dynamic javascript version. The dynamic version does not work if [[htmlscrubber|/plugins/htmlscrubber]] is active on the page.
+
+The dynamic button does not require creation of the page on flattr before being added to a page, the static one does.
+
+I wrote some notes on [jonatan.walck.se](http://jonatan.walck.se/software/ikiwiki/plugins/flattr/) and put the source here: [flattr.pm](http://jonatan.walck.se/software/ikiwiki/flattr.pm)
+
+This plugin is licensed under CC0.
+
+# Usage #
+
+    # [[!flattr args]] where args are in the form of arg=value.
+    # Possible args:
+    # type - static or dynamic. Defaults to static.
+
+    # vars in static mode:
+    # --------------------
+    # Required:
+    # url - URL to flattr page,
+    # e.g. http://flattr.com/thing/1994/jaywalks-weblog
+    # Optional: 
+    # btn - Set to compact for compact button.
+
+    # vars in dynamic mode:
+    # ---------------------
+    # Required:
+    # None.
+    # Optional:
+    # uid - Set the default in the plugin, override if needed.
+    # tle - The title defaults to $wikiname/some/path (like on the top of
+    #   the wiki).
+    # dsc - A description of the content. Defaults to " ".
+    # cat - Category, this can be text, images, video, audio, software or
+    #   rest. Defaults to text.
+    # lng - Language, list of available choises is on
+    #   https://flattr.com/support/integrate/languages. Defaults to en_GB.
+    # tag - A list of comma separated tags. Empty per default.
+    # url - URL to thing to flattred,
+    #   e.g. http://jonatan.walck.se/weblog
+    # btn - Set it to compact to get the small button, big for any other
+    #   value including empty.
+    
-- 
cgit v1.2.3


From f2304367f6820813e699eaeafaad4804de033753 Mon Sep 17 00:00:00 2001
From: jwalck <jwalck@web>
Date: Mon, 17 May 2010 04:04:50 +0000
Subject:

---
 doc/plugins/contrib/flattr.mdwn | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/flattr.mdwn b/doc/plugins/contrib/flattr.mdwn
index d40465971..76d4d7b1d 100644
--- a/doc/plugins/contrib/flattr.mdwn
+++ b/doc/plugins/contrib/flattr.mdwn
@@ -22,7 +22,7 @@ This plugin is licensed under CC0.
     # url - URL to flattr page,
     # e.g. http://flattr.com/thing/1994/jaywalks-weblog
     # Optional: 
-    # btn - Set to compact for compact button.
+    # style - Set to compact for compact button.
 
     # vars in dynamic mode:
     # ---------------------
@@ -30,16 +30,16 @@ This plugin is licensed under CC0.
     # None.
     # Optional:
     # uid - Set the default in the plugin, override if needed.
-    # tle - The title defaults to $wikiname/some/path (like on the top of
+    # title - The title defaults to $wikiname/some/path (like on the top of
     #   the wiki).
-    # dsc - A description of the content. Defaults to " ".
+    # desc - A description of the content. Defaults to " ".
     # cat - Category, this can be text, images, video, audio, software or
     #   rest. Defaults to text.
-    # lng - Language, list of available choises is on
+    # lang - Language, list of available choises is on
     #   https://flattr.com/support/integrate/languages. Defaults to en_GB.
     # tag - A list of comma separated tags. Empty per default.
     # url - URL to thing to flattred,
     #   e.g. http://jonatan.walck.se/weblog
-    # btn - Set it to compact to get the small button, big for any other
+    # style - Set it to compact to get the small button, big for any other
     #   value including empty.
     
-- 
cgit v1.2.3


From 7cae2951248245cb8b4da69d0f28065c394b31a2 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@kitenet.net>
Date: Mon, 17 May 2010 00:42:52 -0400
Subject: on javascript, plugins, and htmlscrubber

---
 doc/plugins/contrib/flattr/discussion.mdwn | 4 ++++
 1 file changed, 4 insertions(+)
 create mode 100644 doc/plugins/contrib/flattr/discussion.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/flattr/discussion.mdwn b/doc/plugins/contrib/flattr/discussion.mdwn
new file mode 100644
index 000000000..98b7771c5
--- /dev/null
+++ b/doc/plugins/contrib/flattr/discussion.mdwn
@@ -0,0 +1,4 @@
+FWIW, it is possible for a plugin like this to add javascript to pages that
+are protected by htmlscrubber. Just return a token in your preprocess hook,
+and then have a format hook that replaces the token with the javascript.
+--[[Joey]] 
-- 
cgit v1.2.3


From 744919eba0448c2d7494f57b89afa2d27dde5fbd Mon Sep 17 00:00:00 2001
From: jwalck <jwalck@web>
Date: Mon, 17 May 2010 04:52:27 +0000
Subject:

---
 doc/plugins/contrib/flattr/discussion.mdwn | 5 +++++
 1 file changed, 5 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/flattr/discussion.mdwn b/doc/plugins/contrib/flattr/discussion.mdwn
index 98b7771c5..586139e9c 100644
--- a/doc/plugins/contrib/flattr/discussion.mdwn
+++ b/doc/plugins/contrib/flattr/discussion.mdwn
@@ -2,3 +2,8 @@ FWIW, it is possible for a plugin like this to add javascript to pages that
 are protected by htmlscrubber. Just return a token in your preprocess hook,
 and then have a format hook that replaces the token with the javascript.
 --[[Joey]] 
+
+> Thanks, That's good to know. I'll try to continue the development of this
+> plugin later, for now I just needed it to work. :) It will most likely
+> evolve as my page does too.
+> --[[jaywalk]]
-- 
cgit v1.2.3


From ddb4f2410486f46255c4909bbb43b75c4b08f308 Mon Sep 17 00:00:00 2001
From: jwalck <jwalck@web>
Date: Mon, 17 May 2010 04:56:44 +0000
Subject:

---
 doc/plugins/contrib/flattr/jaywalk.mdwn | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 doc/plugins/contrib/flattr/jaywalk.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/flattr/jaywalk.mdwn b/doc/plugins/contrib/flattr/jaywalk.mdwn
new file mode 100644
index 000000000..31b3e0c4d
--- /dev/null
+++ b/doc/plugins/contrib/flattr/jaywalk.mdwn
@@ -0,0 +1,5 @@
+Jonatan Walck. Home page: [jonatan.walck.se](http://jonatan.walck.se)
+
+## Contact ##
+* jonatan at walck dot se
+* [I2P-Bote key](http://jonatan.walck.i2p/docs/i2p-bote.txt) [what is this?](http://i2pbote.i2p.to/)
-- 
cgit v1.2.3


From b7777931e2ade5e71b7e1b82e5ab12138e63ec96 Mon Sep 17 00:00:00 2001
From: "http://jmtd.livejournal.com/" <http://jmtd.livejournal.com/@web>
Date: Mon, 17 May 2010 17:12:22 +0000
Subject: fix link

---
 doc/plugins/contrib/flattr.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/flattr.mdwn b/doc/plugins/contrib/flattr.mdwn
index 76d4d7b1d..fb532f44c 100644
--- a/doc/plugins/contrib/flattr.mdwn
+++ b/doc/plugins/contrib/flattr.mdwn
@@ -6,7 +6,7 @@ This plugin makes it easier to put flattr buttons in ikiwiki. It supports both t
 
 The dynamic button does not require creation of the page on flattr before being added to a page, the static one does.
 
-I wrote some notes on [jonatan.walck.se](http://jonatan.walck.se/software/ikiwiki/plugins/flattr/) and put the source here: [flattr.pm](http://jonatan.walck.se/software/ikiwiki/flattr.pm)
+I wrote some notes on [jonatan.walck.se](http://jonatan.walck.se/software/ikiwiki/plugin/flattr/) and put the source here: [flattr.pm](http://jonatan.walck.se/software/ikiwiki/flattr.pm)
 
 This plugin is licensed under CC0.
 
-- 
cgit v1.2.3


From 4de7cdf2aaa7f35a33178da23e793e79ff073225 Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@kitenet.net>
Date: Mon, 17 May 2010 13:13:11 -0400
Subject: fix location

---
 doc/plugins/contrib/flattr/jaywalk.mdwn | 5 -----
 doc/users/jaywalk.mdwn                  | 5 +++++
 2 files changed, 5 insertions(+), 5 deletions(-)
 delete mode 100644 doc/plugins/contrib/flattr/jaywalk.mdwn
 create mode 100644 doc/users/jaywalk.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/flattr/jaywalk.mdwn b/doc/plugins/contrib/flattr/jaywalk.mdwn
deleted file mode 100644
index 31b3e0c4d..000000000
--- a/doc/plugins/contrib/flattr/jaywalk.mdwn
+++ /dev/null
@@ -1,5 +0,0 @@
-Jonatan Walck. Home page: [jonatan.walck.se](http://jonatan.walck.se)
-
-## Contact ##
-* jonatan at walck dot se
-* [I2P-Bote key](http://jonatan.walck.i2p/docs/i2p-bote.txt) [what is this?](http://i2pbote.i2p.to/)
diff --git a/doc/users/jaywalk.mdwn b/doc/users/jaywalk.mdwn
new file mode 100644
index 000000000..31b3e0c4d
--- /dev/null
+++ b/doc/users/jaywalk.mdwn
@@ -0,0 +1,5 @@
+Jonatan Walck. Home page: [jonatan.walck.se](http://jonatan.walck.se)
+
+## Contact ##
+* jonatan at walck dot se
+* [I2P-Bote key](http://jonatan.walck.i2p/docs/i2p-bote.txt) [what is this?](http://i2pbote.i2p.to/)
-- 
cgit v1.2.3


From 4518fbe1c101ed3a4a70d6c569ee0b5e0573835e Mon Sep 17 00:00:00 2001
From: "http://jmtd.livejournal.com/" <http://jmtd.livejournal.com/@web>
Date: Mon, 17 May 2010 17:13:17 +0000
Subject: link CC0 (I'd never heard of it)

---
 doc/plugins/contrib/flattr.mdwn | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/flattr.mdwn b/doc/plugins/contrib/flattr.mdwn
index fb532f44c..f8f005c31 100644
--- a/doc/plugins/contrib/flattr.mdwn
+++ b/doc/plugins/contrib/flattr.mdwn
@@ -8,7 +8,7 @@ The dynamic button does not require creation of the page on flattr before being
 
 I wrote some notes on [jonatan.walck.se](http://jonatan.walck.se/software/ikiwiki/plugin/flattr/) and put the source here: [flattr.pm](http://jonatan.walck.se/software/ikiwiki/flattr.pm)
 
-This plugin is licensed under CC0.
+This plugin is licensed under [CC0](http://creativecommons.org/publicdomain/zero/1.0/) (public domain).
 
 # Usage #
 
-- 
cgit v1.2.3


From f463cde12eb814945cdce798dfdf675d4945fb11 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 19 May 2010 11:18:35 +0000
Subject: new version

---
 doc/plugins/contrib/field.mdwn | 127 +++++++++++++++++++++++++++++++++--------
 1 file changed, 104 insertions(+), 23 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field.mdwn b/doc/plugins/contrib/field.mdwn
index 09646d28a..dce2d891c 100644
--- a/doc/plugins/contrib/field.mdwn
+++ b/doc/plugins/contrib/field.mdwn
@@ -13,9 +13,22 @@ IkiWiki::Plugin::field - front-end for per-page record fields.
     # simple registration
     field_register => [qw{meta}],
 
+    # simple registration with priority
+    field_register => {
+	meta => 'last'
+	foo => 'DD'
+    },
+
     # allow the config to be queried as a field
     field_allow_config => 1,
 
+    # flag certain fields as "tags"
+    field_tags => {
+	BookAuthor => '/books/authors',
+	BookGenre => '/books/genres',
+	MovieGenre => '/movies/genres',
+    }
+
 ## DESCRIPTION
 
 This plugin is meant to be used in conjunction with other plugins
@@ -25,13 +38,14 @@ are fields in that record.  This can include the meta-data for that page,
 such as the page title.
 
 Plugins can register a function which will return the value of a "field" for
-a given page.  This can be used in three ways:
+a given page.  This can be used in a few ways:
 
 * In page templates; all registered fields will be passed to the page template in the "pagetemplate" processing.
 * In PageSpecs; the "field" function can be used to match the value of a field in a page.
+* In SortSpecs; the "field" function can be used for sorting pages by the value of a field in a page.
 * By other plugins, using the field_get_value function, to get the value of a field for a page, and do with it what they will.
 
-## OPTIONS
+## CONFIGURATION OPTIONS
 
 The following options can be set in the ikiwiki setup file.
 
@@ -46,28 +60,77 @@ keys of the config hash are the field names.
 
     field_register => [qw{meta}],
 
-A list of plugin-IDs to register.  This assumes that the plugins in
-question store data in the %pagestatus hash using the ID of that plugin,
-and thus the field values are looked for there.
+    field_register => {
+	meta => 'last'
+	foo => 'DD'
+    },
+
+A hash of plugin-IDs to register.  The keys of the hash are the names of the
+plugins, and the values of the hash give the order of lookup of the field
+values.  The order can be 'first', 'last', 'middle', or an explicit order
+sequence between 'AA' and 'ZZ'.  If the simpler type of registration is used,
+then the order will be 'middle'.
+
+This assumes that the plugins in question store data in the %pagestatus hash
+using the ID of that plugin, and thus the field values are looked for there.
 
 This is the simplest form of registration, but the advantage is that it
 doesn't require the plugin to be modified in order for it to be
 registered with the "field" plugin.
 
-## PageSpec
+**field_tags**
+
+    field_tags => {
+	BookAuthor => '/books/authors',
+	BookGenre => '/books/genres',
+	MovieGenre => '/movies/genres',
+    }
 
-The "field" PageSpec function can be used to match the value of a field for a page.
+A hash of fields and their associated pages.  This provides a faceted
+tagging system.
 
-**field(*name* *glob*)**
+The way this works is that a given field-name will be associated with a given
+page, and the values of that field will be linked to sub-pages of that page.
 
 For example:
 
-field(bar Foo*) will match if the "bar" field starts with "Foo".
+	BookGenre: SF
+
+will link to "/books/genres/SF", with a link-type of "bookgenre".
 
-**destfield(*name* *glob*)**
+## PageSpec
+
+The `field` plugin provides a few PageSpec functions to match values
+of fields for pages.
+
+* field
+  * **field(*name* *glob*)**
+  * field(bar Foo\*) will match if the "bar" field starts with "Foo".
+* destfield
+  * **destfield(*name* *glob*)**
+  * as for "field" but matches against the destination page (i.e when the source page is being included in another page).
+* field_item
+  * **field_item(*name* *glob*)**
+  * field_item(bar Foo) will match if one of the values of the "bar" field is "Foo".
+* destfield_item
+  * **destfield_item(*name* *glob*)**
+  * as for "field_item" but matches against the destination page.
+* field_tagged
+  * **field_tagged(*name* *glob*)**
+  * like `tagged`, but this uses the tag-bases and link-types defined in the `field_tags` configuration option.
+* destfield_tagged
+  * **destfield_tagged(*name* *glob*)**
+  * as for "field_tagged" but matches against the destination page.
+
+## SortSpec
+
+The "field" SortSpec function can be used to sort a page depending on the value of a field for that page.  This is used for directives that take sort parameters, such as **inline** or **report**.
+
+field(*name*)
 
-is the same, except that it tests the destination page (that is, in cases
-when the source page is being included in another page).
+For example:
+
+sort="field(bar)" will sort by the value og the "bar" field.
 
 ## FUNCTIONS
 
@@ -75,16 +138,18 @@ when the source page is being included in another page).
 
 field_register(id=>$id);
 
-Register a plugin as having field data.  The above form is the simplest, where the field value
-is looked up in the %pagestatus hash under the plugin-id.
+Register a plugin as having field data.  The above form is the simplest, where
+the field value is looked up in the %pagestatus hash under the plugin-id.
 
 Additional Options:
 
 **call=>&myfunc**
 
-A reference to a function to call rather than just looking up the value in the %pagestatus hash.
-It takes two arguments: the name of the field, and the name of the page.  It is expected to return
-the value of that field, or undef if there is no field by that name.
+A reference to a function to call rather than just looking up the value in the
+%pagestatus hash.  It takes two arguments: the name of the field, and the name
+of the page.  It is expected to return (a) an array of the values of that field
+if "wantarray" is true, or (b) a concatenation of the values of that field
+if "wantarray" is not true, or (c) undef if there is no field by that name.
 
     sub myfunc ($$) {
 	my $field = shift;
@@ -92,22 +157,38 @@ the value of that field, or undef if there is no field by that name.
 
 	...
 
-	return $value;
+	return (wantarray ? @values : $value);
     }
 
 **first=>1**
 
-Set this to be called first in the sequence of calls looking for values.  Since the first found
-value is the one which is returned, ordering is significant.
+Set this to be called first in the sequence of calls looking for values.  Since
+the first found value is the one which is returned, ordering is significant.
+This is equivalent to "order=>'first'".
 
 **last=>1**
 
-Set this to be called last in the sequence of calls looking for values.  Since the first found
-value is the one which is returned, ordering is significant.
+Set this to be called last in the sequence of calls looking for values.  Since
+the first found value is the one which is returned, ordering is significant.
+This is equivalent to "order=>'last'".
+
+**order=>$order**
+
+Set the explicit ordering in the sequence of calls looking for values.  Since
+the first found value is the one which is returned, ordering is significant.
+
+The values allowed for this are "first", "last", "middle", or a two-character
+ordering-sequence between 'AA' and 'ZZ'.
 
 ### field_get_value($field, $page)
 
-Returns the value of the field for that page, or undef if none is found.
+    my @values = field_get_value($field, $page);
+
+    my $value = field_get_value($field, $page);
+
+Returns the values of the field for that page, or undef if none is found.
+Note that it will return an array of values if you ask for an array,
+and a scalar value if you ask for a scalar.
 
 ## DOWNLOAD
 
-- 
cgit v1.2.3


From 9b45264c1c3e83b991d74de6df652a2f2e8749d8 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 19 May 2010 11:20:44 +0000
Subject: new version

---
 doc/plugins/contrib/ftemplate.mdwn | 83 ++++----------------------------------
 1 file changed, 7 insertions(+), 76 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/ftemplate.mdwn b/doc/plugins/contrib/ftemplate.mdwn
index fba51e1c2..d82867f94 100644
--- a/doc/plugins/contrib/ftemplate.mdwn
+++ b/doc/plugins/contrib/ftemplate.mdwn
@@ -1,85 +1,16 @@
 [[!template id=plugin name=ftemplate author="[[rubykat]]"]]
 [[!tag type/meta type/format]]
-[[!toc]]
-## NAME
 
-IkiWiki::Plugin::ftemplate - field-aware structured template plugin
+This plugin provides the [[ikiwiki/directive/ftemplate]] directive.
 
-## SYNOPSIS
+This is like the [[ikiwiki/directive/template]] directive, with the addition
+that one does not have to provide all the values in the call to the template,
+because ftemplate can query structured data ("fields") using the [[field]]
+plugin.
 
-    # activate the plugin
-    add_plugins => [qw{goodstuff ftemplate ....}],
-
-## DESCRIPTION
-
-This plugin provides the **ftemplate** directive.  This is like
-the [[ikiwiki/directive/template]] directive, with the addition that one does not
-have to provide all the values in the call to the template,
-because ftemplate can query structured data ("fields") using
-the [[field]] plugin.
-
-Templates are files that can be filled out and inserted into pages in
-the wiki, by using the ftemplate directive. The directive has an id
-parameter that identifies the template to use.
-
-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 is, as with the
-[[plugins/template]] plugin, 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.
-
-### EXAMPLES
-
-#### Example 1
-
-PageA:
-
-    \[[!meta title="I Am Page A"]]
-    \[[!meta description="A is for Apple."]]
-    \[[!meta author="Fred Nurk"]]
-    \[[!ftemplate id="mytemplate"]]
-
-Template "mytemplate":
+## Activate the plugin
 
-    # <TMPL_VAR NAME="TITLE">
-    by <TMPL_VAR NAME="AUTHOR">
-
-    **Summary:** <TMPL_VAR NAME="DESCRIPTION">
-
-This will give:
-
-    <h1>I Am Page A</h1>
-    <p>by Fred Nurk</p>
-    <p><strong>Summary:</strong> A is for Apple.
-
-#### Example 2: Overriding values
-
-PageB:
-
-    \[[!meta title="I Am Page B"]]
-    \[[!meta description="B is for Banana."]]
-    \[[!meta author="Fred Nurk"]]
-    \[[!ftemplate id="mytemplate" title="Bananananananas"]]
-
-This will give:
-
-    <h1>Bananananananas</h1>
-    <p>by Fred Nurk</p>
-    <p><strong>Summary:</strong> B is for Banana.
-
-### LIMITATIONS
-
-One cannot query the values of fields on pages other than the current
-page.
+    add_plugins => [qw{goodstuff ftemplate ....}],
 
 ## PREREQUISITES
 
-- 
cgit v1.2.3


From cc84a2dacdc85e3ca8e5e652464bfd5ce4f0c725 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 19 May 2010 11:25:43 +0000
Subject: new version; splitting docs between plugin and directive pages

---
 doc/plugins/contrib/report.mdwn | 154 ++--------------------------------------
 1 file changed, 7 insertions(+), 147 deletions(-)

(limited to 'doc/plugins/contrib')

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
 
-- 
cgit v1.2.3


From 2f7a909bbc0b58714bd2effd03f15d41ded77fcf Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 19 May 2010 11:29:45 +0000
Subject: new version to go with new version of field

---
 doc/plugins/contrib/ymlfront.mdwn | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/ymlfront.mdwn b/doc/plugins/contrib/ymlfront.mdwn
index f4438f23c..6dd8ed532 100644
--- a/doc/plugins/contrib/ymlfront.mdwn
+++ b/doc/plugins/contrib/ymlfront.mdwn
@@ -42,7 +42,7 @@ That will be htmlized using the page-type of the page-file.
 
 ### Accessing the Data
 
-There are three ways to access the data given in the YAML section.
+There are a few ways to access the data given in the YAML section.
 
 * [[getfield]] plugin
 
@@ -83,6 +83,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.
 
+* [[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.
-- 
cgit v1.2.3


From c1f68a8cff3217fb81052043d897b25aae677513 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Wed, 19 May 2010 11:30:35 +0000
Subject: reply

---
 doc/plugins/contrib/ymlfront/discussion.mdwn | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/ymlfront/discussion.mdwn b/doc/plugins/contrib/ymlfront/discussion.mdwn
index 3ad02af29..b5c08fedd 100644
--- a/doc/plugins/contrib/ymlfront/discussion.mdwn
+++ b/doc/plugins/contrib/ymlfront/discussion.mdwn
@@ -9,3 +9,5 @@ Joey's code in IkiWiki::Setup::Yaml. Please consider merging :-) --[[smcv]]
 >> 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]]
-- 
cgit v1.2.3


From 3fbcd2c8d270b1282e3c457cd2eb7720f43726af Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@kitenet.net>
Date: Wed, 9 Jun 2010 14:58:39 -0400
Subject: move contrib plugin directives out of ikiwiki/directive

Problem is that ikiwiki/directive is turned into an underlay and added to
all wikis. And the test suite checks it for broken links and turns some up.
So it's not appropriate for contrib plugin's directives to be documented
in there.
---
 doc/ikiwiki/directive/ftemplate.mdwn               | 106 ---------------
 doc/ikiwiki/directive/report.mdwn                  | 149 ---------------------
 .../ftemplate/ikiwiki/directive/ftemplate.mdwn     | 106 +++++++++++++++
 .../contrib/report/ikiwiki/directive/report.mdwn   | 149 +++++++++++++++++++++
 4 files changed, 255 insertions(+), 255 deletions(-)
 delete mode 100644 doc/ikiwiki/directive/ftemplate.mdwn
 delete mode 100644 doc/ikiwiki/directive/report.mdwn
 create mode 100644 doc/plugins/contrib/ftemplate/ikiwiki/directive/ftemplate.mdwn
 create mode 100644 doc/plugins/contrib/report/ikiwiki/directive/report.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/doc/ikiwiki/directive/ftemplate.mdwn b/doc/ikiwiki/directive/ftemplate.mdwn
deleted file mode 100644
index 3009fc830..000000000
--- a/doc/ikiwiki/directive/ftemplate.mdwn
+++ /dev/null
@@ -1,106 +0,0 @@
-The `ftemplate` directive is supplied by the [[!iki plugins/contrib/ftemplate desc=ftemplate]] plugin.
-
-This is like the [[ikiwiki/directive/template]] directive, with the addition
-that one does not have to provide all the values in the call to the template,
-because ftemplate can query structured data ("fields") using the
-[[plugins/contrib/field]] plugin.
-
-Templates are files that can be filled out and inserted into pages in
-the wiki, by using the ftemplate directive. The directive has an id
-parameter that identifies the template to use.
-
-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 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.
-
-### EXAMPLES
-
-#### Example 1
-
-PageA:
-
-    \[[!meta title="I Am Page A"]]
-    \[[!meta description="A is for Apple."]]
-    \[[!meta author="Fred Nurk"]]
-    \[[!ftemplate id="mytemplate"]]
-
-Template "mytemplate":
-
-    # <TMPL_VAR NAME="TITLE">
-    by <TMPL_VAR NAME="AUTHOR">
-
-    **Summary:** <TMPL_VAR NAME="DESCRIPTION">
-
-This will give:
-
-    <h1>I Am Page A</h1>
-    <p>by Fred Nurk</p>
-    <p><strong>Summary:</strong> A is for Apple.
-
-#### Example 2: Overriding values
-
-PageB:
-
-    \[[!meta title="I Am Page B"]]
-    \[[!meta description="B is for Banana."]]
-    \[[!meta author="Fred Nurk"]]
-    \[[!ftemplate id="mytemplate" title="Bananananananas"]]
-
-This will give:
-
-    <h1>Bananananananas</h1>
-    <p>by Fred Nurk</p>
-    <p><strong>Summary:</strong> B is for Banana.
-
-#### Example 3: Loops
-
-(this example uses the [[plugins/contrib/ymlfront]] plugin)
-
-Page C:
-
-    ---
-    BookAuthor: Georgette Heyer
-    BookTitle: Black Sheep
-    BookGenre:
-      - Historical
-      - Romance
-    ---
-    \[[ftemplate id="footemplate"]]
-
-    I like this book.
-
-Template "footemplate":
-
-    # <TMPL_VAR BOOKTITLE>
-    by <TMPL_VAR BOOKAUTHOR>
-
-    <TMPL_IF BOOKGENRE>(
-    <TMPL_LOOP GENRE_LOOP><TMPL_VAR BOOKGENRE>
-    <TMPL_UNLESS __last__>, </TMPL_UNLESS>
-    </TMPL_LOOP>
-    )</TMPL_IF>
-
-This will give:
-
-    <h1>Black Sheep</h1>
-    <p>by Georgette Heyer</p>
-
-    <p>(Historical, Romance)</p>
-
-    <p>I like this book.</p>
-
-### LIMITATIONS
-
-One cannot query the values of fields on pages other than the current
-page.  If you want to do that, check out the [[plugins/contrib/report]]
-plugin.
diff --git a/doc/ikiwiki/directive/report.mdwn b/doc/ikiwiki/directive/report.mdwn
deleted file mode 100644
index 8f8e6b4e8..000000000
--- a/doc/ikiwiki/directive/report.mdwn
+++ /dev/null
@@ -1,149 +0,0 @@
-[[!toc]]
-The `report` directive is supplied by the [[!iki plugins/contrib/report desc=report]] plugin.
-
-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 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.
-
-**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.
-
-Additional space-separated trail pages can be given in this option.
-For example:
-
-    trail="animals/cats animals/dogs"
-
-This will take the links from both the "animals/cats" page and the
-"animals/dogs" page as the set of pages to apply the PageSpec to.
-
-**sort**: A SortSpec to determine how the matching pages should be sorted.
-
-**here_only**: Report on the current page only.
-
-This is useful in combination with "prev_" and "next_" variables to
-make a navigation trail.
-If the current page doesn't match the pagespec, then no pages will
-be reported on.
-
-### 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
-
-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"]]
-
-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.
-
-**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.
-
-### Prev_ And Next_ Items
-
-Any of the above variables can be prefixed with "prev_" or "next_"
-and that will give the previous or next value of that variable; that is,
-the value from the previous or next page that this report is reporting on.
-This is mainly useful for a "here_only" report.
-
-### 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.
diff --git a/doc/plugins/contrib/ftemplate/ikiwiki/directive/ftemplate.mdwn b/doc/plugins/contrib/ftemplate/ikiwiki/directive/ftemplate.mdwn
new file mode 100644
index 000000000..3009fc830
--- /dev/null
+++ b/doc/plugins/contrib/ftemplate/ikiwiki/directive/ftemplate.mdwn
@@ -0,0 +1,106 @@
+The `ftemplate` directive is supplied by the [[!iki plugins/contrib/ftemplate desc=ftemplate]] plugin.
+
+This is like the [[ikiwiki/directive/template]] directive, with the addition
+that one does not have to provide all the values in the call to the template,
+because ftemplate can query structured data ("fields") using the
+[[plugins/contrib/field]] plugin.
+
+Templates are files that can be filled out and inserted into pages in
+the wiki, by using the ftemplate directive. The directive has an id
+parameter that identifies the template to use.
+
+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 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.
+
+### EXAMPLES
+
+#### Example 1
+
+PageA:
+
+    \[[!meta title="I Am Page A"]]
+    \[[!meta description="A is for Apple."]]
+    \[[!meta author="Fred Nurk"]]
+    \[[!ftemplate id="mytemplate"]]
+
+Template "mytemplate":
+
+    # <TMPL_VAR NAME="TITLE">
+    by <TMPL_VAR NAME="AUTHOR">
+
+    **Summary:** <TMPL_VAR NAME="DESCRIPTION">
+
+This will give:
+
+    <h1>I Am Page A</h1>
+    <p>by Fred Nurk</p>
+    <p><strong>Summary:</strong> A is for Apple.
+
+#### Example 2: Overriding values
+
+PageB:
+
+    \[[!meta title="I Am Page B"]]
+    \[[!meta description="B is for Banana."]]
+    \[[!meta author="Fred Nurk"]]
+    \[[!ftemplate id="mytemplate" title="Bananananananas"]]
+
+This will give:
+
+    <h1>Bananananananas</h1>
+    <p>by Fred Nurk</p>
+    <p><strong>Summary:</strong> B is for Banana.
+
+#### Example 3: Loops
+
+(this example uses the [[plugins/contrib/ymlfront]] plugin)
+
+Page C:
+
+    ---
+    BookAuthor: Georgette Heyer
+    BookTitle: Black Sheep
+    BookGenre:
+      - Historical
+      - Romance
+    ---
+    \[[ftemplate id="footemplate"]]
+
+    I like this book.
+
+Template "footemplate":
+
+    # <TMPL_VAR BOOKTITLE>
+    by <TMPL_VAR BOOKAUTHOR>
+
+    <TMPL_IF BOOKGENRE>(
+    <TMPL_LOOP GENRE_LOOP><TMPL_VAR BOOKGENRE>
+    <TMPL_UNLESS __last__>, </TMPL_UNLESS>
+    </TMPL_LOOP>
+    )</TMPL_IF>
+
+This will give:
+
+    <h1>Black Sheep</h1>
+    <p>by Georgette Heyer</p>
+
+    <p>(Historical, Romance)</p>
+
+    <p>I like this book.</p>
+
+### LIMITATIONS
+
+One cannot query the values of fields on pages other than the current
+page.  If you want to do that, check out the [[plugins/contrib/report]]
+plugin.
diff --git a/doc/plugins/contrib/report/ikiwiki/directive/report.mdwn b/doc/plugins/contrib/report/ikiwiki/directive/report.mdwn
new file mode 100644
index 000000000..8f8e6b4e8
--- /dev/null
+++ b/doc/plugins/contrib/report/ikiwiki/directive/report.mdwn
@@ -0,0 +1,149 @@
+[[!toc]]
+The `report` directive is supplied by the [[!iki plugins/contrib/report desc=report]] plugin.
+
+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 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.
+
+**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.
+
+Additional space-separated trail pages can be given in this option.
+For example:
+
+    trail="animals/cats animals/dogs"
+
+This will take the links from both the "animals/cats" page and the
+"animals/dogs" page as the set of pages to apply the PageSpec to.
+
+**sort**: A SortSpec to determine how the matching pages should be sorted.
+
+**here_only**: Report on the current page only.
+
+This is useful in combination with "prev_" and "next_" variables to
+make a navigation trail.
+If the current page doesn't match the pagespec, then no pages will
+be reported on.
+
+### 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
+
+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"]]
+
+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.
+
+**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.
+
+### Prev_ And Next_ Items
+
+Any of the above variables can be prefixed with "prev_" or "next_"
+and that will give the previous or next value of that variable; that is,
+the value from the previous or next page that this report is reporting on.
+This is mainly useful for a "here_only" report.
+
+### 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.
-- 
cgit v1.2.3


From a39c6b6eac7059e4ed13dbf8a3750a79a5c9a5c8 Mon Sep 17 00:00:00 2001
From: 
 "https://www.google.com/accounts/o8/id?id=AItOawnbe6oB_ecFtNYII1JN3zSggwUPUdOb8jI"
 <William@web>
Date: Sat, 26 Jun 2010 22:12:24 +0000
Subject: Add Microdata suggestion

---
 doc/plugins/contrib/field/discussion.mdwn | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn
index 103e061e5..5f4c9b942 100644
--- a/doc/plugins/contrib/field/discussion.mdwn
+++ b/doc/plugins/contrib/field/discussion.mdwn
@@ -324,3 +324,5 @@ smcv's discuission of field author vs meta author above. --[[Joey]]
 >>> the side-effects, but use `field` as an interface to get the values of those special fields.
 
 >>> --[[KathrynAndersen]]
+
+I was just looking at HTML5 and wondered if the field plugin should generate the new Microdata tags (as well as the internal structures)? <http://slides.html5rocks.com/#slide19> -- [[Will]]
-- 
cgit v1.2.3


From 91fde37f13a89b4593e128852c2f8927b478d881 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Thu, 1 Jul 2010 00:30:58 +0000
Subject: response to Microdata question

---
 doc/plugins/contrib/field/discussion.mdwn | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn
index 5f4c9b942..191f8b27d 100644
--- a/doc/plugins/contrib/field/discussion.mdwn
+++ b/doc/plugins/contrib/field/discussion.mdwn
@@ -325,4 +325,8 @@ smcv's discuission of field author vs meta author above. --[[Joey]]
 
 >>> --[[KathrynAndersen]]
 
+-----
+
 I was just looking at HTML5 and wondered if the field plugin should generate the new Microdata tags (as well as the internal structures)? <http://slides.html5rocks.com/#slide19> -- [[Will]]
+
+> This could just as easily be done as a separate plugin.  Feel free to do so. --[[KathrynAndersen]]
-- 
cgit v1.2.3


From 5bbbdbecbbe1e68b65baf35c3d8b8a371c9341b2 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Fri, 6 Aug 2010 08:12:11 +0000
Subject: update docs for new version

---
 doc/plugins/contrib/ymlfront.mdwn | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

(limited to 'doc/plugins/contrib')

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
 
-- 
cgit v1.2.3


From f78357348a028fe97037429f4712d511d2921b14 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Fri, 6 Aug 2010 08:13:48 +0000
Subject: ymlfront now provides a ymlfront directive

---
 doc/plugins/contrib/ikiwiki/directive/ymlfront.mdwn | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)
 create mode 100644 doc/plugins/contrib/ikiwiki/directive/ymlfront.mdwn

(limited to 'doc/plugins/contrib')

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.
-- 
cgit v1.2.3


From 0497b6379285df3c505c701ddfc9886922e85054 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Fri, 6 Aug 2010 08:19:06 +0000
Subject: Should I remove the old ymlfront format now that it recognises
 directives?

---
 doc/plugins/contrib/ymlfront/discussion.mdwn | 16 ++++------------
 1 file changed, 4 insertions(+), 12 deletions(-)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/ymlfront/discussion.mdwn b/doc/plugins/contrib/ymlfront/discussion.mdwn
index b5c08fedd..3f7f0a337 100644
--- a/doc/plugins/contrib/ymlfront/discussion.mdwn
+++ b/doc/plugins/contrib/ymlfront/discussion.mdwn
@@ -1,13 +1,5 @@
-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
+* it is fragile (easily breakable)
+* it is non-standard
 
-> 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]]
-
->> 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?
-- 
cgit v1.2.3


From d2b50c37b44972e60d08854e9e780a09481872d5 Mon Sep 17 00:00:00 2001
From: "http://kerravonsen.dreamwidth.org/"
 <http://kerravonsen.dreamwidth.org/@web>
Date: Fri, 6 Aug 2010 08:19:39 +0000
Subject: formatting

---
 doc/plugins/contrib/ymlfront/discussion.mdwn | 1 +
 1 file changed, 1 insertion(+)

(limited to 'doc/plugins/contrib')

diff --git a/doc/plugins/contrib/ymlfront/discussion.mdwn b/doc/plugins/contrib/ymlfront/discussion.mdwn
index 3f7f0a337..b1fd65fff 100644
--- a/doc/plugins/contrib/ymlfront/discussion.mdwn
+++ b/doc/plugins/contrib/ymlfront/discussion.mdwn
@@ -1,4 +1,5 @@
 Now that I have implemented a \[[!ymlfront ...]] directive, I would like to remove support for the old "---" delimited format, because
+
 * it is fragile (easily breakable)
 * it is non-standard
 
-- 
cgit v1.2.3


From 80102c042d0f2fd194222cd233a7bfd0e8bd467f Mon Sep 17 00:00:00 2001
From: Joey Hess <joey@kitenet.net>
Date: Thu, 12 Aug 2010 16:53:52 -0400
Subject: flattr: New plugin.

Thanks to jaywalk for the initial implementation at a flattr plugin!

This one is less configurable, but simpler.
---
 IkiWiki/Plugin/flattr.pm          | 97 +++++++++++++++++++++++++++++++++++++++
 debian/changelog                  |  2 +
 doc/ikiwiki/directive/flattr.mdwn | 45 ++++++++++++++++++
 doc/plugins/contrib/flattr.mdwn   |  3 ++
 doc/plugins/flattr.mdwn           |  9 ++++
 doc/style.css                     |  4 ++
 6 files changed, 160 insertions(+)
 create mode 100644 IkiWiki/Plugin/flattr.pm
 create mode 100644 doc/ikiwiki/directive/flattr.mdwn
 create mode 100644 doc/plugins/flattr.mdwn

(limited to 'doc/plugins/contrib')

diff --git a/IkiWiki/Plugin/flattr.pm b/IkiWiki/Plugin/flattr.pm
new file mode 100644
index 000000000..3aee1eb93
--- /dev/null
+++ b/IkiWiki/Plugin/flattr.pm
@@ -0,0 +1,97 @@
+#!/usr/bin/perl
+package IkiWiki::Plugin::flattr;
+
+use warnings;
+use strict;
+use IkiWiki 3.00;
+
+sub import {
+	hook(type => "getsetup", id => "flattr", call => \&getsetup);
+	hook(type => "preprocess", id => "flattr", call => \&preprocess);
+	hook(type => "format", id => "flattr", call => \&format);
+}
+
+sub getsetup () {
+	return
+		plugin => {
+			safe => 1,
+			rebuild => undef,
+		},
+		flattr_userid => {
+			type => "string",
+			example => 'joeyh',
+			description => "userid or user name to use by default for Flattr buttons",
+			advanced => 0,
+			safe => 1,
+			rebuild => undef,
+		},
+}
+
+my %flattr_pages;
+
+sub preprocess (@) {
+	my %params=@_;
+
+	$flattr_pages{$params{destpage}}=1;
+
+	my $url=$params{url};
+	if (! defined $url) {
+		$url=urlto($params{page}, "", 1);
+	}
+
+	my @fields;
+	foreach my $field (qw{language uid button hidden category tags}) {
+		if (exists $params{$field}) {
+			push @fields, "$field:$params{$field}";
+		}
+	}
+	
+	return '<a class="FlattrButton" href="'.$url.'"'.
+       		(exists $params{title} ? ' title="'.$params{title}.'"' : '').
+		' rev="flattr;'.join(';', @fields).';"'.
+		'>'.
+		(exists $params{description} ? $params{description} : '').
+		'</a>';
+}
+
+sub format (@) {
+	my %params=@_;
+
+	# Add flattr's javascript to pages with flattr buttons.
+	if ($flattr_pages{$params{page}}) {
+		if (! ($params{content}=~s!^(<body[^>]*>)!$1.flattrjs()!em)) {
+			# no <body> tag, probably in preview mode
+			$params{content}=flattrjs().$params{content};
+		}
+	}
+	return $params{content};
+}
+
+my $js_cached;
+sub flattrjs {
+	return $js_cached if defined $js_cached;
+
+	my $js_url='https://api.flattr.com/js/0.5.0/load.js?mode=auto';
+	if (defined $config{flattr_userid}) {
+		my $userid=$config{flattr_userid};
+		$userid=~s/[^-A-Za-z0-9_]//g; # sanitize for inclusion in javascript
+		$js_url.="&uid=$userid";
+	}
+
+	# This is Flattr's standard javascript snippet to include their
+	# external javascript file, asynchronously.
+	return $js_cached=<<"EOF";
+<script type="text/javascript">
+<!--//--><![CDATA[//><!--
+(function() {
+	var s = document.createElement('script'), t = document.getElementsByTagName('script')[0];
+	s.type = 'text/javascript';
+	s.async = true;
+	s.src = '$js_url';
+	t.parentNode.insertBefore(s, t);
+})();//--><!]]>
+</script>
+EOF
+}
+
+1
diff --git a/debian/changelog b/debian/changelog
index 440bee34f..f90fd8855 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -2,6 +2,8 @@ ikiwiki (3.20100805) UNRELEASED; urgency=low
 
   * filecheck: Fall back to using the file command if the freedesktop
     magic file cannot identify a file.
+  * flattr: New plugin. (Thanks to jaywalk for the initial implementation
+    at a flattr plugin! This one is less configurable, but simpler.)
 
  -- Joey Hess <joeyh@debian.org>  Mon, 09 Aug 2010 13:18:28 -0400
 
diff --git a/doc/ikiwiki/directive/flattr.mdwn b/doc/ikiwiki/directive/flattr.mdwn
new file mode 100644
index 000000000..5083005ce
--- /dev/null
+++ b/doc/ikiwiki/directive/flattr.mdwn
@@ -0,0 +1,45 @@
+The `flattr` directive is supplied by the [[!iki plugins/flattr desc=flattr]] plugin.
+
+This directive allows easily inserting Flattr buttons onto wiki pages.
+
+Flattr supports both static buttons and javascript buttons. This directive
+only creates dynamic javascript buttons. If you want to insert a static
+Flattr button, you can simply copy the html code for it from Flattr, instead.
+Note that this directive inserts javascript code into the page, that
+loads more javascript code from Flattr.com. So only use it if you feel
+comfortable with that.
+
+The directive can be used to display a button for a thing you have already
+manually submitted to Flattr. In this mode, the only parameter you need to
+include is the exact url to the thing that was submitted to Flattr.
+(If the button is for the current page, you can leave that out.) For
+example, this is the Flattr button for ikiwiki. Feel free to add it to all
+your pages. ;)
+
+	\[[!flattr url="http://ikiwiki.info/" button=compact]]
+
+The directive can also be used to create a button that automatically
+submits a page to Flattr when a user clicks on it. In this mode you
+need to include parameters to specify your uid, and a title, category, tags,
+and description for the page. For example, this is a Flattr button for
+a blog post:
+	
+	\[[!flattr uid=25634 title="my new blog post" category=text
+	tags="blog,example" description="This is a post on my blog."]]
+
+Here are all possible parameters you can pass to the Flattr directive.
+
+* `button` - Set to "compact" for a small button.
+* `url` - The url to the thing to be Flattr'd. If omitted, defaults
+  to the url of the current page.
+* `uid` - Your numeric Flattr userid. Not needed if the flattr plugin
+  has been configured with a global `flattr_userid`.
+* `title` - A short title for the thing, to show on its Flattr page.
+* `description` - A description of the thing, to show on its Flattr
+  page.
+* `category` - One of: text, images, video, audio, software, rest.
+* `tags` - A list of tags separated by a comma.
+* `language` - A language code.
+* `hidden` - Set to 1 to hide the button from listings on Flattr.com.
+
+[[!meta robots="noindex, follow"]]
diff --git a/doc/plugins/contrib/flattr.mdwn b/doc/plugins/contrib/flattr.mdwn
index f8f005c31..e9b4bf857 100644
--- a/doc/plugins/contrib/flattr.mdwn
+++ b/doc/plugins/contrib/flattr.mdwn
@@ -10,6 +10,9 @@ I wrote some notes on [jonatan.walck.se](http://jonatan.walck.se/software/ikiwik
 
 This plugin is licensed under [CC0](http://creativecommons.org/publicdomain/zero/1.0/) (public domain).
 
+Note that there is now a [[plugins/flattr]] plugin bundled with ikiwiki. It
+is less configurable, not supporting static buttons, but simpler to use.
+
 # Usage #
 
     # [[!flattr args]] where args are in the form of arg=value.
diff --git a/doc/plugins/flattr.mdwn b/doc/plugins/flattr.mdwn
new file mode 100644
index 000000000..5da279518
--- /dev/null
+++ b/doc/plugins/flattr.mdwn
@@ -0,0 +1,9 @@
+[[!template id=plugin name=flattr author="[[Joey]]"]]
+[[!tag type/web]]
+
+[Flattr](http://flattr.com/) is a social micropayment platform.
+This plugin allows easily adding Flattr buttons to pages,
+using the [[ikiwiki/directive/flattr]] directive.
+
+This plugin has a configuration setting. `flattr_userid` can be set
+to either your numeric flatter userid, or your flattr username.
diff --git a/doc/style.css b/doc/style.css
index 8dd3b1c15..66d962bd6 100644
--- a/doc/style.css
+++ b/doc/style.css
@@ -449,6 +449,10 @@ li.L8 { list-style: upper-alpha; }
 	background: #ff9900;
 }
 
+.FlattrButton {
+	display: none;
+}
+
 /* openid selector */
 #openid_choice {
 	display: none;
-- 
cgit v1.2.3