Merge branch 'master'

Conflicts:
	doc/ikiwiki-makerepo.mdwn

14 files changed, 358 insertions, 2 deletions

diff --git a/doc/forum/Adding_new_markup_to_markdown.mdwn b/doc/forum/Adding_new_markup_to_markdown.mdwn
new file mode 100644
index 000000000..39d233add
--- /dev/null
+++ b/doc/forum/Adding_new_markup_to_markdown.mdwn
@@ -0,0 +1,11 @@
+I'm using ikiwiki to manage my personal wiki. One of the things I'm toying with is storing my grocery list in a wiki. The way I typically grocery-shop is to make one huge master list containing all the items I typically buy in a single cycle. Then, on any given trip, I make a subset list containing only the items I need. I'd like to streamline this process by making the master list a series of checkboxes. Before each trip, I load the list page on my phone, check off all the items I already have, then check off individual items as I get them.
+
+I'm not sure if there's a convenient way of adding checkboxes to wiki pages, and after a bit of thought I decided that "( )" would be a good markup for this. Ideally I'd like to still have access to other markdown conventions so I could, say, organize the list with headings and such when it grows large, so I don't want to create an entirely separate format, or a separate copy of the markdown plugin.
+
+Is there an existing means of, say, adding supersets to wiki markup? I suppose I could use an inline directive that inserts a multisellect HTML element, but I really like ( ). :)
+
+Ideal would be some sort of filter infrastructure. Plugins could register with a larger filter plugin that adds an inline directive. I could then invoke the checkbox filter at the top of my grocery list, and all instances of ( ) would be replaced with HTML. Might also make sense for the individual filters to specify whether or not they're invoked before or after the page template, or perhaps just always invoke them after. *shrug*
+
+Does something like this exist? I'd really like to avoid messing around with raw HTML or an inline for each of 40-50 list items. :)
+
+-- [[Nolan]]
diff --git a/doc/forum/Darcs_as_the_RCS___63__.mdwn b/doc/forum/Darcs_as_the_RCS___63__.mdwn
new file mode 100644
index 000000000..2635690f7
--- /dev/null
+++ b/doc/forum/Darcs_as_the_RCS___63__.mdwn
@@ -0,0 +1,11 @@
+Hi,
+
+I have successfully installed and set up my first instance of [[ikiwiki]] on my dedicated server. Following [[joey]]'s screencasts made this easy (thank you).
+
+Currently, I have set up the RCS to be git but I do not like this very much. I'd rather want darcs but if I replace rcs settings, it fails.
+
+What should I put in the configuration file to use darcs ?
+
+> Darcs is not yet supported. It's being [[worked_on|todo/darcs]].
+
+> > That's good news for me then ! Thank you.
diff --git a/doc/forum/How_does_ikiwiki_remember_times__63__.mdwn b/doc/forum/How_does_ikiwiki_remember_times__63__.mdwn
new file mode 100644
index 000000000..5522cbf45
--- /dev/null
+++ b/doc/forum/How_does_ikiwiki_remember_times__63__.mdwn
@@ -0,0 +1,89 @@
+This is similar to the last post in this forum. I want to know exactly how ikiwiki remembers the times associated with pages, especially when using it for blogging, so I know whether I can trust it or not. From that last thread, I think what ikiwiki does is this:
+
+*   The created time of a file is when that file was first committed into the versioning repository (in my case git)
+
+    > If `--getctime` it used, yes. In normal operation, when new files
+    > are added, ikiwiki sets the creation time to the ctime of the file
+    > on disk, rather than bothering to ask the VCS. --[[Joey]] 
+
+*   The modified time of a file is what that file was last updated in the repository
+
+    > Almost right, the modified time is actually taken from the
+    > modification time of the file in disk. --[[Joey]] 
+
+And with a blog, by default, the posts are ordered by creation time, although an option can order them by modified time.
+
+Okay. So this should mean that the times are safe if, for example, I delete my working copy and then clone another one from the bare git repository, or otherwise mess up the creation times and mtimes stored as file metadata on the filesystem.
+
+Do I have it right?
+
+> Some VCS, like git, set the file mtimes to the current time
+> when making a new checkout, so they will be lost if you do that.
+> The creation times can be retrived using the `--getctime` option.
+> I suppose it might be nice if there were a `--getmtime` that pulled
+> true modification times out of the VCS, but I haven't found it a big
+> deal in practice for the last modification times to be updated to the
+> current time when rebuilding a wiki like this. --[[Joey]] 
+>
+> > Thanks for the clarification. I ran some tests of my own to make sure I understand it right, and I'm satisfied
+> > that the order of posts in my blog can be retrieved from the VCS using the `--getctime` option, at least if I
+> > choose to order my posts by creation time rather than modification time. But I now know that I can't rely on
+> > page modification times in ikiwiki as these can be lost permanently.
+> >
+> > I would suggest that there should at least be a `--getmtime` option like you describe, and perhaps that 
+> > `--getctime` and `--getmtime` be _on by default_. In my opinion the creation times and modification times of 
+> > pages in ikiwiki are part of the user's content and are important to protect, because the user may be relying 
+> > on them, especially if they use blogging or lists of recently modified pages, etc. Right now the modification
+> > times can be lost permanently.
+> >
+> > Is there a typo in the description of `--getctime` in the man page?
+> >
+> > > --getctime
+> > > Pull  **last  changed  time**  for each new page out of the revision
+> > > control system. This rarely used option provides a  way  to  get
+> > > the real creation times of items in weblogs, such as when build‐
+> > > ing a wiki from a new Subversion checkout. It is unoptimised and
+> > > quite  slow. It is best used with --rebuild, to force ikiwiki to
+> > > get the ctime for all pages.
+> >
+> > Surely it is not the _last changed time_ but the _first seen time_ of each page that is pulled out of the VCS?
+> > If the aim is to get the real creation times of items in weblogs, then the last times that the items were
+> > changed in the VCS is not going to help. -- [[seanh]]
+>>> Typo, fixed. --[[Joey]] 
+
+> > > If you want to preserve the date of a page, the best way to do it is to
+> > > use [[ikiwiki/directive/meta]] date="foo". This will survive checkouts,
+> > > VCS migrations, etc. -- [[Jon]]
+> > >
+> > > > That's a good tip Jon. That would also survive renaming a page by renaming its mdwn file, which would 
+> > > > normally lose the times also. (And in that case I think both times are irretrievable, even by 
+> > > > `--getctime`). I might start using a simple script to make blog posts that creates a file for
+> > > > me, puts today's date in the file as a meta, and opens the file in my editor.  -- [[seanh]]
+
+>>>>> I use a script that does that and also sets up templates and tags
+>>>>> for a new item:
+
+    #!/bin/sh
+    set -u
+    set -e
+
+    if [ $# -ne 1 ]; then
+        echo usage: $0 pagename >&2
+        exit 1
+    fi
+
+    pagename="$1"
+
+    if [ -e "$pagename" ]; then
+        echo error: "$pagename" exists >&2
+            exit 1
+    fi
+
+    date=$(date)
+    echo '\[[!template id=draft]]' >> "$pagename"
+    echo "\[[!meta date=\"$date\"]]" >> "$pagename"
+    echo "\[[!tag draft]]" >> "$pagename"
+    git add "$pagename"
+    $EDITOR "$pagename"
+
+>>>>> -- [[Jon]]
diff --git a/doc/forum/How_to_fix___34__does_not_map_to_Unicode__34___errors__63__.mdwn b/doc/forum/How_to_fix___34__does_not_map_to_Unicode__34___errors__63__.mdwn
new file mode 100644
index 000000000..0b3895357
--- /dev/null
+++ b/doc/forum/How_to_fix___34__does_not_map_to_Unicode__34___errors__63__.mdwn
@@ -0,0 +1,20 @@
+I'm getting a number of errors like this when running ikiwiki:
+
+    utf8 "\xA2" does not map to Unicode at /usr/local/share/perl/5.10.0/IkiWiki.pm line 739, <$in> chunk 1.
+
+I think it's because some of my files contain non-utf8, non-unicode, or somehow bad characters in them, probably fancy quotes and the like that have been copy-and-pasted from my web browser. The problem is that I have hundreds of files, I transferred them all over from pyblosxom to ikiwiki at once, and the error message doesn't tell me which file the error comes from. How can I fix this?
+
+Thanks  
+-- seanh
+
+> Unfortunatly, these messages are logged by perl so there's no way to add
+> a filename to them.
+> 
+> If you run the build in --verbose mode, you should see which page ikiwiki
+> is working on, and unless it inlines some other page, you can be pretty
+> sure that page contains invalid utf-8 if the message is then printed.
+>
+> Another option is to use the `isutf8` program from 
+> moreutils](http://kitenet.net/~joey/code/moreutils/),
+> and run it on each file, it will tell you the line number
+> and character position that is invalid. --[[Joey]] 
diff --git a/doc/forum/Is_there_a_pagespec_for_creation_dates_relative_to_today__63__.mdwn b/doc/forum/Is_there_a_pagespec_for_creation_dates_relative_to_today__63__.mdwn
index e88400cd4..53c70e50a 100644
--- a/doc/forum/Is_there_a_pagespec_for_creation_dates_relative_to_today__63__.mdwn
+++ b/doc/forum/Is_there_a_pagespec_for_creation_dates_relative_to_today__63__.mdwn
@@ -17,6 +17,10 @@ Paul
 > somehow figure out that pages matched by it yesterday no longer match,
 > and that pages containing the pagespec need to be rebuilt. Which means
 > you'd also need a cron job.
->
+
+>> Thank you for the explanation.
+
 > I suspect what you're trying to accomplish is
 > [[todo/tagging_with_a_publication_date]]? --[[Joey]]
+
+>> Yeah, something like that. Thanks! --[[PaulePanter]]
diff --git a/doc/forum/Migrating_old_repository_to_new_ikiwiki_system__63__.mdwn b/doc/forum/Migrating_old_repository_to_new_ikiwiki_system__63__.mdwn
new file mode 100644
index 000000000..fe67e6aba
--- /dev/null
+++ b/doc/forum/Migrating_old_repository_to_new_ikiwiki_system__63__.mdwn
@@ -0,0 +1,58 @@
+How do I setup an old ikiwiki repository on a new system?
+
+I have a git repository from an old ikiwiki system.
+I reformatted that hard drive, but saved the repository.
+
+I copied it the repository to my new system, which is now the "master" host.
+I installed ikiwiki on the new system.
+
+How do I set up an ikiwiki system using a pre-existing repository (instead of creating a new one)? --[[JosephTurian]]
+
+> Well, if you have:
+> * A git repository of the wiki
+> * A setup file for the wiki
+>
+> Then you should:
+> 
+> 1. Manually set up a bare git repository, and push
+>    your backed up repository to it.
+> 2. `git clone` from the bare git repository to 
+>    recreate the ikiwiki srcdir
+> 3. `git clone` from the bare git repository a second time,
+>    to create a checkout you can manually edit (optional)
+> 4. run `ikiwiki --getctime --setup your.setup`
+>    The getctime will ensure page creation times are accurate
+>    by putting the info out of the git history,
+>    and only needs to be done once.
+>
+> If you preserved your repository, but not the setup file,
+> the easiest way to make one is probably to run
+> `ikiwiki -dumpsetup` and edit the setup file. --[[Joey]] 
+
+> > I get the following errors after running ikiwiki setup:
+
+    shortcut plugin will not work without shortcuts.mdwn
+    shortcut plugin will not work without shortcuts.mdwn
+    successfully generated /home/turian/public_html/iki/ikiwiki.cgi
+    shortcut plugin will not work without shortcuts.mdwn
+    successfully generated /home/turian/repos/iki.git/hooks/post-update
+    Can't stat /usr/share/ikiwiki/basewiki/../javascript: No such file or directory
+     at /home/turian/utils//lib/perl5/site_perl/5.8.8//IkiWiki/Plugin/autoindex.pm line 60
+    Can't stat /usr/share/ikiwiki/basewiki/../smiley: No such file or directory
+     at /home/turian/utils//lib/perl5/site_perl/5.8.8//IkiWiki/Plugin/autoindex.pm line 60
+    Can't stat /usr/share/ikiwiki/basewiki: No such file or directory
+     at /home/turian/utils//lib/perl5/site_perl/5.8.8//IkiWiki/Plugin/autoindex.pm line 60
+    Can't stat /usr/share/ikiwiki/basewiki/../javascript: No such file or directory
+     at /home/turian/utils//lib/perl5/site_perl/5.8.8//IkiWiki/Render.pm line 320
+    Can't stat /usr/share/ikiwiki/basewiki/../smiley: No such file or directory
+     at /home/turian/utils//lib/perl5/site_perl/5.8.8//IkiWiki/Render.pm line 320
+    Can't stat /usr/share/ikiwiki/basewiki: No such file or directory
+     at /home/turian/utils//lib/perl5/site_perl/5.8.8//IkiWiki/Render.pm line 320
+    internal error: smileys.mdwn cannot be found in /home/turian/iki or underlay
+
+> > How do I resolve these errors? I have my PERL5LIB location set correctly.
+
+>>> Well, that's unrelated to the original question, but
+>>> I guess you should set `underlaydir` in your setup file to
+>>> point to whereever you have installed the basewiki directory.
+>>> --[[Joey]] 
diff --git a/doc/forum/What_is_wrong_with_my_recentchange_page___63__.mdwn b/doc/forum/What_is_wrong_with_my_recentchange_page___63__.mdwn
new file mode 100644
index 000000000..4914cba59
--- /dev/null
+++ b/doc/forum/What_is_wrong_with_my_recentchange_page___63__.mdwn
@@ -0,0 +1,13 @@
+Hi again,
+
+I have finally finished my setup *but* I still have a problem with RecentChanges page.
+
+Can somebody check it for me at [http://maillard.mobi/~xma/wiki/recentchanges/] and tell what is wrong ?
+
+Thank you.
+
+--[[xma]]
+
+> Looks to me like you don't have the meta plugin enabled. --[[Joey]]
+
+> > You are right. Now all is ok. --[[xma]]
diff --git a/doc/forum/chinese_character_problem.mdwn b/doc/forum/chinese_character_problem.mdwn
new file mode 100644
index 000000000..aea55703f
--- /dev/null
+++ b/doc/forum/chinese_character_problem.mdwn
@@ -0,0 +1,21 @@
+just finished setting up ikiwiki..
+
+I can type chinese, save and display it correctly in ikiwiki for the first time. However, when i try to edit the page again, the chinese character in the form is unrecognizable. you can see it here <http://ikiwiki.perlchina.org/>
+
+I am using the latest ikiwiki(manually installed as non-root user) and CGI::FormBuilder(3.0501) on Debian 4.0
+
+这个没问题 it is not a problem on ikiwiki website though.
+
+Thanks.
+
+
+> Is your system perhaps not configured with a utf-8 default locale? Or ikiwiki not configured to use it?
+> Make sure that some utf-8 locale is enabled (in /etc/locale.gen on Debian for example) and try setting `locale` in your > ikiwiki setup file. --[[Joey]]
+
+I have installed locales-all and locale -a shows that zh_CN.UTF-8 is installed(there is no /etc/local.gen file though). then I enabled this line "locale => 'zh_CN.UTF-8'" in my wiki setup and -setup again. but that generated lots error messages "Missing constant domain at (eval 30) line 3"
+
+sorry being a n00b on this thing  what else can I do?
+
+> See [[bugs/Missing_constant_domain_at_IkiWiki.pm_line_842]].
+> Looks like you need to upgrade to a newer version of 
+> [[!cpan Locale::gettext]] --[[Joey]] 
diff --git a/doc/forum/discussion.mdwn b/doc/forum/discussion.mdwn
new file mode 100644
index 000000000..93cf4656e
--- /dev/null
+++ b/doc/forum/discussion.mdwn
@@ -0,0 +1,7 @@
+I like the idea of this forum heirarchy -- but I think a map would be clearer than inlining the sub-pages. -- [[users/Jon]]
+
+> The easier way to accomplish this is to set archive=yes in the inline.
+> Switching to archive view can be useful when there are a lot of long
+> posts and people tend to want to scan by title to find interesting ones
+> and not necessarily read them all, which probably fits this forum pretty
+> well --[[Joey]]
diff --git a/doc/forum/ikiwiki__39__s_notion_of_time.mdwn b/doc/forum/ikiwiki__39__s_notion_of_time.mdwn
new file mode 100644
index 000000000..ee564fcc9
--- /dev/null
+++ b/doc/forum/ikiwiki__39__s_notion_of_time.mdwn
@@ -0,0 +1,35 @@
+I'm having some difficulties with ikiwiki's notion of time.
+
+For (regular) pages, the *last edited* date is the one where the file
+was indeed last modified according to the file system information.
+The *created* date (commented out in the HTML) is, at least for
+`--getctime` operation, the date, where the file was last registered
+as changed with the VCS.
+
+Now, at least with git, the thing is that when you're checking out files,
+they'll get the checkout-time's current time stamp.
+
+What I strive for is the following: *created* be the date when the file
+(under its current name) was *first* registered with the VCS (which is
+more logical in my opinion), and *last edited* be the date the file was
+last registered as changed with the VCS, which is the current
+`--getctime` *created* date.
+
+This means that I can build the HTML files from different checkouts of the
+VCS and they won't differ in the time stamps they contain in the HTML.
+
+What is the rationale for ikiwiki's current behavior with respect to these
+time stamps?
+
+--[[tschwinge]]
+
+> Presumably it's the authors of the git and mercurial backends
+> not understanding the documentation for `rcs_getctime`,
+> which states:
+> 
+>>This is used to get the page creation time for a file from the RCS, by
+>>looking it up in the history.
+> 
+> I've fixed both broken implementations to correctly look
+> up the first, not the last, commit. Other VCS do not seem
+> to have the problem. --[[Joey]] 
diff --git a/doc/forum/managing_todo_lists.mdwn b/doc/forum/managing_todo_lists.mdwn
new file mode 100644
index 000000000..0a69af805
--- /dev/null
+++ b/doc/forum/managing_todo_lists.mdwn
@@ -0,0 +1,44 @@
+I keep some TODO lists on ikiwiki pages. I'm half-tempted to write a plugin
+to make ticking items off and adding items easier via the web interface. I'm
+aware though that this is not really what ikiwiki is designed for. Would
+anyone else find this useful? -- [[users/jon]]
+
+----
+
+My subsequent thoughts about how to approach this are two-fold.
+
+Firstly, a filetype for todo lists, probably OPML, but I haven't looked to see
+if there is something more suitable. A plugin that converts this source into a
+traditional page output, i.e. a DOM tree of ul or ol and li elements.
+
+Secondly, some magic javascript to make editing the list via the web page 
+more interactive: add items, strike items out, reorder items etc., without
+round-tripping to the cgi for each operation.
+
+Finally, a mechanism whereby the changes made to the page live can be
+committed back to the repository:
+
+ * ...perhaps the input → output conversion is reversible, and the HTML DOM
+   representing the list can be transformed back into the source and submitted
+   to the cgi like a regular edit: issues include the result of other
+   postprocessing: templates, wikilinks, etc.
+ * perhaps an embedded copy of the source is included in the output and the
+   javascript operates on that in tandem with the static copy
+   * perhaps the "output" is generated live by the JS at view time (with maybe
+     a plugin-generated rendered output for non JS environments)
+
+I envisage a button called "commit changes" appearing once some changes are
+made that submits the changes to the CGI, perhaps via a back channel. I'm not
+sure how to handle embeds or challenges from the CGI such as a login challenge
+(maybe the back channel would not be necessary in the first cut).
+
+> You might look at the [[plugins/hnb]] plugin. HNB supports checklists.
+> There's not a fancy web interface, but the hnb command-line program can
+> be used to edit them. --[[Joey]] 
+
+>> thanks - I'll give it a look. I spent a few hours writing some javascript to manipulate a ul/li DOM tree in an outliner-fashion the other day. I might be able to join the puzzle pieces together sometime. [[Jon]]
+
+a solution for this could be similar to a solution for [[todo/structured page data]], as todo lists are definitely a form of structured data. (in both cases, the page's current content is rendered into a html form, whose result is then saved as the page's new contents) --[[chrysn]]
+
+> Thanks for the link: yup, there's definitely some common ground there.
+> -- [[Jon]]
diff --git a/doc/forum/multi-user_setup_of_ikiwiki__44___gitosis_and_apache2_in_Debian_Sid.mdwn b/doc/forum/multi-user_setup_of_ikiwiki__44___gitosis_and_apache2_in_Debian_Sid.mdwn
index d42a5c704..fa8b5010e 100644
--- a/doc/forum/multi-user_setup_of_ikiwiki__44___gitosis_and_apache2_in_Debian_Sid.mdwn
+++ b/doc/forum/multi-user_setup_of_ikiwiki__44___gitosis_and_apache2_in_Debian_Sid.mdwn
@@ -43,7 +43,7 @@ In the end, I did the following. I created a directory /srv/ikiwiki/ which is ow
 
 ## cgi_wrapper
 
-I do not understand those wrappers completely. The cgi is a script, which can be called by a webserver, e. g. [[Apache_2|/tips/apache_cgi]]. But www-data is normally not allowed to write to the source directory (which is owned by gitosis or push to the repository). Therefore it should be run as the user gitosis. And because cgi scripts can not be made suid, I wrapper (in this case a C program) is created (cgi\_wrapper) which can be made suid and therefore be run as the user gitosis. Is this correct?
+I do not understand those wrappers completely. The cgi is a script, which can be called by a webserver, e. g. [[Apache_2|/tips/dot_cgi]]. But www-data is normally not allowed to write to the source directory (which is owned by gitosis or push to the repository). Therefore it should be run as the user gitosis. And because cgi scripts can not be made suid, I wrapper (in this case a C program) is created (cgi\_wrapper) which can be made suid and therefore be run as the user gitosis. Is this correct?
 
 > It seems to me like you understand the wrapper pretty well. It's main reson to exist is to safely be suid, yes.
 
diff --git a/doc/forum/usedirs___38___indexpages_using_problem.mdwn b/doc/forum/usedirs___38___indexpages_using_problem.mdwn
new file mode 100644
index 000000000..05c85e281
--- /dev/null
+++ b/doc/forum/usedirs___38___indexpages_using_problem.mdwn
@@ -0,0 +1,17 @@
+My ikiwiki setup file configed like:
+
+	usedirs => 0,
+	indexpages => 1,
+
+I create a directory and some .mdwn source file  /Whatis/index.mdwn and /Whatis/OSS.mdwn . The html file ikiwiki generated is
+/Whatis/index.html and /Whatis/OSS.html . 
+
+But in the page [OSS.html](http://atoz.org.cn/Whatis/OSS.html) , the auto generated link (on the page top)
+to “Whatis” is /Whatis.html file , not to /Whatis/index.html. So the link to “Whatis” is fail .
+
+Is it a bug , and how can I do for that ?
+
+> I suggest that you name your page `Whatis.mdwn`, and not
+> `Whatis/index.mdwn`. That will make ikiwiki's links work,
+> and allows you to link to the `Whatis` page by that name.
+> --[[Joey]] 
diff --git a/doc/forum/wiki_name_in_page_titles.mdwn b/doc/forum/wiki_name_in_page_titles.mdwn
new file mode 100644
index 000000000..01ff8d817
--- /dev/null
+++ b/doc/forum/wiki_name_in_page_titles.mdwn
@@ -0,0 +1,26 @@
+I'd like to have the wiki name appear in page titles as in "WikiName:
+Page Title."  If I use `<TMPL_VAR WIKINAME>: <TMPL_VAR TITLE>` in the
+template this works for all pages except the index page itself which
+will have title "WikiName: WikiName" as its title.  Does anyone know
+of a template-based solution to this or do I need to write a plugin
+that provides a `IS_HOMEPAGE` template variable? --[[JasonBlevins]]
+
+> Hmm, one way to work around this is to put a meta title directive on the
+> index page. Then TITLE will be that, rather than WIKINAME, and your
+> template should work. --[[Joey]]
+
+>> I ended up writing a [path][] plugin since I had some other
+>> path-specific conditional things to include in my templates.
+>>
+>> So now I can do things like this:
+>>
+>>     <title>
+>>     <TMPL_VAR WIKINAME><TMPL_UNLESS IS_HOMEPAGE>: <TMPL_VAR TITLE></TMPL_UNLESS>
+>>     </title>
+>>
+>> But also more complicated path-specific conditionals like
+>> `IN_DIR_SUBDIR` to indicate subpages of `/dir/subdir/`.  I've got a
+>> few other small plugins brewing so I'll try to put up some contrib
+>> pages for them soon. --[[JasonBlevins]]
+
+[path]: http://code.jblevins.org/ikiwiki/plugins.git/plain/path.pm