template docu reorg

Remove wikitemplates page; fold its contents into templates page.
Update all backlinks. Document new ability to put templates inside srcdir.

22 files changed, 111 insertions, 141 deletions

diff --git a/doc/bugs/SSI_include_stripped_from_mdwn.mdwn b/doc/bugs/SSI_include_stripped_from_mdwn.mdwn
index 5519e45c6..270da86d3 100644
--- a/doc/bugs/SSI_include_stripped_from_mdwn.mdwn
+++ b/doc/bugs/SSI_include_stripped_from_mdwn.mdwn
@@ -10,7 +10,7 @@ If I have a <--#include virtual="foo" --> in some file, it gets stripped,
 > Anyway, it makes sense for the htmlscrubber to strip server-side
 > includes because otherwise your wiki could be attacked
 > by them being added to it. If you want to use both the htmlscrubber and
-> SSI together, I'd suggest you modify the [[wikitemplates]]
+> SSI together, I'd suggest you modify the [[templates]]
 > and put the SSI on there.
 > 
 > Ie, `page.tmpl` has a 
diff --git a/doc/bugs/login_page_non-obvious_with_openid.mdwn b/doc/bugs/login_page_non-obvious_with_openid.mdwn
index 1d087985a..9aa702037 100644
--- a/doc/bugs/login_page_non-obvious_with_openid.mdwn
+++ b/doc/bugs/login_page_non-obvious_with_openid.mdwn
@@ -36,7 +36,7 @@ If you want to keep it as one form, then perhaps using some javascript to disabl
 > that allows modifying that form, but does not allow creating a separate
 > form. The best way to make it obvious how to use it currently is to just
 > disable password auth, then it's nice and simple. :-) Javascript is an
-> interesting idea. It's also possible to write a custom [[signin.tmpl wikitemplates]] that
+> interesting idea. It's also possible to write a custom [[templates]] that
 > is displayed instead of the regular signin form, and it should be
 > possible to use that to manually lay it out better than FormBuilder
 > manages with its automatic layout. --[[Joey]]
@@ -44,4 +44,4 @@ If you want to keep it as one form, then perhaps using some javascript to disabl
 > I've improved the form, I think it's more obvious now that the openid
 > stuff is separate. Good enough to call this [[done]]. I think. --[[Joey]]
 
->> Looks good, thanks!  :-) -- [[AdamShand]]
\ No newline at end of file
+>> Looks good, thanks!  :-) -- [[AdamShand]]
diff --git a/doc/features.mdwn b/doc/features.mdwn
index ab521213d..07ce648ea 100644
--- a/doc/features.mdwn
+++ b/doc/features.mdwn
@@ -72,7 +72,7 @@ you would care to syndicate.
 
 Ikiwiki aims to produce 
 [valid XHTML 1.0](http://validator.w3.org/check?url=referer). Ikiwiki
-generates html using [[templates|wikitemplates]], and uses [[css]], so you
+generates html using [[templates]], and uses [[css]], so you
 can change the look and layout of all pages in any way you would like.
 
 ## [[Plugins]]
diff --git a/doc/freesoftware.mdwn b/doc/freesoftware.mdwn
index 7ac1ac6b4..2243d9b1f 100644
--- a/doc/freesoftware.mdwn
+++ b/doc/freesoftware.mdwn
@@ -4,7 +4,7 @@ ikiwiki, and this documentation wiki, are licensed under the terms of the
 GNU [[GPL]], version 2 or later.
 
 The parts of ikiwiki that become part of your own wiki (the [[basewiki]]
-pages (but not the smilies) and the [[templates|wikitemplates]]) are licensed
+pages (but not the smilies) and the [[templates]]) are licensed
 as follows: 
 
 > Redistribution and use in source and compiled forms, with or without
diff --git a/doc/ikiwiki-calendar.mdwn b/doc/ikiwiki-calendar.mdwn
index c1f4d7267..03cbdd86c 100644
--- a/doc/ikiwiki-calendar.mdwn
+++ b/doc/ikiwiki-calendar.mdwn
@@ -43,7 +43,7 @@ An example crontab:
 
 # TEMPLATES
 
-This command uses two [[template|wikitemplates]] to generate
+This command uses two [[templates]] to generate
 the pages, `calendarmonth.tmpl` and `calendaryear.tmpl`.
 
 # AUTHOR
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/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/template.mdwn b/doc/ikiwiki/directive/template.mdwn
index ae71ba5b5..052ca7873 100644
--- a/doc/ikiwiki/directive/template.mdwn
+++ b/doc/ikiwiki/directive/template.mdwn
@@ -1,7 +1,11 @@
 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.
 
