reword, reorg, add example

[git.ikiwiki.info.git] / doc / templates.mdwn

diff --git a/doc/templates.mdwn b/doc/templates.mdwn
index f7b3adae5adf0170cef71e151687447345593e5d..0e54ae8a0840a4cdfd85bf889dae8c77a80a9671 100644 (file)
--- a/doc/templates.mdwn
+++ b/doc/templates.mdwn
@@ -2,69 +2,72 @@
 you can fully customise this site.
 
 [[!if test="enabled(template)" then="""
 you can fully customise this site.
 
 [[!if test="enabled(template)" then="""

-## The template directive
+## template pages

 
 

-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 template directive allows wiki pages to be used as templates,
+filled out and inserted into other pages in the wiki.

 """]]
 [[!if test="enabled(template) and enabled(inline)" then="""
 [[!inline pages="templates/* and !*/discussion" feeds=no archive=yes
 sort=title template=titlepage
 rootpage=templates postformtext="Add a new template named:"]]
 """]]
 """]]
 [[!if test="enabled(template) and enabled(inline)" then="""
 [[!inline pages="templates/* and !*/discussion" feeds=no archive=yes
 sort=title template=titlepage
 rootpage=templates postformtext="Add a new template named:"]]
 """]]

+[[!if test="enabled(template)" then="""
+[[!template id=note text="This note box is built using the
+[[note]] template!"]]
+[[!template id=popup mouseover="popup example" popup="This popup is built using
+the [[popup]] template!"]]
+"""]]

 
 [[!if test="enabled(edittemplate)" then="""
 
 [[!if test="enabled(edittemplate)" then="""

-## The edittemplate directive
+## edit templates

 
 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.
 """]]
 
 
 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
+## 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.
 
 
 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.
+* `page.tmpl` - Used for displaying all regular wiki pages. This is the
+  key template customize.
+[[!if test="enabled(pagetemplate)" then="""
+  (The pagetemplate directive can be used to make a page use a
+  different template than `page.tmpl`.)
+"""]]

 * `misc.tmpl` - Generic template used for any page that doesn't
   have a custom template.
 * `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]].
+* `rsspage.tmpl` - Used for generating rss feeds for blogs.

 * `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.
 * `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.
+* `inlinepage.tmpl` - Used for displaying a post in a blog.

 * `archivepage.tmpl` - Used for listing a page in a blog archive page.
 * `archivepage.tmpl` - Used for listing a page in a blog archive page.

+* `titlepage.tmpl` - Used for listing a page by title 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)
 * `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
+* `feedlink.tmpl` - Used to add rss/atom links if `blogpost.tmpl` is not used.
+* `aggregatepost.tmpl` - Used by the aggregate plugin to create

   a page for a post.
   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`.
-"""]]
+* `searchform.tmpl`, `googleform.tmpl` - Used by the search plugin 
+  and google plugin to add search forms to wiki pages.
+* `searchquery.tmpl` - This is a Omega template, used by the
+  search plugin.
+* `comment.tmpl` - Used by the comments plugin to display a comment.
+* `change.tmpl` - Used to create a page describing a change made to the wiki.
+* `recentchanges.tmpl` - Used for listing a change on the RecentChanges page.
+* `autoindex.tmpl` - Filled in by the autoindex plugin to make index pages.
+* `autotag.tmpl` - Filled in by the tag plugin to make tag pages.
+* `calendarmonth.tmpl`, `calendaryear.tmpl` - Used by ikiwiki-calendar to
+  make calendar archive pages.
+* `editpage.tmpl`, `editconflict.tmpl`, `editcreationconflict.tmpl`,
+  `editfailedsave.tmpl`, `editpagegone.tmpl`, `pocreatepage.tmpl`,
+  `editcomment.tmpl` `commentmoderation.tmpl`, `renamesummary.tmpl`,
+  `passwordmail.tmpl` - Parts of ikiwiki's user interface; do not
+  normally need to be customised.

 
 ## Template locations
 
 
 ## Template locations