Merge remote branch 'upstream/master' into prv/po

Conflicts:
	IkiWiki/Plugin/po.pm

16 files changed, 177 insertions, 24 deletions

diff --git a/doc/ikiwiki/directive/calendar.mdwn b/doc/ikiwiki/directive/calendar.mdwn
index b2ac75b11..e9216e11f 100644
--- a/doc/ikiwiki/directive/calendar.mdwn
+++ b/doc/ikiwiki/directive/calendar.mdwn
@@ -40,18 +40,21 @@ An example crontab:
   "month" or "year". The default is a month view calendar.
 * `pages` - Specifies the [[ikiwiki/PageSpec]] of pages to link to from the
   month calendar. Defaults to "*".
-* `archivebase` - Configures the base of the archives hierarchy. The
-  default is "archives". Note that this default can also be overridden
+* `archivebase` - Configures the base of the archives hierarchy. 
+  The default is "archives". Note that this default can also be overridden
   for the whole wiki by setting `archivebase` in ikiwiki's setup file.
+  Calendars link to pages under here, with names like "2010/04" and
+  "2010". These pages can be automatically created using the
+  `ikiwiki-calendar` program. 
 * `year` - The year for which the calendar is requested. Defaults to the
-  current year.
+  current year. Can also use -1 to refer to last year, and so on.
 * `month` - The numeric month for which the calendar is requested, in the
   range 1..12. Used only for the month view calendar, and defaults to the
-  current month.
+  current month. Can also use -1 to refer to last month, and so on.
 * `week_start_day` - A number, in the range 0..6, which represents the day
   of the week that the month calendar starts with. 0 is Sunday, 1 is Monday,
   and so on. Defaults to 0, which is Sunday.
-* `months_per_row` - In the annual calendar, number of months to place in
+* `months_per_row` - In the year calendar, number of months to place in
   each row. Defaults to 3.
 
 [[!meta robots="noindex, follow"]]
diff --git a/doc/ikiwiki/directive/comment.mdwn b/doc/ikiwiki/directive/comment.mdwn
index 693a92770..398130e2e 100644
--- a/doc/ikiwiki/directive/comment.mdwn
+++ b/doc/ikiwiki/directive/comment.mdwn
@@ -29,6 +29,8 @@ metadata of the comment.
   nearly any format, since it's parsed by [[!cpan TimeDate]]
 * `username` - Used to record the username (or OpenID)
   of a logged in commenter.
+* `nickname` - Name to display for a logged in commenter.
+  (Optional; used for OpenIDs.)
 * `ip` - Can be used to record the IP address of a commenter,
   if they posted anonymously.
 * `claimedauthor` - Records the name that the user entered,
diff --git a/doc/ikiwiki/directive/date.mdwn b/doc/ikiwiki/directive/date.mdwn
index df45fa840..b89241e4c 100644
--- a/doc/ikiwiki/directive/date.mdwn
+++ b/doc/ikiwiki/directive/date.mdwn
@@ -12,3 +12,5 @@ For example, an update to a page with an embedded date stamp could look
 like:
 
 	Updated \[[!date "Wed, 25 Nov 2009 01:11:55 -0500"]]: mumble mumble
+
+[[!meta robots="noindex, follow"]]
diff --git a/doc/ikiwiki/directive/edittemplate.mdwn b/doc/ikiwiki/directive/edittemplate.mdwn
index d731bdb47..c486e821b 100644
--- a/doc/ikiwiki/directive/edittemplate.mdwn
+++ b/doc/ikiwiki/directive/edittemplate.mdwn
@@ -21,7 +21,7 @@ something like:
 	Details:
 
 The template page can also contain [[!cpan HTML::Template]] directives,
-similar to other ikiwiki [[templates]]. Currently only one variable is
+like other ikiwiki [[templates]]. Currently only one variable is
 set: `<TMPL_VAR name>` is replaced with the name of the page being
 created.
 