diff --git a/doc/plugins/autoindex.mdwn b/doc/plugins/autoindex.mdwn
index d1133e4f5..7c4e40419 100644
--- a/doc/plugins/autoindex.mdwn
+++ b/doc/plugins/autoindex.mdwn
@@ -3,5 +3,5 @@
 
 This plugin searches for [[SubPages|ikiwiki/subpage]] with a missing parent
 page, and generates the parent pages. The generated page content is
-controlled by the `autoindex.tmpl` [[template|wikitemplates]], which by
+controlled by the `autoindex.tmpl` [[template|templates]], which by
 default, uses a [[map]] to list the SubPages.
diff --git a/doc/plugins/map/discussion.mdwn b/doc/plugins/map/discussion.mdwn
index 2f7b140d6..54c921b0f 100644
--- a/doc/plugins/map/discussion.mdwn
+++ b/doc/plugins/map/discussion.mdwn
@@ -1,7 +1,7 @@
 I'm wanting a [[map]] (with indentation levels) showing page _titles_
 instead of page 'names'.  As far as I can see, this is not an option with
 existing plugins - I can get a list of pages using [[inline]] and
-appropriate [[wikitemplates]], but that has no indentation and therefore
+appropriate [[templates]], but that has no indentation and therefore
 doesn't show structure well.
 
 The quick way is to modify the map plugin to have a 'titles' option.  The
diff --git a/doc/plugins/pagetemplate.mdwn b/doc/plugins/pagetemplate.mdwn
index 53f069d0d..8254e14c5 100644
--- a/doc/plugins/pagetemplate.mdwn
+++ b/doc/plugins/pagetemplate.mdwn
@@ -3,8 +3,4 @@
 
 This plugin provides the [[ikiwiki/directive/pagetemplate]]
 [[ikiwiki/directive]], which allows a page to be displayed
-using a different [[template|wikitemplates]] than the default.
-
-This plugin can only use templates that are already installed in
-`/usr/share/ikiwiki/templates` (or wherever ikiwiki is configured to look for
-them). You can choose to use any .tmpl files in that directory.
+using a different [[template|templates]] than the default.
diff --git a/doc/plugins/template.mdwn b/doc/plugins/template.mdwn
index da775f232..8d17e2825 100644
--- a/doc/plugins/template.mdwn
+++ b/doc/plugins/template.mdwn
@@ -3,5 +3,5 @@
 
 This plugin provides the [[ikiwiki/directive/template]] [[ikiwiki/directive]].
 With this plugin, you can set up templates, and cause them to be filled out
-and inserted into pages in the wiki. It's documented and existing templates
-are listed in the [[templates]] page.
+and inserted into pages in the wiki. Existing templates are listed in the
+[[templates]] page.
diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 00b54bdd3..9128c7f54 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -297,7 +297,7 @@ value is ignored.
 
 	hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
 
-[[Templates|wikitemplates]] are filled out for many different things in
+[[Templates]] are filled out for many different things in
 ikiwiki, like generating a page, or part of a blog page, or an rss feed, or
 a cgi. This hook allows modifying the variables available on those
 templates. The function is passed named parameters. The "page" and
@@ -313,7 +313,7 @@ a new custom parameter to the template.
 
 	hook(type => "templatefile", id => "foo", call => \&templatefile);
 
-This hook allows plugins to change the [[template|wikitemplates]] that is
+This hook allows plugins to change the [[template|templates]] that is
 used for a page in the wiki. The hook is passed a "page" parameter, and
 should return the name of the template file to use (relative to the
 template directory), or undef if it doesn't want to change the default
diff --git a/doc/templates.mdwn b/doc/templates.mdwn
index f2b581d2f..f7b3adae5 100644
--- a/doc/templates.mdwn
+++ b/doc/templates.mdwn
@@ -1,17 +1,88 @@
-[[!meta robots="noindex, follow"]]
-[[!if test="enabled(template)"
-then="This wiki has templates **enabled**."
-else="This wiki has templates **disabled**."
-]]
+[[Ikiwiki]] uses many templates for many purposes. By editing its templates,
+you can fully customise this site.
 
