template docu reorg

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

diff --git a/doc/bugs/SSI_include_stripped_from_mdwn.mdwn b/doc/bugs/SSI_include_stripped_from_mdwn.mdwn
index 5519e45c682a450d5d5c027fb0b2a70398739736..270da86d34dda6af43e724d6382c25d0e5dcc44c 100644 (file)
--- 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
 > 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 
 > 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 1d087985a241d6603a0fae88377953a624a11291..9aa702037ba34a94ba5133f5fe68db991da3de46 100644 (file)
--- 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
 > 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]]
 > 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]]
 
 > 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 ab521213df223cdcfc400bcc6004bcd2d94b9146..07ce648eabdbcf3f864745f679037bde14d591d8 100644 (file)
--- 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
 
 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]]
 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 7ac1ac6b44e8663cd5d443db9d46a66c7fa7307d..2243d9b1f02c0a1192c2dcf2e22a8ddb87b775b2 100644 (file)
--- 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]]
 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
 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 c1f4d72670c92cc0bc79aafb40ec4dcb3aa76089..03cbdd86c1c66fdec8126ede029897036f9d8727 100644 (file)
--- a/doc/ikiwiki-calendar.mdwn
+++ b/doc/ikiwiki-calendar.mdwn
@@ -43,7 +43,7 @@ An example crontab:
 
 # TEMPLATES
 
 
 # TEMPLATES
 

-This command uses two [[template|wikitemplates]] to generate
+This command uses two [[templates]] to generate

 the pages, `calendarmonth.tmpl` and `calendaryear.tmpl`.
 
 # AUTHOR
 the pages, `calendarmonth.tmpl` and `calendaryear.tmpl`.
 
 # AUTHOR

diff --git a/doc/ikiwiki/directive/edittemplate.mdwn b/doc/ikiwiki/directive/edittemplate.mdwn
index d731bdb4708727d4515fc223321a841cbfacc5bf..c486e821b0fc3ddd66d61226cb53f56ab18ad6bc 100644 (file)
--- 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,
        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.
 
 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 8ad901c1a93b53816b444c1b3a55a9e07376ba82..401b38099b33a3c8638e3f4018b7ef4d89a82bc1 100644 (file)
--- 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.
 
 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.
 
 
 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"]]
        \[[!pagetemplate template="my_fancy.tmpl"]]
 
 [[!meta robots="noindex, follow"]]

diff --git a/doc/ikiwiki/directive/template.mdwn b/doc/ikiwiki/directive/template.mdwn
index ae71ba5b56e7f12306ece8a39e876e39920e8dc3..052ca78732cc2ad5477cc2ae4d03a15deef80438 100644 (file)
--- 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.
 
 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.
 
 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 d1133e4f55b0ceb7e82285c69aac069f8ea91447..7c4e40419a6d8b6bd792a92300e520e08ed73c7a 100644 (file)
--- 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
 
 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.
 default, uses a [[map]] to list the SubPages.

diff --git a/doc/plugins/map/discussion.mdwn b/doc/plugins/map/discussion.mdwn
index 2f7b140d6e6859369dd89d3fcf6a59ac63de7bc7..54c921b0fc46a4cf2ab8a414f49597d49658154d 100644 (file)
--- 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
 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
 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 53f069d0d578980f49bc4f7c36cea7ea5e31db5f..8254e14c5170c20a38aced748437112c67d61c82 100644 (file)
--- 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
 
 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 da775f232cec6336c56e2d969145462fff12c5ec..8d17e2825ebbd4bd34141b8e622ba835b4bb572c 100644 (file)
--- 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
 
 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 00b54bdd35de1e397beee474f70223f3a54be731..9128c7f5453bd14b679e37ea31fdd14510a3b58b 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -297,7 +297,7 @@ value is ignored.
 
        hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
 
 
        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
 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);
 
 
        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
 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 f2b581d2f8f76521225f7283fd1813bdf05a0f80..f7b3adae5adf0170cef71e151687447345593e5d 100644 (file)
--- 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="""
 [[!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:"]]
 """]]
 [[!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 6f8137256e54ba8b0068a62bbd20080f01ec6ac7..6d4dbb8039567a46f716da14b13510a0d925eb5c 100644 (file)
--- 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
        \[[!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.
 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 f6d444890086df1f6e7740496280a98e808fd931..7eb4049104ce20a9cdac056344778453140e50cc 100644 (file)
--- 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]]*
 
 
 *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"]]
 
 
     \[[!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 a112cb9da9581d9fa38dd0a96e49ba7d476f00bf..838d15c1a7ca60572551ba692cd366ec7092c654 100644 (file)
--- 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",
 
 
        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.
 
 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 44f20c8763f030970b67d40a2c8bce3657374186..4f4542be21233eed3ab54a199dcf954674dc4d49 100644 (file)
--- 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
 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]] ..)
 
 [[done]] ([[css_market]] ..)

diff --git a/doc/todo/multiple_templates.mdwn b/doc/todo/multiple_templates.mdwn
index 72783c556d3ddcaeeb6dfa616de918cefdcd312e..30fb8d6ee74b1cbfb56f1fcceb6cbf5b71bcedef 100644 (file)
--- 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.
 
 > 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 2e12517ea9105ab17e6e792a78271cc59f149a77..9cf61cc6cd667fc1cbf4ce328f16df1dad9c13b6 100644 (file)
--- a/doc/usage.mdwn
+++ b/doc/usage.mdwn
@@ -120,10 +120,11 @@ also be configured using a setup file.
 
 * --templatedir dir
 
 
 * --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
   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
 
   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 (file)
index 6e5a726..0000000
--- 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 (file)
index f97444e..0000000
--- 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.