diff --git a/doc/ikiwiki/directive/format.mdwn b/doc/ikiwiki/directive/format.mdwn
index 23830e9cd..7d11d225f 100644
--- a/doc/ikiwiki/directive/format.mdwn
+++ b/doc/ikiwiki/directive/format.mdwn
@@ -22,7 +22,7 @@ Note that if the highlight plugin is enabled, this directive can also be
 used to display syntax highlighted code. Many languages and formats are
 supported. For example:
 
-	\[[format perl """
+	\[[!format perl """
 	print "hello, world\n";
 	"""]]
 
diff --git a/doc/ikiwiki/directive/img.mdwn b/doc/ikiwiki/directive/img.mdwn
index 94cc754bd..cda62b58f 100644
--- a/doc/ikiwiki/directive/img.mdwn
+++ b/doc/ikiwiki/directive/img.mdwn
@@ -18,7 +18,8 @@ making the image smaller than the specified size. You can also specify only
 the width or the height, and the other value will be calculated based on
 it: "200x", "x200"
 
-You can also pass `alt`, `title`, `class`, `align` and `id` parameters.
+You can also pass `alt`, `title`, `class`, `align`, `id`, `hspace`, and
+`vspace` parameters.
 These are passed through unchanged to the html img tag. If you include a
 `caption` parameter, the caption will be displayed centered beneath the image.
 
diff --git a/doc/ikiwiki/directive/inline/discussion.mdwn b/doc/ikiwiki/directive/inline/discussion.mdwn
index 998ba642b..6a186cd93 100644
--- a/doc/ikiwiki/directive/inline/discussion.mdwn
+++ b/doc/ikiwiki/directive/inline/discussion.mdwn
@@ -1,3 +1,10 @@
+## Combine inline and toggle
+
+Is it possible to combine the behaviour of toggle and inline? ie, have it present of list of 'headlines' which are created from seperate subpages which can be clicked to expand to the body of the inlined page. Thanks.
+
+-- Thiana
+
+---
 ## How do you provide the per post discussion links in your own blog?
 
 > That's configured by the "actions" parameter to the inline directive. See
diff --git a/doc/ikiwiki/directive/map/discussion.mdwn b/doc/ikiwiki/directive/map/discussion.mdwn
index 062b4267a..b7ac17b1a 100644
--- a/doc/ikiwiki/directive/map/discussion.mdwn
+++ b/doc/ikiwiki/directive/map/discussion.mdwn
@@ -1,3 +1,14 @@
+### Sorting
+
+Is there a way to have the generated maps sorted by *title* instead of *filename* when show=title is used?
+Thanks 
+
+-- Thiana
+
+> [[bugs/map_sorts_by_pagename_and_not_title_when_show__61__title_is_used]] --[[Joey]] 
+
+----
+
 Question: Is there a way to generate a listing that shows *both* title and description meta information? Currently, a \[\[!map ...]] shows only one of the two, but I'd like to generate a navigation that looks like a description list. For example:
 
  * This is the title meta information.
@@ -72,3 +83,15 @@ Is there any way to do that?  I don't mind mucking around with `\[[!meta]]` on e
 >>> I think that the ideas and code in
 >>> [[todo/tracking_bugs_with_dependencies]] might also handle this case.
 >>> --[[Joey]]
+
+----
+
+I feel like this should be obvious, but I can't figure out how to sort numerically. 
+
+I have `map pages="./* and !*/Discussion and !*/sidebar"`  and a bunch of pages with names like 1, 2, 3, 11, 12, 1/1.1, 12/12.3 etc. I want to sort them numerically. I see lots of conversation implying there's a simple way to do it, but not how.
+
+> No, you can't: map can't currently use a non-default sort order. If it
+> could, then you could use [[plugins/sortnaturally]]. There's a
+> [[feature_request|todo/sort_parameter_for_map_plugin_and_directive]];
+> [[a_bug_references_it|bugs/map_sorts_by_pagename_and_not_title_when_show=title_is_used]].
+> --[[smcv]]
diff --git a/doc/ikiwiki/directive/meta.mdwn b/doc/ikiwiki/directive/meta.mdwn
index 557441c0b..5a3919dea 100644
--- a/doc/ikiwiki/directive/meta.mdwn
+++ b/doc/ikiwiki/directive/meta.mdwn
@@ -23,6 +23,13 @@ Supported fields:
   be set to a true value in the template; this can be used to format things
   differently in this case.
 
+  An optional `sortas` parameter will be used preferentially when
+  [[ikiwiki/pagespec/sorting]] by `meta(title)`:
+
+	\[[!meta title="The Beatles" sortas="Beatles, The"]]
+
+	\[[!meta title="David Bowie" sortas="Bowie, David"]]
+
 * license
 
   Specifies a license for the page, for example, "GPL". Can contain
@@ -37,6 +44,11 @@ Supported fields:
 
   Specifies the author of a page.
 
+  An optional `sortas` parameter will be used preferentially when
+  [[ikiwiki/pagespec/sorting]] by `meta(author)`:
+
+	\[[!meta author="Joey Hess" sortas="Hess, Joey"]]
+
 * authorurl
 
   Specifies an url for the author of a page.
diff --git a/doc/ikiwiki/directive/pagestats.mdwn b/doc/ikiwiki/directive/pagestats.mdwn
index 68f4d2734..d0e0e7be7 100644
--- a/doc/ikiwiki/directive/pagestats.mdwn
+++ b/doc/ikiwiki/directive/pagestats.mdwn
@@ -4,10 +4,16 @@ This directive can generate stats about how pages link to each other. It can
 produce either a tag cloud, or a table counting the number of links to each
 page.
 
-Here's how to use it to create a [[tag]] cloud:
+Here's how to use it to create a [[tag]] cloud, with tags sized based
+on frequency of use:
 
 	\[[!pagestats pages="tags/*"]]
 
+Here's how to create a list of tags, sized by use as they would be in a
+cloud.
+	
+	\[[!pagestats style="list" pages="tags/*"]]
+
 And here's how to create a table of all the pages on the wiki:
 
 	\[[!pagestats style="table"]]
@@ -28,4 +34,7 @@ links:
 
 	\[[!pagestats style="table" show="10"]]
 
+The optional `class` parameter can be used to control the class
+of the generated tag cloud `div` or page stats `table`.
+
 [[!meta robots="noindex, follow"]]
diff --git a/doc/ikiwiki/directive/pagestats/discussion.mdwn b/doc/ikiwiki/directive/pagestats/discussion.mdwn
index d72b4058d..99029e88e 100644
--- a/doc/ikiwiki/directive/pagestats/discussion.mdwn
+++ b/doc/ikiwiki/directive/pagestats/discussion.mdwn
@@ -13,3 +13,6 @@ Thanks
 
 > The approach that [PmWiki](http://www.pmwiki.org) takes is that it enables the optional auto-creation of (empty) pages which match a particular "group" (set of sub-pages); thus one could set all the "tags/*" pages to be auto-created, creating a new tags/foo page the first time the \[[!tag foo]] directive is used. See [[todo/auto-create_tag_pages_according_to_a_template]] for more discussion on this idea.
 > -- [[KathrynAndersen]]
+
+> Update: Ikiwiki can auto-create tags now, though it only defaults to
+> doing so when tagbase is set. --[[Joey]] 
diff --git a/doc/ikiwiki/directive/pagetemplate.mdwn b/doc/ikiwiki/directive/pagetemplate.mdwn
index 8ad901c1a..401b38099 100644
--- a/doc/ikiwiki/directive/pagetemplate.mdwn
+++ b/doc/ikiwiki/directive/pagetemplate.mdwn
@@ -1,17 +1,13 @@
 The `pagetemplate` directive is supplied by the [[!iki plugins/pagetemplate desc=pagetemplate]] plugin.
 
-This directive allows a page to be displayed using a different template than
-the default `page.tmpl` template.
+This directive allows a page to be displayed using a different
+[[template|templates]] than the default `page.tmpl` template.
 
 The page text is inserted into the template, so the template controls the
 overall look and feel of the wiki page. This is in contrast to the
 [[ikiwiki/directive/template]] directive, which allows inserting templates
 _into_ the body of a page.
 
-This directive can only reference templates that are already installed
-by the system administrator, typically into the
-`/usr/share/ikiwiki/templates` directory. Example:
-
 	\[[!pagetemplate template="my_fancy.tmpl"]]
 
 [[!meta robots="noindex, follow"]]
diff --git a/doc/ikiwiki/directive/sidebar.mdwn b/doc/ikiwiki/directive/sidebar.mdwn
new file mode 100644
index 000000000..599695d22
--- /dev/null
+++ b/doc/ikiwiki/directive/sidebar.mdwn
@@ -0,0 +1,20 @@
+The `sidebar` directive is supplied by the [[!iki plugins/sidebar desc=sidebar]] plugin.
+
+This directive can specify a custom sidebar to display on the page,
+overriding any sidebar that is displayed globally.
+
+If no custom sidebar content is specified, it forces the sidebar page to
+be used as the sidebar, even if the `global_sidebars` setting has been
+used to disable use of the sidebar page by default.
+
+## examples
+
+	\[[!sidebar content="""
+	This is my custom sidebar for this page.
+
+	\[[!calendar pages="posts/*"]]
+	"""]]
+
+	\[[!sidebar]]
+
+[[!meta robots="noindex, follow"]]
diff --git a/doc/ikiwiki/directive/table.mdwn b/doc/ikiwiki/directive/table.mdwn
index e27a94b7c..a6692f92c 100644
--- a/doc/ikiwiki/directive/table.mdwn
+++ b/doc/ikiwiki/directive/table.mdwn
@@ -6,8 +6,8 @@ or DSV (delimiter-separated values) format.
 ## examples
 
 	\[[!table data="""
-	Customer|Amount
-	Fulanito|134,34
+	Customer |Amount
+	Fulanito |134,34
 	Menganito|234,56
 	Menganito|234,56
 	"""]]
@@ -42,4 +42,9 @@ cells. For example:
   as the table header. Set it to "no" to make a table without a header, or
   "column" to make the first column be the header.
 
+For tab-delimited tables (often obtained by copying and pasting from HTML
+or a spreadsheet), `delimiter` must be set to a literal tab character. These
+are difficult to type in most web browsers - copying and pasting one from
+the table data is likely to be the easiest way.
+
 [[!meta robots="noindex, follow"]]
diff --git a/doc/ikiwiki/directive/tag.mdwn b/doc/ikiwiki/directive/tag.mdwn
index 64736f8cd..c8d9b9816 100644
--- a/doc/ikiwiki/directive/tag.mdwn
+++ b/doc/ikiwiki/directive/tag.mdwn
@@ -19,7 +19,8 @@ instead:
 Note that if the wiki is configured to use a tagbase, then the tags will be
 located under a base directory, such as "tags/". This is a useful way to
 avoid having to write the full path to tags, if you want to keep them
-grouped together out of the way.
+grouped together out of the way. Also, since ikiwiki then knows where to put
+tags, it will automatically create tag pages when new tags are used.
 
 Bear in mind that specifying a tagbase means you will need to incorporate it
 into the `link()` [[ikiwiki/PageSpec]] you use: e.g., if your tagbase is
@@ -28,7 +29,7 @@ into the `link()` [[ikiwiki/PageSpec]] you use: e.g., if your tagbase is
 If you want to override the tagbase for a particular tag, you can use
 something like this:
 
-	\[[!tag ./foo]]
+	\[[!tag /foo]]
 	\[[!taglink /foo]]
 
 [[!meta robots="noindex, follow"]]
diff --git a/doc/ikiwiki/directive/template.mdwn b/doc/ikiwiki/directive/template.mdwn
index d538b69b1..6c50fa32e 100644
--- a/doc/ikiwiki/directive/template.mdwn
+++ b/doc/ikiwiki/directive/template.mdwn
@@ -1,18 +1,87 @@
 The `template` directive is supplied by the [[!iki plugins/template desc=template]] plugin.
 
-[[Templates]] are files that can be filled out and inserted into pages in the
-wiki, by using the template directive. The directive has an `id` parameter
+The template directive allows wiki pages to be used as templates.
+These templates can be filled out and inserted into other pages in the
+wiki using the directive. The [[templates]] page lists templates
+that can be used with this directive.
+
+The directive has an `id` parameter
 that identifies the template to use. The remaining parameters are used to
 fill out the template.
 
-Example:
+## Example
 
 	\[[!template id=note text="""Here is the text to insert into my note."""]]
 
 This fills out the `note` template, filling in the `text` field with
 the specified value, and inserts the result into the page.
 
-For a list of available templates, and details about how to create more,
-see the [[templates]] page.
+## Using a template
+
+Generally, a value can include any markup that would be allowed in the wiki
+page outside the template. Triple-quoting the value even allows quotes to
+be included in it. Combined with multi-line quoted values, this allows for
+large chunks of marked up text to be embedded into a template:
+
+        \[[!template id=foo name="Sally" color="green" age=8 notes="""
+        * \[[Charley]]'s sister.
+        * "I want to be an astronaut when I grow up."
+        * Really 8 and a half.
+        """]]
+
+## Creating a template
+
+The template is a regular wiki page, located in the `templates/`
+subdirectory inside the source directory of the wiki.
+
+(Alternatively, templates can be stored in a directory outside the wiki,
+as files with the extension ".tmpl".
+By default, these are searched for in `/usr/share/ikiwiki/templates`;
+the `templatedir` setting can be used to make another directory be searched
+first.)
+
+The template uses the syntax used by the [[!cpan HTML::Template]] perl
+module, which allows for some fairly complex things to be done. Consult its
+documentation for the full syntax, but all you really need to know are a
+few things:
+
+* Each parameter you pass to the template directive will generate a 
+  template variable. There are also some pre-defined variables like PAGE
+  and BASENAME.
+* To insert the value of a variable, use `<TMPL_VAR variable>`. Wiki markup
+  in the value will first be converted to html.
+* To insert the raw value of a variable, with wiki markup not yet converted
+  to html, use `<TMPL_VAR raw_variable>`.
+* To make a block of text conditional on a variable being set use
+  `<TMPL_IF variable>text</TMPL_IF>`.
+* To use one block of text if a variable is set and a second if it's not,
+  use `<TMPL_IF variable>text<TMPL_ELSE>other text</TMPL_IF>`
+
+Here's a sample template:
+
+        <span class="infobox">
+        Name: \[[<TMPL_VAR raw_name>]]<br />
+        Age: <TMPL_VAR age><br />
+        <TMPL_IF color>
+        Favorite color: <TMPL_VAR color><br />
+        <TMPL_ELSE>
+        No favorite color.<br />
+        </TMPL_IF>
+        <TMPL_IF notes>
+        <hr />
+        <TMPL_VAR notes>
+        </TMPL_IF>
+        </span>
+
+The filled out template will be formatted the same as the rest of the page
+that contains it, so you can include WikiLinks and all other forms of wiki
+markup in the template. Note though that such WikiLinks will not show up as
+backlinks to the page that uses the template.
+
+Note the use of "raw_name" inside the [[ikiwiki/WikiLink]] generator in the
+example above. This ensures that if the name contains something that might
+be mistaken for wiki markup, it's not converted to html before being
+processed as a [[ikiwiki/WikiLink]].
+
 
 [[!meta robots="noindex, follow"]]