-Templates are files that can be filled out and inserted into pages in the
-wiki.
+[[!if test="enabled(template)" then="""
+## The template directive
 
+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.
+"""]]
 [[!if test="enabled(template) and enabled(inline)" then="""
-
-These templates are available for use with the template directive.
-
 [[!inline pages="templates/* and !*/discussion" feeds=no archive=yes
 sort=title template=titlepage
 rootpage=templates postformtext="Add a new template named:"]]
 """]]
+
+[[!if test="enabled(edittemplate)" then="""
+## The edittemplate directive
+
+The edittemplate directive can be used to make new pages default to
+containing text from a template, which can be filled as out the page is
+edited.
+"""]]
+
+## Wiki templates
+
+These templates are used to build the wiki. The aim is to keep almost all
+html out of ikiwiki and in the templates.
+
+* `page.tmpl` - Used for displaying all regular wiki pages.
+* `misc.tmpl` - Generic template used for any page that doesn't
+  have a custom template.
+* `editpage.tmpl` - Create/edit page.
+* `change.tmpl` - Used to create a page describing a change made to the wiki.
+* `passwordmail.tmpl` - Not a html template, this is used to
+  generate a mail with an url the user can use to reset their password.
+* `rsspage.tmpl` - Used for generating rss feeds for [[blogs|blog]].
+* `rssitem.tmpl` - Used for generating individual items on rss feeds.
+* `atompage.tmpl` - Used for generating atom feeds for blogs.
+* `atomitem.tmpl` - Used for generating individual items on atom feeds.
+* `inlinepage.tmpl` - Used for adding a page inline in a blog
+  page.
+* `archivepage.tmpl` - Used for listing a page in a blog archive page.
+* `microblog.tmpl` - Used for showing a microblogging post inline.
+* `blogpost.tmpl` - Used for a form to add a post to a blog (and a rss/atom links)
+* `feedlink.tmpl` - Used to add rss/atom links if blogpost.tmpl is not used.
+* `aggregatepost.tmpl` - Used by the [[plugins/aggregate]] plugin to create
+  a page for a post.
+* `searchform.tmpl` - Used by the [[plugins/search]] plugin to add a search
+  form to wiki pages.
+* `searchquery.tmpl` - This is an omega template, used by the
+  [[plugins/search]] plugin.
+* `comment.tmpl` - This template is used to display a comment
+  by the [[plugins/comments]] plugin.
+* `editcomment.tmpl` - This template is the comment post form for the
+  [[plugins/comments]] plugin.
+* `commentmoderation.tmpl` - This template is used to produce the comment
+  moderation form.
+* `recentchanges.tmpl` - This template is used for listing a change
+  on the RecentChanges page.
+
+[[!if test="enabled(pagetemplate)" then="""
+## The pagetemplate directive
+
+The pagetemplate directive can allow individual pages to use a
+different template than `page.tmpl`.
+"""]]
+
+## Template locations
+
+Templates are located in `/usr/share/ikiwiki/templates` by default;
+the `templatedir` setting can be used to make another directory be
+searched first. Customized templates can also be placed inside the
+"templates/" directory in your wiki's source.
+
+## Template syntax
+
+Ikiwiki uses the HTML::Template module as its template engine. This
+supports things like conditionals and loops in templates and is pretty easy
+to learn. All you really need to know are a few things:
+
+* To insert the value of a template variable, use `<TMPL_VAR variable>`.
+* To make a block of text conditional on a variable being set use
+  `<TMPL_IF NAME="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 NAME="variable">text<TMPL_ELSE>other text</TMPL_IF>`
+
+[[!meta robots="noindex, follow"]]
diff --git a/doc/tips/comments_feed.mdwn b/doc/tips/comments_feed.mdwn
index 6f8137256..6d4dbb803 100644
--- a/doc/tips/comments_feed.mdwn
+++ b/doc/tips/comments_feed.mdwn
@@ -6,5 +6,5 @@ add a feed that contains all the comments posted to any page. Here's how:
 	\[[!inline pages="internal(*/comment_*)" template=comment]]
 
 The special [[ikiwiki/PageSpec]] matches all comments. The
-[[template|wikitemplates]] causes the comments to be displayed formatted
+[[template|templates]] causes the comments to be displayed formatted
 nicely.
diff --git a/doc/todo/auto-create_tag_pages_according_to_a_template.mdwn b/doc/todo/auto-create_tag_pages_according_to_a_template.mdwn
index f6d444890..7eb404910 100644
--- a/doc/todo/auto-create_tag_pages_according_to_a_template.mdwn
+++ b/doc/todo/auto-create_tag_pages_according_to_a_template.mdwn
@@ -17,7 +17,7 @@ The new tag file is then complied during the change phase.
 
 *see git history of this page if you want the patch --[[smcv]]*
 
