12 files changed, 535 insertions, 0 deletions
diff --git a/doc/ikiwiki/blog.mdwn b/doc/ikiwiki/blog.mdwn
new file mode 100644
index 000000000..6e5eec4aa
--- /dev/null
+++ b/doc/ikiwiki/blog.mdwn
@@ -0,0 +1,97 @@
+[[if test="enabled(inline)"
+     then="This wiki has the inline plugin **enabled**."
+     else="This wiki has the inline plugin **disabled**."]]
+
+[[if test="enabled(inline)"
+     then="You can"
+     else="If this wiki had the inline plugin enabled, you could"]]
+turn any page on this wiki into a weblog by using the `inline`
+[[PreProcessorDirective]]. For example:
+
+	\[[inline pages="blog/* and !*/Discussion" show="10" rootpage="blog"]]
+
+Any pages that match the specified [[PageSpec]] (in the example, any
+[[SubPage]] of "blog") will be part of the blog, and the newest 10
+of them will appear in the page. Note that if files that are not pages
+match the [[PageSpec]], they will be included in the feed using RSS
+enclosures, which is useful for podcasting.
+
+The optional `rootpage` parameter tells the wiki that new posts to this blog
+should default to being [[SubPage]]s of "blog", and enables a form at the
+top of the blog that can be used to add new items.
+
+If you want your blog to have an archive page listing every post ever made
+to it, you can accomplish that like this:
+
+	\[[inline pages="blog/* and !*/Discussion" archive="yes"]]
+
+You can even create an automatically generated list of all the pages on the
+wiki, with the most recently added at the top, like this:
+
+	\[[inline pages="* and !*/Discussion" archive="yes"]]
+
+If you want to be able to add pages to a given blog feed by tagging them,
+you can do that too. To tag a page, just make it link to a page or pages 
+that represent its tags. Then use the special `link()` [[PageSpec]] to match
+all pages that have a given tag:
+
+	\[[inline pages="link(life)"]]
+
+Or include some tags and exclude others:
+
+	\[[inline pages="link(debian) and !link(social)"]]
+
+## usage
+
+Here are descriptions of all the supported parameters to the `inline`
+directive:
+
+* `pages` - A [[PageSpec]] of the pages to inline.
+* `show` - Specify the maximum number of matching pages to inline.
+  Default is 10, unless archiving, when the default is to show all.
+  Set to 0 to show all matching pages.
+* `skip` - Specify a number of pages to skip displaying. Can be useful
+  to produce a feed that only shows archived pages.
+* `rss` - controls generation of an rss feed. On by default if the wiki is
+  configured to use rss feeds, set to "no" to disable.
+* `atom` - controls generation of an atom feed. On by default if the wiki is
+  configured to use atom feeds, set to "no" to disable.
+* `feeds` - controls generation of all types of feeds. Set to "no" to
+  disable generating any feeds.
+* `postform` - Set to "yes" to enables a form to post new pages to a [[blog]].
+* `postformtext` - Set to specify text that is displayed in a postform.
+* `rootpage` - Also enables a form to post new pages to a [[blog]], and
+  allows specifying of a page that is used as the parent page for new pages.
+* `archive` - If set to "yes", only list page titles and some metadata, not
+  full controls.
+* `quick` - Build archives in quick mode, without reading page contents for
+  metadata. By default, this also turns off generation of any feeds.
+* `template` - Specifies the template to fill out to display each inlined
+  page. By default the `inlinepage` template is used, while
+  the `archivepage` template is used for archives. Set this parameter to
+  use some other, custom template, such as the `titlepage` template that
+  only shows post titles. Note that you should still set `archive=yes` if
+  your custom template does not include the page content.
+* `raw` - Rather than the default behavior of creating a [[blog]],
+  if raw is set to "yes", the page will be included raw, without additional
+  markup around it, as if it were a literal part of the source of the 
+  inlining page.
+* `description` - Sets the description of the rss feed if one is generated.
+  Defaults to the name of the wiki.
+* `actions` - If set to "yes" add links to the bottom of the inlined pages 
+  for editing and discussion (if they would be shown at the top of the page
+  itself).
+* `sort` - Controls how inlined pages are sorted. The default, "age" is to
+  sort newest created pages first. Setting it to "title" will sort pages by
+  title, and "mtime" sorts most recently modified pages first.
+* `reverse` - If set to "yes", causes the sort order to be reversed.
+* `feedpages` - A [[PageSpec]] of inlined pages to include in the rss/atom
+  feeds. The default is the same as the `pages` value above, and only pages
+  matches by that value are included, but some of those can be excluded by
+  specifying a tighter [[PageSpec]] here.
+* `feedshow` - Specify the maximum number of matching pages to include in
+  the rss/atom feeds. The default is the same as the `show` value above.
+* `feedonly` - Only generate the feed, do not display the pages inline on
+  the page.
+* `timeformat` - Use this to specify how to display the time or date for pages
+  in the blog. The format string is passed to the strftime(3) function.
diff --git a/doc/ikiwiki/blog/discussion.mdwn b/doc/ikiwiki/blog/discussion.mdwn
new file mode 100644
index 000000000..8e98e2e5e
--- /dev/null
+++ b/doc/ikiwiki/blog/discussion.mdwn
@@ -0,0 +1,37 @@
+## 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
+> docs in [[plugins/inline]]. --[[Joey]]
+
+And do you have any ideas/hints about implementing a "comments" feature.
+What I'm after is something for users who don't quite understand the Wiki
+style for discussions.  I would like to have a form for them to post a
+comment and have the comment appended to the discussion Wiki-style.  Maybe
+take it as far as implementing "replies" to other comments.
+
+-- Marcelo
+
+> See [[todo/discussion_page_as_blog]] for some of my own thoughts on this
+> --[[Joey]]
+
+---
+
+## More dynamic `rootpage` parameter of inline plugin?
+
+I prefer to use a current year, month and day to archive my blog posts, for example
+`post/2007/11/12/foo-bar-baz` path is better for me then `post/foo-bar-baz`.
+Unfortunately it seems that `rootpage` parameter of inline plugin is very static.
+Is it a chance to make it more dynamic? Now I have to use `svn mkdir` command
+to create appropriate subdirectories by hand.
+
+I think that you could add builtin functions or variables, for example `current_year()`
+or `$CURRENT_YEAR` to usage inside `rootpage` parameter. Something like for Manoj's
+calendar plugin. Then my `rootpage` parameter could be like
+`rootpage="post/current_year()/current_month()/current_day()"`. Another good hints
+are welcomed ;)
+
+What's your opinion, Joey? I hope it's also useful for another ikiwiki lovers :)
+
+--[[Paweł|ptecza]]
+
+>> Hello Joey! Is it a taboo subject? ;) --[[Paweł|ptecza]]
diff --git a/doc/ikiwiki/formatting.mdwn b/doc/ikiwiki/formatting.mdwn
new file mode 100644
index 000000000..69e28913f
--- /dev/null
+++ b/doc/ikiwiki/formatting.mdwn
@@ -0,0 +1,94 @@
+[[meta title="Formatting wiki pages"]]
+
+Text on this wiki is, by default, written in a form very close to how you
+might write text for an email message. This style of text formatting is
+called [[MarkDown]], and it works like this:
+
+Leave blank lines between paragraphs.
+
+You can \**emphasise*\* or \*\***strongly emphasise**\*\* text by placing it
+in single or double asterisks.
+
+To create a list, start each line with an asterisk:
+
+* "* this is my list"
+* "* another item"
+
+To make a numbered list, start each line with a number (any number will
+do) followed by a period:
+
+1. "1. first line"
+2. "2. second line"
+2. "2. third line"
+
+To create a header, start a line with one or more `#` characters followed
+by a space and the header text. The number of `#` characters controls the
+size of the header:
+
+# # h1
+## ## h2
+### ### h3
+#### #### h4
+##### ##### h5
+###### ###### h6
+
+To create a horizontal rule, just write three or more dashes or stars on
+their own line:
+
+----
+
+To quote someone, prefix the quote with ">":
+
+> To be or not to be,
+> that is the question.
+
+To write a code block, indent each line with a tab or 4 spaces:
+
+	10 PRINT "Hello, world!"
+	20 GOTO 10
+
+To link to an url or email address, you can just put the
+url in angle brackets: <<http://ikiwiki.info>>, or you can use the
+form \[link text\]\(url\)
+
+----
+
+In addition to basic html formatting using [[MarkDown]], this wiki lets
+you use the following additional features:
+
+* To link to another page on the wiki, place the page's name inside double
+  square brackets. So you would use `\[[WikiLink]]` to link to [[WikiLink]].
+
+[[if test="enabled(smiley) and smileys" then="""
+* Insert [[smileys]] and some other useful symbols. :-)
+"""]]
+
+[[if test="enabled(shortcut) and shortcuts" then="""
+* Use [[shortcuts]] to link to common resources.
+
+	\[[wikipedia War\_of\_1812]]
+"""]]
+
+[[if test="enabled(toc)" then="""
+* Add a table of contents to a page:
+
+	\[[toc ]]
+"""]]
+
+
+[[if test="enabled(meta)" then="""
+* Change the title of a page:
+
+	\[[meta title="full page title"]]
+"""]]
+
+[[if test="enabled(inline) and blog" then="""
+* Create a [[blog]] by inlining a set of pages:
+
+	\[[inline pages="blog/*"]]
+"""]]
+
+[[if test="enabled(template) and templates" then="""
+* Create and fill out [[templates]] for repeated chunks of
+  parameterized wiki text.
+"""]]
diff --git a/doc/ikiwiki/markdown.mdwn b/doc/ikiwiki/markdown.mdwn
new file mode 100644
index 000000000..73aee9c16
--- /dev/null
+++ b/doc/ikiwiki/markdown.mdwn
@@ -0,0 +1,12 @@
+[Markdown](http://daringfireball.net/projects/markdown/)
+is a minimal markup language that resembles plain text as used in
+email messages. It is the markup language used by this wiki by default.
+
+For documentation about the markdown syntax, see [[formatting]] and
+[Markdown: syntax](http://daringfireball.net/projects/markdown/syntax). A
+[markdown mode](http://jrblevin.freeshell.org/software/markdown-mode/) for 
+emacs can help in editing.
+
+Note that [[WikiLink]]s and [[PreProcessorDirective]]s are not part of the
+markdown syntax, and are the only bit of markup that this wiki handles
+internally.
diff --git a/doc/ikiwiki/openid.mdwn b/doc/ikiwiki/openid.mdwn
new file mode 100644
index 000000000..f02a0a62c
--- /dev/null
+++ b/doc/ikiwiki/openid.mdwn
@@ -0,0 +1,32 @@
+[[meta title="OpenID"]]
+
+[[if test="enabled(openid)"
+     then="This wiki has OpenID **enabled**."
+     else="This wiki has OpenID **disabled**."]]
+
+[OpenID](http://openid.net) is a decentralized authentication mechanism
+that allows you to have one login that you can use on a growing number of
+websites.
+
+To sign up for an OpenID, visit one of the following identity providers:
+
+* [MyOpenID](https://www.myopenid.com/)
+* [GetOpenID](https://getopenid.com/)
+* [Videntity](http://videntity.org/)
+* [LiveJournal](http://www.livejournal.com/openid/)
+* or any of the [many others out there](http://openiddirectory.com/index.php?dir=1)..
+
+Your OpenID is the URL that you are given when you sign up.
+[[if test="enabled(openid)" then="""
+To sign in to this wiki using OpenID, just enter it in the OpenID field in the
+signin form. You do not need to give this wiki a password or go through any
+registration process when using OpenID.
+"""]]
+
+---
+
+It's also possible to make a page in the wiki usable as an OpenID url,
+by delegating it to an openid server. Here's an example of how to do that:
+
+	\[[meta openid="http://yourid.myopenid.com/"
+	       server="http://www.myopenid.com/server"]]
diff --git a/doc/ikiwiki/pagespec.mdwn b/doc/ikiwiki/pagespec.mdwn
new file mode 100644
index 000000000..5c6433ed3
--- /dev/null
+++ b/doc/ikiwiki/pagespec.mdwn
@@ -0,0 +1,79 @@
+To select a set of pages, such as pages that are locked, pages
+whose commit emails you want subscribe to, or pages to combine into a
+blog, the wiki uses a PageSpec. This is an expression that matches
+a set of pages.
+
+The simplest PageSpec is a simple list of pages. For example, this matches
+any of the three listed pages:
+
+	foo or bar or baz
+
+More often you will want to match any pages that have a particular thing in
+their name. You can do this using a glob pattern. "`*`" stands for any part
+of a page name, and "`?`" for any single letter of a page name. So this
+matches all pages about music, and any [[SubPage]]s of the SandBox, but does
+not match the SandBox itself:
+
+	*music* or SandBox/*
+
+You can also prefix an item with "`!`" to skip pages that match it. So to
+match all pages except for Discussion pages and the SandBox:
+
+	* and !SandBox and !*/Discussion
+
+Some more elaborate limits can be added to what matches using any of these
+functions:
+
+* "`link(page)`" - match only pages that link to a given page (or glob)
+* "`backlink(page)`" - match only pages that a given page links to
+* "`creation_month(month)`" - match only pages created on the given month
+* "`creation_day(mday)`" - or day of the month
+* "`creation_year(year)`" - or year
+* "`created_after(page)`" - match only pages created after the given page
+  was created
+* "`created_before(page)`" - match only pages created before the given page
+  was created
+* "`user(name)`" - only available in page subscription preferences, match
+  only changes made by this user
+
+For example, to match all pages in a blog that link to the page about music
+and were written in 2005:
+
+	blog/* and link(music) and creation_year(2005)
+
+Note the use of "and" in the above example, that means that only pages that
+match each of the three expressions match the whole. Use "and" when you
+want to combine expression like that; "or" when it's enough for a page to
+match one expression. Note that it doesn't make sense to say "index and
+SandBox", since no page can match both expressions.
+
+More complex expressions can also be created, by using parentheses for
+grouping. For example, to match pages in a blog that are tagged with either
+of two tags, use:
+
+	blog/* and (link(tag/foo) or link(tag/bar))
+
+Note that page names in PageSpecs are matched against the absolute
+filenames of the pages in the wiki, so a pagespec "foo" used on page
+"a/b" will not match a page named "a/foo" or "a/b/foo". To match
+relative to the directory of the page containing the pagespec, you can
+use "./". For example, "./foo" on page "a/b" matches page "a/foo".
+
+## Old syntax
+
+The old PageSpec syntax was called a "GlobList", and worked differently in
+two ways:
+
+1. "and" and "or" were not used; any page matching any item from the list
+   matched.
+2. If an item was prefixed with "`!`", then no page matching that item
+   matched, even if it matched an earlier list item.
+
+For example, here is the old way to match all pages except for the SandBox
+and Discussion pages:
+
+	* !SandBox !*/Discussion
+
+Using this old syntax is still supported. However, the old syntax is
+deprecated and will be removed at some point, and using the new syntax is
+recommended.
diff --git a/doc/ikiwiki/pagespec/discussion.mdwn b/doc/ikiwiki/pagespec/discussion.mdwn
new file mode 100644
index 000000000..ab05e3e78
--- /dev/null
+++ b/doc/ikiwiki/pagespec/discussion.mdwn
@@ -0,0 +1,52 @@
+I am using ikiwiki 2.6.1.
+
+I can't figure out the locked pages.
+
+As an admin in preferences, I put in my Locked Pages:
+
+index and downloads
+
+I don't want anyone to be able to edit the front page or my downloads page.
+
+That didn't work. I am using a different web browser as a different non-ikiwiki-admin user.
+
+So I changed it to
+
+/index and /downloads
+
+That stopped me from editing the front page. It didn't say it was locked just repeatedly gave me the ikiwiki login. (How can I get it to tell me it is locked instead?)
+
+I also tried
+
+/index and /downloads/index
+
+But I could still edit my downloads page.
+
+Can someone share some hints on how to lock these two pages?
+
+My source pages for the lock are:
+
+source/downloads.mdwn
+source/index.mdwn
+
+My webpages to lock are:
+
+public\_html/downloads/index.html
+public\_html/index.html
+
+> So I tried again with using "or" instead of "and":
+>
+> index or downloads
+>
+> And that worked. I now get a message saying it is locked and cannot be edited.
+> To me saying "lock both 'index and downloads'" made sense while now it reads like: "lock either 'index or downloads'". Maybe the [[PageSpec]] should define "and" and "or" (beyond the examples it has).
+>
+> Also why did my "/index and /downloads" prevent editing the index by repeatedly showing login webpage?
+>
+> -JeremyReed
+
+>> I've clarified and/or in [[PageSpec]].
+>> 
+>> I can't reproduce "/index and /downloads" causing the login webpage to
+>> be shown repeatedly. Sure you weren't having some independent issue with
+>> logging in? --[[Joey]]
diff --git a/doc/ikiwiki/preprocessordirective.mdwn b/doc/ikiwiki/preprocessordirective.mdwn
new file mode 100644
index 000000000..1e2332c09
--- /dev/null
+++ b/doc/ikiwiki/preprocessordirective.mdwn
@@ -0,0 +1,33 @@
+Preprocessor directives are similar to a [[WikiLink]] in form, except they
+contain spaces and parameters. The general form is:
+
+	\[[directive param="value" param="value"]]
+
+This gets expanded before the rest of the page is processed, and can be used
+to transform the page in various ways.
+
+The quotes around values can be omitted if the value is a simple word.
+Also, some directives may use parameters without values, for example:
+
+	\[[tag foo]]
+
+Note that if a preprocessor directive has no parameters, a space still must
+be put after its name, to avoid confusion with a [[WikiLink]]. For example:
+
+	\[[pagecount ]]
+
+A preprocessor directive does not need to all be on one line, it can be
+wrapped to multiple lines if you like:
+	
+	\[[directive foo="baldersnatch"
+	bar="supercalifragalisticexpealadocious" baz=11]]
+
+Also, multiple lines of *quoted* text can be used for a value.
+To allow quote marks inside the quoted text, delimit the block
+of text with triple-quotes:
+
+	\[[directive text="""
+	1. "foo"
+	2. "bar"
+	3. "baz"
+	"""]]
diff --git a/doc/ikiwiki/subpage.mdwn b/doc/ikiwiki/subpage.mdwn
new file mode 100644
index 000000000..43669209c
--- /dev/null
+++ b/doc/ikiwiki/subpage.mdwn
@@ -0,0 +1,11 @@
+ikiwiki supports placing pages in a directory hierarchy. For example,
+this page, [[SubPage]] has some related pages placed under it, like
+[[SubPage/LinkingRules]]. This is a useful way to add some order to your
+wiki rather than just having a great big directory full of pages.
+
+To add a SubPage, just make a subdirectory and put pages in it. For
+example, this page is SubPage.mdwn in this wiki's source, and there is also
+a SubPage subdirectory, which contains SubPage/LinkingRules.mdwn. Subpages
+can be nested as deeply as you'd like.
+
+Linking to and from a SubPage is explained in [[LinkingRules]].
diff --git a/doc/ikiwiki/subpage/linkingrules.mdwn b/doc/ikiwiki/subpage/linkingrules.mdwn
new file mode 100644
index 000000000..c1062304a
--- /dev/null
+++ b/doc/ikiwiki/subpage/linkingrules.mdwn
@@ -0,0 +1,32 @@
+To link to or from a [[SubPage]], you can normally use a regular
+[[WikiLink]] that does not contain the name of the parent directory of
+the [[SubPage]]. Ikiwiki descends the directory hierarchy looking for a
+page that matches your link.
+
+For example, if FooBar/SubPage links to "OtherPage", ikiwiki will first 
+prefer pointing the link to FooBar/SubPage/OtherPage if it exists, next
+to FooBar/OtherPage and finally to OtherPage in the root of the wiki.
+
+Note that this means that if a link on FooBar/SomePage to "OtherPage"
+currently links to OtherPage, in the root of the wiki, and FooBar/OtherPage
+is created, the link will _change_ to point to FooBar/OtherPage. On the
+other hand, a link from BazBar to "OtherPage" would be unchanged by this
+creation of a [[SubPage]] of FooBar.
+
+You can also specify a link that contains a directory name, like
+"FooBar/OtherPage" to more exactly specify what page to link to. This is
+the only way to link to an unrelated [[SubPage]].
+
+You can use this to, for example, to link from BazBar to "FooBar/SubPage",
+or from BazBar/SubPage to "FooBar/SubPage".
+
+You can also use "/" at the start of a link, to specify exactly which page
+to link to, when there are multiple pages with similar names and the link
+goes to the wrong page by default. For example, linking from
+"FooBar/SubPage" to  "/OtherPage" will link to the "OtherPage" in the root
+of the wiki, even if there is a "FooBar/OtherPage".
+
+Also, if the wiki is configured with a userdir, you can link to pages
+within the userdir without specifying a path to them. This is to allow for
+easy linking to a user's page in the userdir, to sign a comment. These
+links are checked for last of all.
diff --git a/doc/ikiwiki/wikilink.mdwn b/doc/ikiwiki/wikilink.mdwn
new file mode 100644
index 000000000..38df00f86
--- /dev/null
+++ b/doc/ikiwiki/wikilink.mdwn
@@ -0,0 +1,27 @@
+WikiLinks provide easy linking between pages of the wiki. To create a
+[[WikiLink]], just put the name of the page to link to in double brackets.
+For example `\[[WikiLink]]`.
+
+If you ever need to write something like `\[[WikiLink]]` without creating a
+wikilink, just prefix it with a `\`, like `\\[[WikiLink]]`.
+
+There are some special [[SubPage/LinkingRules]] that come into play when
+linking between [[SubPages|SubPage]].
+
+Also, if the file linked to by a WikiLink looks like an image, it will
+be displayed inline on the page.
+
+WikiLinks are matched with page names in a case-insensitive manner, so you
+don't need to worry about getting the case the same, and can capitalise
+links at the start of a sentence, and so on.
+
+It's also possible to write a WikiLink that uses something other than the page
+name as the link text. For example `\[[foo_bar|SandBox]]` links to the SandBox
+page, but the link will appear like this: [[foo_bar|SandBox]].
+
+To link to an anchor inside a page, you can use something like
+`\[[WikiLink#foo]]`
+
+**Note that you cannot use spaces in WikiLinks**. Replace spaces with
+underscores. The presence of spaces is used to distinguish between a
+[[PreprocessorDirective]] and a WikiLink.
diff --git a/doc/ikiwiki/wikilink/discussion.mdwn b/doc/ikiwiki/wikilink/discussion.mdwn
new file mode 100644
index 000000000..d81163670
--- /dev/null
+++ b/doc/ikiwiki/wikilink/discussion.mdwn
@@ -0,0 +1,29 @@
+# Creating an anchor in Markdown
+
+Is it a native Markdown "tag" for creating an anchor? Unfortunately,
+I haven't any information about it at
+[Markdown syntax](http://daringfireball.net/projects/markdown/syntax) page.
+
+Of course, I know that I can use HTML tag to do it,
+for example &lt;a name="foo" /&gt;, but I don't want to mix Markdown
+and HTML code if it's not necessary.
+
+BTW, ikiwiki doesn't displays the #foo anchor in the example
+("To link to an anchor inside a page...") at [[WikiLink]] page...
+
+--[[Paweł|ptecza]]
+
+> No such syntax exists in markdown.  ikiwiki could certainly have a
+> [[preprocessor_directive|preprocessordirective]] for it, though.
+>
+> The lack of the `#foo` anchor in the anchor example on [[wikilink]]
+> definitely looks like a bug.  --[[JoshTriplett]]
+
+>> Fixed that --[[Joey]]
+
+---
+
+Considering a hierarchy like `foo/bar/bar`, I had the need to link from the
+`foo/bar/bar` page to the `foo/bar` one.  It would have been convenient to
+simply write [[wikilink]]s like `\[[../bar]]` (or even just `\[[..]]`?), but
+this doesn't work, so I had to resort to using `\[[foo/bar]]` instead.