-This uses a [[template|wikitemplates]] called `autotagpage.tmpl`, here is my template file:
+This uses a [[template|templates]] called `autotagpage.tmpl`, here is my template file:
 
     \[[!inline pages="link(<TMPL_VAR TAG>)" archive="yes"]]
 
diff --git a/doc/todo/auto_rebuild_on_template_change.mdwn b/doc/todo/auto_rebuild_on_template_change.mdwn
index a112cb9da..838d15c1a 100644
--- a/doc/todo/auto_rebuild_on_template_change.mdwn
+++ b/doc/todo/auto_rebuild_on_template_change.mdwn
@@ -6,7 +6,7 @@ This would allow setting:
 
 	templatedir => "$srcdir/templates",
 
-.. and then the [[wikitemplates]] are managed like other wiki files; and
+.. and then the [[templates]] are managed like other wiki files; and
 like other wiki files, a change to them automatically updates dependent
 pages.
 
diff --git a/doc/todo/html.mdwn b/doc/todo/html.mdwn
index 44f20c876..4f4542be2 100644
--- a/doc/todo/html.mdwn
+++ b/doc/todo/html.mdwn
@@ -1,6 +1,6 @@
 Create some nice(r) stylesheets.
 
 Should be doable w/o touching a single line of code, just
-editing the [[wikitemplates]] and/or editing [[style.css]].
+editing the [[templates]] and/or editing [[style.css]].
 
 [[done]] ([[css_market]] ..)
diff --git a/doc/todo/multiple_templates.mdwn b/doc/todo/multiple_templates.mdwn
index 72783c556..30fb8d6ee 100644
--- a/doc/todo/multiple_templates.mdwn
+++ b/doc/todo/multiple_templates.mdwn
@@ -1,4 +1,4 @@
-> Another useful feature might be to be able to choose a different [[template|wikitemplates]]
+> Another useful feature might be to be able to choose a different [[template|templates]]
 > file for some pages; [[blog]] pages would use a template different from the
 > home page, even if both are managed in the same repository, etc.
 
diff --git a/doc/usage.mdwn b/doc/usage.mdwn
index 2e12517ea..9cf61cc6c 100644
--- a/doc/usage.mdwn
+++ b/doc/usage.mdwn
@@ -120,10 +120,11 @@ also be configured using a setup file.
 
 * --templatedir dir
 
-  Specify the directory that the page [[templates|wikitemplates]] are stored in.
+  Specify the directory that [[templates|templates]] are stored in.
   Default is `/usr/share/ikiwiki/templates`, or another location as configured at
   build time. If the templatedir is changed, missing templates will still
-  be searched for in the default location as a fallback.
+  be searched for in the default location as a fallback. Templates can also be
+  placed in the "templates/" subdirectory of the srcdir.
 
   Note that if you choose to copy and modify ikiwiki's templates, you will need
   to be careful to keep them up to date when upgrading to new versions of
diff --git a/doc/wikitemplates.mdwn b/doc/wikitemplates.mdwn
deleted file mode 100644
index 6e5a7261d..000000000
--- a/doc/wikitemplates.mdwn
+++ /dev/null
@@ -1,52 +0,0 @@
-ikiwiki uses the HTML::Template module as its template engine. This
-supports things like conditionals and loops in templates and is pretty easy
-to learn.
-
-The aim is to keep almost all html out of ikiwiki and in the templates.
-
-It ships with some basic templates which can be customised. These are
-located in `/usr/share/ikiwiki/templates` by default; the `templatedir`
-setting can be used to make another directory be searched first.
-
-* `page.tmpl` - Used for displaying all regular wiki pages.
-* `misc.tmpl` - Generic template used for any page that doesn't
-  have a custom template.
-* `editpage.tmpl` - Create/edit page.
-* `change.tmpl` - Used to create a page describing a change made to the wiki.
-* `passwordmail.tmpl` - Not a html template, this is used to
-  generate a mail with an url the user can use to reset their password.
-* `rsspage.tmpl` - Used for generating rss feeds for [[blogs|blog]].
-* `rssitem.tmpl` - Used for generating individual items on rss feeds.
-* `atompage.tmpl` - Used for generating atom feeds for blogs.
-* `atomitem.tmpl` - Used for generating individual items on atom feeds.
-* `inlinepage.tmpl` - Used for adding a page inline in a blog
-  page.
-* `archivepage.tmpl` - Used for listing a page in a blog archive page.
-* `microblog.tmpl` - Used for showing a microblogging post inline.
-* `blogpost.tmpl` - Used for a form to add a post to a blog (and a rss/atom links)
-* `feedlink.tmpl` - Used to add rss/atom links if blogpost.tmpl is not used.
-* `aggregatepost.tmpl` - Used by the [[plugins/aggregate]] plugin to create
-  a page for a post.
-* `searchform.tmpl` - Used by the [[plugins/search]] plugin to add a search
-  form to wiki pages.
-* `searchquery.tmpl` - This is an omega template, used by the
-  [[plugins/search]] plugin.
-* `comment.tmpl` - This template is used to display a comment
-  by the [[plugins/comments]] plugin.
-* `editcomment.tmpl` - This template is the comment post form for the
-  [[plugins/comments]] plugin.
-* `commentmoderation.tmpl` - This template is used to produce the comment
-  moderation form.
-* `recentchanges.tmpl` - This template is used for listing a change
-  on the RecentChanges page.
-
-The [[plugins/pagetemplate]] plugin can allow individual pages to use a
-different template than `page.tmpl`.
-
-The [[plugins/template]] plugin also uses templates, though those
-[[templates]] are typically stored as pages in the wiki, and are inserted
-into pages.
-
-The [[plugins/edittemplate]] plugin is used to make new pages default to
-containing text from a template, which can be filled as out the page is
-edited.
diff --git a/doc/wikitemplates/discussion.mdwn b/doc/wikitemplates/discussion.mdwn
deleted file mode 100644
index f97444e5f..000000000
--- a/doc/wikitemplates/discussion.mdwn
+++ /dev/null
@@ -1,46 +0,0 @@
-## Place for local templates
-Where does one put any locally modified templates for an individual ikiwiki? --Ivan Z.
-
-> You can put them whereever you like; the `templatedir` controls
-> where ikiwiki looks for them. --[[Joey]] 
-
-Thank you for your response! My question arose out of my intention to make
-custom templates for a wiki--specifically suited for the kind of  content
-it will have--so, that would mean I would want to distribute them through
-git together with other content of the wiki. So, for this case the
-separation of conceptually ONE thing (the content, the templates, and the
-config option which orders to use these templates) into THREE separate
-files/repos (the main content repo, the repo with templates, and the config
-file) is not convenient: instead of distributing a single repo, I have to
-tell people to take three things if they want to replicate this wiki. How
-would you solve this inconvenience? Perhaps, a default location of the
-templates *inside* the source repo would do?--Ivan Z.
-
-> I would avoid putting the templates in a subdirectory of the ikiwiki srcdir.
-> (I'd also avoid putting the ikiwiki setup file there.)
-> While it's safe to do either in some cases, there are configurations where
-> it's unsafe. For example, a malicious user could use attachment handling to
-> replace those files with their own, bad versions.
-> 
-> So, two ideas for where to put the templatedir and ikiwiki setup. 
-
-> * The easiest option is to put your wiki content in a subdirectory
->   ("wiki", say) and point `srcdir` at that.
->   then you can have another subdirectory for the wikitemplates,
->   and put the setup file at the top.
-> * Another option if using git would be to have a separate branch,
->   in the same git repository, that holds wikitemplates and the setup file.
->   Then you check out the repository once to make the `srcdir` available,
->   and have a second checkout, of the other branch, to make the other stuff
->   available.
-> 
-> Note that with either of these methods, you have to watch out if
-> giving other direct commit access to the repository. They could
-> still edit the setup file and templates, so only trusted users should
-> be given access. (It is, however, perfectly safe to let people edit
-> the wiki via the web, and is even safe to configure
-> [[tips/untrusted_git_push]] to such a repository.) --[[Joey]]
-
-Thanks, that's a nice and simple idea: to have a subdirectory! I'll try it. --Ivan Z.
-
-A [[!taglink wish|wishlist]]: the ikiwiki program could be improved so that it follows the same logic as git in looking for its config: it could ascend directories until it finds an `.ikiwiki/` directory with `.ikiwiki/setup` and then uses that configuration. Now I'm tired to always type `ikiwiki --setup path/to/the/setup --refresh` when working in my working clone of the sources; I'd like to simply type `ikiwiki` instead, and let it find the setup file. The default location to look for templates could also be made to be a sibling of the setup file: `.ikiwiki/templates/`. --Ivan Z.