diff options
Diffstat (limited to 'doc')
207 files changed, 3702 insertions, 395 deletions
diff --git a/doc/bugs/404_plugin_and_lighttpd.mdwn b/doc/bugs/404_plugin_and_lighttpd.mdwn new file mode 100644 index 000000000..ffbad8add --- /dev/null +++ b/doc/bugs/404_plugin_and_lighttpd.mdwn @@ -0,0 +1,35 @@ +Lighttpd apparently sets REDIRECT_STATUS=200 for the server.error-handler-404 page. This breaks the 404 plugin which checks this variable for 404 before processing the URI. It also doesn't seem to set REDIRECT_URL. + +I was able to fix my server to check the REQUEST_URI for ikiwiki.cgi and to continue processing if it was not found, passing $ENV{SEVER_NAME} . $ENV{REQUEST_URI} as the first parameter to cgi_page_from_404. However, my perl is terrible and I just made it work rather than figuring out exactly what to do to get it to work on both lighttpd and apache. + +This is with lighttpd 1.4.19 on Debian. + +> /cgi-bin/ikiwiki.cgi?do=goto also provides redirection in the same way, +> if that's any help? You might need to set the lighttpd 404 handler to +> that, then compose REDIRECT_URL from other variables if necessary. +> +> I originally wrote the plugin for Apache; [[weakish]] contributed the +> lighttpd docs and might know more about how to make it work there. +> --[[smcv]] + +>> As I said, I got it working for me, but somebody who knows perl should probably look at it with the aim of making it work for everyone. +>> I considered having lighttpd construct a proper url for the 404 redirect itself, but I don't know if it can do something like that or not. +>> For what it's worth, here's the change I made to the module: + + sub cgi ($) { + my $cgi=shift; + if ($ENV{REQUEST_URI} !~ /ikiwiki\.cgi/) { + my $page = cgi_page_from_404( + Encode::decode_utf8($ENV{SERVER_NAME} . $ENV{REQUEST_URI}), + $config{url}, $config{usedirs}); + IkiWiki::Plugin::goto::cgi_goto($cgi, $page); + } + + # if (exists $ENV{REDIRECT_STATUS} && + # $ENV{REDIRECT_STATUS} eq '404') { + # my $page = cgi_page_from_404( + # Encode::decode_utf8($ENV{REDIRECT_URL}), + # $config{url}, $config{usedirs}); + # IkiWiki::Plugin::goto::cgi_goto($cgi, $page); + # } + } diff --git a/doc/bugs/Comments_dissapeared.mdwn b/doc/bugs/Comments_dissapeared.mdwn new file mode 100644 index 000000000..7ff1a012f --- /dev/null +++ b/doc/bugs/Comments_dissapeared.mdwn @@ -0,0 +1,35 @@ +Although I have comments enabled and I have been using them successfully for ages now, I've come to notice that they have stopped working in the last week or two. + +I am running version 3.20100312 with the following configuration: + +<http://static.natalian.org/2010-03-27/natalian.txt> + +In my (HTML5 modified page.tmpl) it doesn't seem to enter the "TMPL_IF COMMENTS" block anymore. I tried the stock page.tmpl and they didn't seem to work either, so the variable name hasn't changed has it? + +Any other ideas? With thanks, + + comments_pagespec => 'archives/* and !*/Discussion', + +> Your setup file only allows comments to pages under archives. That +> seems unlikely to be right, so I guess it is causing your problem. +> --[[Joey]] + +That's the only place where I want comments. <http://natalian.org/archives/> +Has the pagespec changed? Is it `archives/*/*` or something like that? + +It worked just fine with this configuration. I swear I have not modified it. :) -- [[Kai Hendry]] + +> No changes that I can think of. 'archives/*' will match *all* pages under +> archives. Anyway, I can see in your site's rss feed that comments are +> enabled for posts, since they have comments tags there. And +> in fact I see comments on eg +> <http://natalian.org/archives/2010/03/25/BBC_News_complaints/>. +> +> So I suspect you have simply not rebuilt your wiki after making some +> change that fixed the comments, and so only newer pages are getting them. +> --[[Joey]] + +I have tried rebuilding on my squeeze system and still comments don't appear. Any clues how to debug this? +<http://natalian.org/comments/> + +I was worried is was due to a time skew problem I was experiencing on my VPS in the last month, though the time is right now and still comments do not appear on blog posts like <http://natalian.org/archives/2010/03/25/BBC_News_complaints/> diff --git a/doc/bugs/Error:_Your_login_session_has_expired._.mdwn b/doc/bugs/Error:_Your_login_session_has_expired._.mdwn index 046d6e10d..b993cd8e7 100644 --- a/doc/bugs/Error:_Your_login_session_has_expired._.mdwn +++ b/doc/bugs/Error:_Your_login_session_has_expired._.mdwn @@ -41,4 +41,6 @@ Whilst trying to edit http://hugh.vm.bytemark.co.uk/ikiwiki.cgi via OpenID. Any Thanks for you excellent analysis. The bug was due to old pre-3.0 **templates** laying about. After deleting them, ikiwiki defaults to its own templates. Clever. :-) +Great, this saved me big time! It is a google 1st hit. I had the same with accidentally using old templates. Thanks! --[[cstamas]] + [[bugs/done]] diff --git a/doc/bugs/Exception:_Unknown_function___96__this__39___.mdwn b/doc/bugs/Exception:_Unknown_function___96__this__39___.mdwn new file mode 100644 index 000000000..189ba740f --- /dev/null +++ b/doc/bugs/Exception:_Unknown_function___96__this__39___.mdwn @@ -0,0 +1,70 @@ +I'm very excited to try out ikiwiki, since it should fit my purposes extremely well, but I'm having trouble with the search plugin. I'm pretty sure that right after I installed ikiwiki and needed dependencies, the search plugin was working fine. However, now when I try to use search, I get "Exception: Unknown function `this'" error on a blank page. I'm not sure how I should go about debugging this issue - my server's (I use Lighttpd 1.4.22) error log has no mention of the exception and there's nothing in /var/log/syslog either. + +What might be causing this exception and how I might go about debugging exceptions? + +> Appears to be coming from your xapian omega cgi binary. If you +> run `strings /usr/lib/cgi-bin/omega/omega` you can see it has +> "Exception: " in it, and I have found some similar (but not identical) +> error messages from xapian in a web search. +> +> I don´t know what to suggest, other than upgrade/downgrade/reinstall +> xapian-omega, and contacting the xapian developers for debugging. +> You could try rebuilding your wiki in case it is somehow +> caused by a problem with the xapian database. Failing everything, you +> could switch to [[google_search_plugin|plugins/google]]. --[[Joey]] + +>> Thanks, Joey. With your help I was able to figure out what was wrong. It's a fun little bug (or feature): the title of my wiki had string `$this` in title and that's what was causing the omega binary to choke. My wiki's title was inserted without escaping into the query template used by omega. Omega treated `$this` in the title as a function name and threw an exception because no such function was defined. To avoid this behavior, I used an html entity in the title, so `$this` became `$this`. I don't think that the wiki title should be inserted into the template without escaping - it can produce an error that's not trivial to debug. If users want to modify the html in the title, they should be editing respective templates, not typing html in the wiki title input. What do you think? --[[dkobozev]] + +>>> Sounds like a bug in omega, and one that probably would affect other +>>> users of omega too. Ikiwiki could work around it by pre-escaping +>>> data before passing it to xapian. I have not quite managed to reproduce it though; +>>> tried setting a page title to '$this' and 'foo $this'. +>>> That's with version 1.0.18 of omega. +>>> --[[Joey]] + +>>>> I tried it with both omega 1.0.13 and omega 1.0.18 and the issue is present in both. If I view the contents of {$srcdir}/.ikiwiki/xapian/templates/query, I can see that the wiki title is inserted verbatim and there are calls to `$setmap`, `$set` and `$def` etc in the template. --[[dkobozev]] + +>>>>> I don't see how that's relevant. It would help if you showed me +>>>>> exactly something that could be inserted into a page to cause the +>>>>> problem. --[[Joey]] + +>>>>>> Correct me if I'm wrong: ikiwiki generates an Omega template from its own templates, such as searchquery.tmpl and puts it into {$srcdir}/.ikiwiki/xapian/templates/query. Omega has its own template syntax, where function names are prefixed with dollar signs (`$`). So, when I call my wiki `$foobar`, ikiwiki generates an Omega template that looks like this snippet: + + <div id="container"> + <div class="pageheader"> + <div class="header"> + <span> + <a href="http://example.com">$foobar</ a>/search + </span> + </div> + </div> <!-- .pageheader --> + + <div id="content"> + $setmap{prefix,title,S} + $setmap{prefix,link,XLINK} + $set{thousand,$.}$set{decimal,.}$setmap{BN,,Any Country,uk,England,fr,France} + ${ + $def{PREV, + $if{$ne{$topdoc,0},<INPUT TYPE=image NAME="<" ALT="<" + SRC="/images/xapian-omega/prev.png" BORDER=0 HEIGHT=30 WIDTH=30>, + <IMG ALT="" SRC="/images/xapian-omega/prevoff.png" HEIGHT=30 WIDTH=30>} + +>>>>>> So `$foobar` clashes with Omega's template tags. Does this help? + +>>>>>>> Ahh. I had somehow gotten it into my head that you were talking +>>>>>>> about the title of a single page, not of the whole wiki. But +>>>>>>> you were clear all along it was the wiki title. Sorry for +>>>>>>> misunderstanding. I've put in a complete fix for this problem. +>>>>>>> if this was in [[bugs]], I'd close it. :) --[[Joey]] + +>>>>>>>> Rather than escaping `$` as an HTML entity, it would be more natural +>>>>>>>> to escape it as `$$` (since you are escaping it for Omega, not for +>>>>>>>> the web browser. +>>>>>>>> +>>>>>>>> Also if ikiwiki can put arbitrary text inside the parameters of an +>>>>>>>> OmegaScript command, you should also escape `{`, `}` and `,` as +>>>>>>>> `$(`, `$)` and `$.`. It's only necessary to do so inside the +>>>>>>>> parameters of a command, but it will work and be easier to escape +>>>>>>>> them in any substituted text. --OllyBetts + +[[done]] diff --git a/doc/bugs/External_links_with_Creole.mdwn b/doc/bugs/External_links_with_Creole.mdwn new file mode 100644 index 000000000..3d800b04e --- /dev/null +++ b/doc/bugs/External_links_with_Creole.mdwn @@ -0,0 +1,3 @@ +When using Creole for markup, creating an external link appears to be impossible. Neither \[[Outside URL|http://example.com]] nor <<http://example.com>> nor \[Outside URL]\(http://example.com) work. The first gets rendered as a broken WikiLink, the second get eaten and the last is not parsed in anyway so you end up with that exact text in your page. + +I'd have made this as a Creole page as a practical demonstration, but that doesn't seem possible here. Here's a page with an example: <https://www.icanttype.org//demo/CreoleExternalLinks> diff --git a/doc/bugs/Tab_delimited_tables_don__39__t_work.mdwn b/doc/bugs/Tab_delimited_tables_don__39__t_work.mdwn new file mode 100644 index 000000000..39d57a4fe --- /dev/null +++ b/doc/bugs/Tab_delimited_tables_don__39__t_work.mdwn @@ -0,0 +1,22 @@ +Table directive should support tab-delimited data, especially important since this is the format you will get if copy/pasting from an HTML table or spreadsheet (Gnumeric, OO Calc, Excel). Test case which fails: + +[[!table format=dsv delimiter="\t" data=""" +1 2 +2 4 +"""]] + +> They do work, but C-style backslash escapes aren't recognised, +> so the syntax `delimiter="\t"` (as in your test case) looks +> for the literal string `\t`. Replacing `\t` with a literal +> tab character makes it work - here's a test (I changed the data +> to make the table layout more obvious): +> +> [[!table format=dsv delimiter=" " data=""" +left 2 +2 right +alpha beta +"""]] +> +> So, I think this can be considered [[not_a_bug|done]]? --[[smcv]] + +>> I've clarified the documentation. --[[smcv]] diff --git a/doc/bugs/anonok_vs._httpauth.mdwn b/doc/bugs/anonok_vs._httpauth.mdwn index 0a62164cb..bff37e18b 100644 --- a/doc/bugs/anonok_vs._httpauth.mdwn +++ b/doc/bugs/anonok_vs._httpauth.mdwn @@ -58,3 +58,61 @@ and a whitelist of OpenIDs in `locked_pages`...) >> On reflection, I've stopped being bothered by the >> redirect-to-signin-page approach. (It only needs to happen once per >> browser session, anyway.) Can we try that? --[[schmonz]] + +Here is an attempt. With this httpauth will only redirect to the +`cgiauth_url` when a page is edited, and it will defer to other plugins +like anonok first. I have not tested this. --[[Joey]] + +<pre> +diff --git a/IkiWiki/Plugin/httpauth.pm b/IkiWiki/Plugin/httpauth.pm +index 127c321..a18f8ca 100644 +--- a/IkiWiki/Plugin/httpauth.pm ++++ b/IkiWiki/Plugin/httpauth.pm +@@ -9,6 +9,8 @@ use IkiWiki 3.00; + sub import { + hook(type => "getsetup", id => "httpauth", call => \&getsetup); + hook(type => "auth", id => "httpauth", call => \&auth); ++ hook(type => "canedit", id => "httpauth", call => \&canedit, ++ last => 1); + } + + sub getsetup () { +@@ -33,9 +35,21 @@ sub auth ($$) { + if (defined $cgi->remote_user()) { + $session->param("name", $cgi->remote_user()); + } +- elsif (defined $config{cgiauthurl}) { +- IkiWiki::redirect($cgi, $config{cgiauthurl}.'?'.$cgi->query_string()); +- exit; ++} ++ ++sub canedit ($$$) { ++ my $page=shift; ++ my $cgi=shift; ++ my $session=shift; ++ ++ if (! defined $cgi->remote_user() && defined $config{cgiauthurl}) { ++ return sub { ++ IkiWiki::redirect($cgi, $config{cgiauthurl}.'?'.$cgi->query_string()); ++ exit; ++ }; ++ } ++ else { ++ return undef; + } + } + +</pre> + +> With `anonok` enabled, this works for anonymous editing of an +> existing Discussion page. auth is still needed to create one. --[[schmonz]] + +>> Refreshed above patch to fix that. --[[Joey]] + +>> Remaining issue: This patch will work with anonok, but not openid or +>> passwordauth, both of which want to display a login page at the same +>> time that httpauth is redirecting to the cgiauthurl. As mentioned above, +>> the only way to deal with that would be to add a link to the signin page +>> that does the httpauth signin. --[[Joey]] + +>>> That's dealt with in final version. [[done]] --[[Joey]] diff --git a/doc/bugs/barfs_on_recentchange_entry_for_a_change_removing_an_invalid_pagespec.mdwn b/doc/bugs/barfs_on_recentchange_entry_for_a_change_removing_an_invalid_pagespec.mdwn index 42e6b9e27..c3cbff43e 100644 --- a/doc/bugs/barfs_on_recentchange_entry_for_a_change_removing_an_invalid_pagespec.mdwn +++ b/doc/bugs/barfs_on_recentchange_entry_for_a_change_removing_an_invalid_pagespec.mdwn @@ -39,3 +39,6 @@ a year ago in September 2007. > ikiwiki. (Doesn't quite seem to be version 2.53.x either) Try with a current > version, and see if you can send me a source tree that can reproduce the > problem? --[[Joey]] + +Did not hear back, so calling this [[done]], unless I hear differently. +--[[Joey]] diff --git a/doc/bugs/bzr_2.0_breaks_bzr_plugin.mdwn b/doc/bugs/bzr_2.0_breaks_bzr_plugin.mdwn new file mode 100644 index 000000000..39500af20 --- /dev/null +++ b/doc/bugs/bzr_2.0_breaks_bzr_plugin.mdwn @@ -0,0 +1,87 @@ +Version 2.0 of bzr seems to break the bzr plugin. + +I traced this to the bzr_log method in the plugin, and patching that seems to fix it. The plugin just needs to parse the input little bit differently. +--liw + +> Patch applied, [[done]] (but, it would be good if it could be tested with +> an older bzr, and it's a pity bzr's human-targeted log has to be parsed, +> I assume there is no machine-targeted version?) --[[Joey]] + + From fb897114124e627fd3acf5af8e784c9a77419a81 Mon Sep 17 00:00:00 2001 + From: Lars Wirzenius <liw@liw.fi> + Date: Sun, 4 Apr 2010 21:05:07 +1200 + Subject: [PATCH] Fix bzr plugin to work with bzr 2.0. + + The output of "bzr log" seems to have changed a bit, so we change the + parsing accordingly. This has not been tested with earlier versions of + bzr. + + Several problems seemed to occur, all in the bzr_log subroutine: + + 1. The @infos list would contain an empty hash, which would confuse the + rest of the program. + 2. This was because bzr_log would push an empty anonymous hash to the + list whenever it thought a new record would start. + 3. However, a new record marker (now?) also happens at th end of bzr log + output. + 4. Now we collect the record to a hash that gets pushed to the list only + if it is not empty. + 5. Also, sometimes bzr log outputs "revno: 1234 [merge]", so we catch only + the revision number. + 6. Finally, there may be non-headers at the of the output, so we ignore + those. + --- + IkiWiki/Plugin/bzr.pm | 23 ++++++++++++++++------- + 1 files changed, 16 insertions(+), 7 deletions(-) + + diff --git a/IkiWiki/Plugin/bzr.pm b/IkiWiki/Plugin/bzr.pm + index 1ffdc23..e813331 100644 + --- a/IkiWiki/Plugin/bzr.pm + +++ b/IkiWiki/Plugin/bzr.pm + @@ -73,28 +73,37 @@ sub bzr_log ($) { + my @infos = (); + my $key = undef; + + + my $hash = {}; + while (<$out>) { + my $line = $_; + my ($value); + if ($line =~ /^message:/) { + $key = "message"; + - $infos[$#infos]{$key} = ""; + + $$hash{$key} = ""; + } + elsif ($line =~ /^(modified|added|renamed|renamed and modified|removed):/) { + $key = "files"; + - unless (defined($infos[$#infos]{$key})) { $infos[$#infos]{$key} = ""; } + + unless (defined($$hash{$key})) { $$hash{$key} = ""; } + } + elsif (defined($key) and $line =~ /^ (.*)/) { + - $infos[$#infos]{$key} .= "$1\n"; + + $$hash{$key} .= "$1\n"; + } + elsif ($line eq "------------------------------------------------------------\n") { + + if (keys %$hash) { + + push (@infos, $hash); + + } + + $hash = {}; + $key = undef; + - push (@infos, {}); + } + - else { + + elsif ($line =~ /: /) { + chomp $line; + - ($key, $value) = split /: +/, $line, 2; + - $infos[$#infos]{$key} = $value; + + if ($line =~ /^revno: (\d+)/) { + + $key = "revno"; + + $value = $1; + + } else { + + ($key, $value) = split /: +/, $line, 2; + + } + + $$hash{$key} = $value; + } + } + close $out; + -- + 1.7.0 diff --git a/doc/bugs/clearenv_not_present_at_FreeBSD_.mdwn b/doc/bugs/clearenv_not_present_at_FreeBSD_.mdwn new file mode 100644 index 000000000..f38c86e03 --- /dev/null +++ b/doc/bugs/clearenv_not_present_at_FreeBSD_.mdwn @@ -0,0 +1,5 @@ +When build wrapper on FreeBSD system, is error occured with clearenv reference. clearenv() das not exists at FreeBSD system, use workaround environ[0]=NULL; +P.S. new git instalation, FreeBSD 7.x + +> `#include <stupid-standards.h>` fixed with nasty ifdefs to handle tcc w/o +> breaking everything else. [[done]] --[[Joey]] diff --git a/doc/bugs/clearenv_not_present_at_FreeBSD_/discussion.mdwn b/doc/bugs/clearenv_not_present_at_FreeBSD_/discussion.mdwn new file mode 100644 index 000000000..713198b61 --- /dev/null +++ b/doc/bugs/clearenv_not_present_at_FreeBSD_/discussion.mdwn @@ -0,0 +1 @@ +Mmmm... i see. But it not setup under FreeBSD without magic manual passes. diff --git a/doc/bugs/depends_simple_mixup.mdwn b/doc/bugs/depends_simple_mixup.mdwn new file mode 100644 index 000000000..2603ff04c --- /dev/null +++ b/doc/bugs/depends_simple_mixup.mdwn @@ -0,0 +1,23 @@ +The [[bugs]] page, at least before I commit this, has a bug at the top that +has been modified to link to done, and ikiwiki's dependency calculations +failed to notice and update the bugs page. Looking at the indexdb, I saw +that the page was not included in the `depends_simple` of the bugs page. + +I was able to replicate the problem locally by starting off with the page +marked done (when it did appear in the bugs page `depends_simple` +(appropriatly as a link dependency, since a change to the page removing the +link would make it match)), then removing the done link. + +At that point, it vanished from `depends_simple`. Presumably because +the main (pagespec) depends for the bugs page now matched it, as a content +dependency. But, it seems to me it should still be listed in +`depends_simple` here. This, I think, is the cause of the bug. + +Then re-add the done link, and the dependency calc code breaks down, +not noticing that bugs dependeded on the page and needs to be updated. + +Ok.. Turns out this was not a problem with the actual influences +calculation or dependency calculation code. Whew! `match_link` +just didn't set the influence correctly when failing. [[fixed|done]] + +--[[Joey]] diff --git a/doc/bugs/filecheck_failing_to_find_files.mdwn b/doc/bugs/filecheck_failing_to_find_files.mdwn new file mode 100644 index 000000000..6501508e4 --- /dev/null +++ b/doc/bugs/filecheck_failing_to_find_files.mdwn @@ -0,0 +1,65 @@ +Using the attachment plugin, when filecheck was checking the mime-type of the attachment before allowing the attachment to be removed, it was returning with an error saying that the mime-type of the file was "unknown" (when the mime-type definitely was known!) + +It turns out that the filecheck plugin couldn't find the file, because it was merely using the $pagesources hash, rather than finding the absolute path of the file in question. + +> I don't understand why the file was not in `%pagesources`. Do you? +> --[[Joey]] + +>> The file *was* in `%pagesources`, but what returns from that is the filename relative to the `srcdir` directory; for example, `foo/bar.gif`. +>> When File::MimeInfo::Magic::magic is given that, it can't find the file. +>> But if it is given `/path/to/srcdir/foo/bar.gif` instead, then it *can* find the file, and returns the mime-type correctly. +>> --[[KathrynAndersen]] + +>>> Ok, so it's not removal specific, can in fact be triggered by using +>>> testpagespec (or really anything besides attachment, which passes +>>> the filename parameter). Nor is it limited to mimetype, all the tests in +>>> filecheck have the problem. --[[Joey]] + +>>>> Alas, not fixed. It seems I was mistaken in some of my assumptions. +>>>> It still happens when attempting to remove attachments. +>>>> With your fix, the `IkiWiki::srcfile` function is only called when the filename is not passed in, but it appears that in the case of removing attachments, the filename IS passed in, but it is the relative filename as mentioned above. Thus, the file is still not found, and the mime-type comes back as unknown. +>>>> The reason my patch worked is because, rather than checking whether a filename was passed in before applying IkiWiki::srcfile to the filename, it checks whether the file can be found, and if it cannot be found, then it applies IkiWiki::srcfile to the filename. +>>>> --[[KathrynAndersen]] + +>>>>> Can you test if this patch fixes that? --[[Joey]] + +>>>>>> Yes, it works! --[[KathrynAndersen]] + +applied && [[done]] + +<pre> +diff --git a/IkiWiki/Plugin/remove.pm b/IkiWiki/Plugin/remove.pm +index f59d026..0fc180f 100644 +--- a/IkiWiki/Plugin/remove.pm ++++ b/IkiWiki/Plugin/remove.pm +@@ -49,7 +49,7 @@ sub check_canremove ($$$) { + # This is sorta overkill, but better safe than sorry. + if (! defined pagetype($pagesources{$page})) { + if (IkiWiki::Plugin::attachment->can("check_canattach")) { +- IkiWiki::Plugin::attachment::check_canattach($session, $page, $file); ++ IkiWiki::Plugin::attachment::check_canattach($session, $page, "$config{srcdir}/$file"); + } + else { + error("removal of attachments is not allowed"); +diff --git a/IkiWiki/Plugin/rename.pm b/IkiWiki/Plugin/rename.pm +index 3908443..1a9da63 100644 +--- a/IkiWiki/Plugin/rename.pm ++++ b/IkiWiki/Plugin/rename.pm +@@ -50,7 +50,7 @@ sub check_canrename ($$$$$$) { + IkiWiki::check_canedit($src, $q, $session); + if ($attachment) { + if (IkiWiki::Plugin::attachment->can("check_canattach")) { +- IkiWiki::Plugin::attachment::check_canattach($session, $src, $srcfile); ++ IkiWiki::Plugin::attachment::check_canattach($session, $src, "$config{srcdir}/$srcfile"); + } + else { + error("renaming of attachments is not allowed"); +@@ -85,7 +85,7 @@ sub check_canrename ($$$$$$) { + if ($attachment) { + # Note that $srcfile is used here, not $destfile, + # because it wants the current file, to check it. +- IkiWiki::Plugin::attachment::check_canattach($session, $dest, $srcfile); ++ IkiWiki::Plugin::attachment::check_canattach($session, $dest, "$config{srcdir}/$srcfile"); + } + } +</pre> diff --git a/doc/bugs/firefox_doesn__39__t_want_to_load_updated_pages_at_ikiwiki.info.mdwn b/doc/bugs/firefox_doesn__39__t_want_to_load_updated_pages_at_ikiwiki.info.mdwn index 46e77a265..558eb90c8 100644 --- a/doc/bugs/firefox_doesn__39__t_want_to_load_updated_pages_at_ikiwiki.info.mdwn +++ b/doc/bugs/firefox_doesn__39__t_want_to_load_updated_pages_at_ikiwiki.info.mdwn @@ -5,3 +5,10 @@ Only explicitly pressing "reload" helps. Is it a bug? I haven't been noticing such problems usually on other sites. --Ivan Z. This remains to be true now, with Epiphany 2.26.3 (Mozilla/5.0 (X11; U; Linux i686; en; rv:1.9.1.4pre) Gecko/20080528 Epiphany/2.22 Firefox/3.5). --Ivan Z. + +> In the most recent ikiwiki release, I added a Cache-Control hack +> explicitly to work around firefox's broken over-caching. +> +> (When I tested epiphany and chromium, neither had firefox's problem.) +> +> [[!tag done]] diff --git a/doc/bugs/ikiwiki-transition_does_not_set_perl_moduels_path_properly.mdwn b/doc/bugs/ikiwiki-transition_does_not_set_perl_moduels_path_properly.mdwn new file mode 100644 index 000000000..b3e87b529 --- /dev/null +++ b/doc/bugs/ikiwiki-transition_does_not_set_perl_moduels_path_properly.mdwn @@ -0,0 +1,17 @@ +When installing ikiwiki the perl module path is setup correctly + + use lib '/usr/local/ikiwiki-3.20100312/share/perl/5.10.0'; + +This is not true for ikiwiki-transition: + + $ PATH=/usr/local/ikiwiki-3.20100312/bin ikiwiki-transition prefix_directives ikiwiki.setup + Can't locate IkiWiki.pm in @INC (@INC contains: /etc/perl /usr/local/lib/perl/5.10.0 + /usr/local/share/perl/5.10.0 /usr/lib/perl5 /usr/share/perl5 /usr/lib/perl/5.10 /usr/share/perl/5.10 /usr/local/lib/site_perl .) + at /usr/local/ikiwiki-3.20100312/bin/ikiwiki-transition line 4. + BEGIN failed--compilation aborted at /usr/local/ikiwiki-3.20100312/bin/ikiwiki-transition line 4. + +The missing line should be added. + +Thanks! + +[[done]] --[[Joey]] diff --git a/doc/bugs/map_sorts_by_pagename_and_not_title_when_show__61__title_is_used.mdwn b/doc/bugs/map_sorts_by_pagename_and_not_title_when_show__61__title_is_used.mdwn index f8e257daf..d12414d55 100644 --- a/doc/bugs/map_sorts_by_pagename_and_not_title_when_show__61__title_is_used.mdwn +++ b/doc/bugs/map_sorts_by_pagename_and_not_title_when_show__61__title_is_used.mdwn @@ -1,4 +1,4 @@ -The [[directive/map]] directive sorty by pagename. That looks kind of odd, when used together with show=title. I would expect it to sort by title then. +The [[ikiwiki/directive/map]] directive sort by pagename. That looks kind of odd, when used together with show=title. I would expect it to sort by title then. > This would be quite hard to fix. Map sorts the pages it displays by page > name, which has the happy effect of making "foo/bar" come after "foo"; @@ -6,3 +6,15 @@ The [[directive/map]] directive sorty by pagename. That looks kind of odd, when > it's located in. If sorting by title, that wouldn't hold. So, map > would have to be effectively totally rewritten, to build up each group > of child pages, and then re-sort those. --[[Joey]] + +>> Ok, you are right, that does would break the tree. This made me think that I do not +>> need to generate a tree for my particular use case just a list, so i thought i could use [[ikiwiki/directive/inline]] instead. +>> This created two new issues: +>> +>> 1. inline also does sort by pagename even when explicitly told to sort by title. +>> +>> 2. I cannot get inline to create a list when the htmltidy plugin is switched on. I have a template which is enclosed in an li tag, and i put the ul tag around the inline manually, but htmltidy breaks this. --martin + +>>>> You might want to check if the [[plugins/contrib/report]] plugin solves your problem. It can sort by title, among other things. --[[KathrynAndersen]] + +>> See also: [[todo/sort_parameter_for_map_plugin_and_directive]] --[[smcv]] diff --git a/doc/bugs/post-update_hook_can__39__t_be_compiled_with_tcc.mdwn b/doc/bugs/post-update_hook_can__39__t_be_compiled_with_tcc.mdwn new file mode 100644 index 000000000..a8fb19888 --- /dev/null +++ b/doc/bugs/post-update_hook_can__39__t_be_compiled_with_tcc.mdwn @@ -0,0 +1,19 @@ +Thinking that any c compiler would do the job, I tried to use tcc with ikiwiki, as explicitely allowed by the Debian package dependencies. + +I installed `tcc` and `libc6-dev` (for `libcrt1`). The wrapper compilation was OK, but the wrapper fails to run correctly and dies with + + usage: ikiwiki [options] source dest + ikiwiki --setup configfile + +Everything works fine with gcc. + +versions: Debian lenny + backports + +> Seems that tcc does not respect changing where `environ` points as a way +> to change the environment seen after `exec` +> +> Given that the man page for `clearenv` suggests using `environ=NULL` +> if `clearenv` is not available, I would be lerry or using tcc to compile +> stuff, since that could easily lead to a security compromise of code that +> expects that to work. However, I have fixed ikiwiki to use `clearenv`. +> --[[Joey]] [[done]] diff --git a/doc/bugs/rebuild_after_changing_the_underlaydir_config_option.mdwn b/doc/bugs/rebuild_after_changing_the_underlaydir_config_option.mdwn new file mode 100644 index 000000000..8613ef03c --- /dev/null +++ b/doc/bugs/rebuild_after_changing_the_underlaydir_config_option.mdwn @@ -0,0 +1,12 @@ +It seems that rebuild a wiki (`ikiwiki --rebuild`) after changing the `underlaydir` config option doesn't remove the pages coming from the previous underlaydir. + +I've noticed this with the debian package version 3.20100102.3~bpo50+1. + +Perhaps it is possible to improve this or mention it in the manual page? + +--prosper + +> --rebuild causes ikiwiki to throw away all its info about what it built +> before, so it will never clean up pages that have been removed, by any +> means. Suggest you do a --refresh, possibly followed by a --rebuild +> if that is really necessary. --[[Joey]] diff --git a/doc/bugs/some_but_not_all_meta_fields_are_stored_escaped.mdwn b/doc/bugs/some_but_not_all_meta_fields_are_stored_escaped.mdwn new file mode 100644 index 000000000..587771ba4 --- /dev/null +++ b/doc/bugs/some_but_not_all_meta_fields_are_stored_escaped.mdwn @@ -0,0 +1,44 @@ +[[!template id=gitbranch branch=smcv/unescaped-meta author="[[Simon_McVittie|smcv]]"]] +[[!tag patch]] +(Warning: this branch has not been tested thoroughly.) + +While discussing the [[plugins/meta]] plugin on IRC, Joey pointed out that +it stores most meta fields unescaped, but 'title', 'guid' and 'description' +are special-cased and stored escaped (with numeric XML/HTML entities). This +is to avoid emitting markup in the `<title>` of a HTML page, or in an RSS/Atom +feed, neither of which are subject to the [[plugins/htmlscrubber]]. + +However, having the meta fields "partially escaped" like this is somewhat +error-prone. Joey suggested that perhaps everything should be stored +unescaped, and the escaping should be done on output; this branch +implements that. + +Points of extra subtlety: + +* The title given to the [[plugins/search]] plugin was previously HTML; + now it's plain text, potentially containing markup characters. I suspect + that that's what Xapian wants anyway (which is why I didn't change it), + but I could be wrong... + + > AFAICS, this if anything, fixes a bug, xapian definitely expects + > unescaped text here. --[[Joey]] + +* Page descriptions in the HTML `<head>` were previously double-escaped: + the description was stored escaped with numeric entities, then that was + output with a second layer of escaping! In this branch, I just emit + the page description escaped once, as was presumably the intention. + +* It's safe to apply this change to a wiki and neglect to rebuild it + (assuming I implemented it correctly!), but until the wiki is rebuilt, + titles, descriptions and GUIDs for unchanged pages will appear + double-escaped on any page that inlines them in `quick=yes` mode, and + is rebuilt for some other reason. The failure mode is too much escaping + rather than too little, so it shouldn't be a security problem. + +* Reverting this change, if applied, is more dangerous; until the wiki is + rebuilt, any titles, descriptions and GUIDs on unchanged pages that + contained markup could appear unescaped on any page that inlines them + in `quick=yes` mode, and is rebuilt for some other reason. The failure + mode here would be too little escaping, i.e. cross-site scripting. + +[[!tag done]] diff --git a/doc/bugs/stray___60____47__p__62___tags.mdwn b/doc/bugs/stray___60____47__p__62___tags.mdwn index 6e508ffda..99d6fe09f 100644 --- a/doc/bugs/stray___60____47__p__62___tags.mdwn +++ b/doc/bugs/stray___60____47__p__62___tags.mdwn @@ -13,3 +13,5 @@ I believe that this snippet in `IkiWiki.pm` might be the reason for the imbalanc } The fact that HTML in a `\[[!meta title]]` is added but then escaped might indicate that some other bug is involved. + +> [[done]] --[[Joey]] diff --git a/doc/bugs/tagged__40____41___matching_wikilinks.mdwn b/doc/bugs/tagged__40____41___matching_wikilinks.mdwn index e7e4af7c3..a211654f1 100644 --- a/doc/bugs/tagged__40____41___matching_wikilinks.mdwn +++ b/doc/bugs/tagged__40____41___matching_wikilinks.mdwn @@ -28,6 +28,8 @@ rationale on this, or what am I doing wrong, and how to achieve what I want? >> is valid. [[todo/matching_different_kinds_of_links]] is probably >> how it will eventually be solved. --[[Joey]] +>>> [[Done]]: `tagged` no longer matches other wikilinks. --[[smcv]] + > And this is an illustration why a clean work-around (without changing the software) is not possible: while thinking about [[todo/matching_different_kinds_of_links]], I thought one could work around the problem by simply explicitly including the kind of the relation into the link target (like the tagbase in tags), and by having a separate page without the "tagbase" to link to when one wants simply to refer to the tag without tagging. But this won't work: one has to at least once refer to the real tag page if one wants to talk about it, and this reference will count as tagging (unwanted). --Ivan Z. > But well, perhaps there is a workaround without introducing different kinds of links. One could modify the [[tag plugin|plugins/tag]] so that it adds 2 links to a page: for tagging -- `tagbase/TAG`, and for navigation -- `tagdescription/TAG` (displayed at the bottom). Then the `tagdescription/TAG` page would hold whatever list one wishes (with `tagged(TAG)` in the pagespec), and whenever one wants to merely refer to the tag, one should link to `tagdescription/TAG`--this link won't count as tagging. So, `tagbase/TAG` would become completely auxiliary (internal) link targets for ikiwiki, the users would edit or link to only `tagdescription/TAG`. --Ivan Z. diff --git a/doc/bugs/templateForRecentChangesMissingCloseSpan.mdwn b/doc/bugs/templateForRecentChangesMissingCloseSpan.mdwn new file mode 100644 index 000000000..5c322991a --- /dev/null +++ b/doc/bugs/templateForRecentChangesMissingCloseSpan.mdwn @@ -0,0 +1,26 @@ +In the template for ikiwiki's recent changes page + + /usr/share/ikiwiki/templates/change.tmpl + +there is a missing </span> tag after the + + <span class="changedate"><TMPL_VAR COMMITDATE> + +This results in the recentchanges/ page being invalid and rendering quite horrifyingly in Internet Exploder. + +[I'm running](http://wiki.shlrm.org) (linked so you can see the one I'm running if you need to) the latest version of ikiwiki, and I note that it's broken on [ikiwiki.info](http://validator.w3.org/check?uri=http%3A%2F%2Fikiwiki.info%2Frecentchanges%2F&charset=%28detect+automatically%29&doctype=Inline&group=0&user-agent=W3C_Validator%2F1.767) too :) + +[This one on debian](https://www.icanttype.org/recentchanges/) is somehow [valid](http://validator.w3.org/check?uri=https%3A%2F%2Fwww.icanttype.org%2F%2Frecentchanges%2F&charset=%28detect+automatically%29&doctype=Inline&group=0&user-agent=W3C_Validator%2F1.767), although it's using the same template. Perhaps there's an additional scrubbing going on his end. + +Thanks, +David + +PS: I have fixed the template by hand on my server, so it will validate, however ikiwiki.info will not. + +> [[!template id="gitbranch" branch=smcv/trivia author="[[smcv]]"]] [[!tag patch]] +> Enabling either [[plugins/htmltidy]] or [[plugins/htmlbalance]] will automatically fix unbalanced +> markup like this; using [[plugins/comments]] without having one or other of those is a bad idea +> from the point of view of avoiding comment forgery, which is probably why icanttype.org works +> correctly. Anyway, I've fixed this in a branch: Joey, care to review smcv/trivia? --[[smcv]] + +[[done]], thanks guys --[[Joey]] diff --git a/doc/bugs/wrapper_can__39__t_find_the_perl_modules.mdwn b/doc/bugs/wrapper_can__39__t_find_the_perl_modules.mdwn new file mode 100644 index 000000000..9804d86c5 --- /dev/null +++ b/doc/bugs/wrapper_can__39__t_find_the_perl_modules.mdwn @@ -0,0 +1,16 @@ +If i intsall perl modules in my custom directory, cgi wrapper can't find them. I found clearing enviroment variables in code of wrapper. But information about custom directories put to perl with PERL5LIB variable. + +Workaround: add newenviron variable PERL5LIB + +My additional question - what wrapper do? I'am russian hosting provider. I am interesting with ikiwiki. + +> The wrapper allows ikiwiki to run as the user who owns the wiki, which +> is generally not the same as the user that runs the web server. +> (It also handles some other things, like some locking.) +> +> As a suid program, the wrapper cannot safely let environment variables +> pass through. +> +> If you want to install ikiwiki's perl modules in a nonstandard location, +> you can set `INSTALL_BASE` when running `Makefile.PL`. ikiwiki will then +> be built to look in that location. --[[Joey]] [[!tag done]] diff --git a/doc/download.mdwn b/doc/download.mdwn index 45d0d7870..92c8a4f75 100644 --- a/doc/download.mdwn +++ b/doc/download.mdwn @@ -35,7 +35,7 @@ own RPM. ## BSD ports -IkiWiki can be installed [from macports](http://www.macports.org/ports.php?by=name&substr=ikiwiki) +Ikiwiki can be installed [from macports](http://www.macports.org/ports.php?by=name&substr=ikiwiki) by running `sudo port install ikiwiki`. NetBSD and many other platforms: pkgsrc has an [ikiwiki package](ftp://ftp.netbsd.org/pub/pkgsrc/current/pkgsrc/www/ikiwiki/README.html). diff --git a/doc/examples/blog.mdwn b/doc/examples/blog.mdwn index f542cad0c..8775c01ab 100644 --- a/doc/examples/blog.mdwn +++ b/doc/examples/blog.mdwn @@ -13,16 +13,11 @@ Some additional configuration you might want to do: example of how to tag a post is: \[[!tag tags/life]] -* Enable the [[sidebar|plugins/sidebar]] plugin to get a sidebar listing all - the categories you've tagged posts with. - * Enable the [[pagestats|plugins/pagestats]] plugin to get a tag cloud to display on the [[index]]. -* Enable the [[comments|plugins/comments]] plugin and configure it to - enable comments to posts to the blog: - - comments_pagespec => 'blog/posts/* and !*/Discussion', +* Enable the [[comments|plugins/comments]] plugin to + enable comments to posts to the blog. * Enable the [[calendar|plugins/calendar]] plugin and run the [[ikiwiki-calendar]] command from cron daily to get an interlinked diff --git a/doc/examples/blog/archives.mdwn b/doc/examples/blog/archives.mdwn new file mode 100644 index 000000000..d07b73b74 --- /dev/null +++ b/doc/examples/blog/archives.mdwn @@ -0,0 +1,8 @@ +[[!if test="archives/*" then=""" +Browse through blog archives by year: +[[!map pages="./archives/* and !./archives/*/* and !*/Discussion"]] +""" +else=""" +You need to use the `ikiwiki-calendar` program to generate calendar-based +archive pages. +"""]] diff --git a/doc/examples/blog/comments.mdwn b/doc/examples/blog/comments.mdwn index 4735dea08..0b503ba01 100644 --- a/doc/examples/blog/comments.mdwn +++ b/doc/examples/blog/comments.mdwn @@ -1,3 +1,3 @@ -This page will show all comments made to posts in my [[blog|index]]. +This page will show recent comments made to posts in the [[blog|index]]. [[!inline pages="./posts/*/Discussion or internal(./posts/*/comment_*)"]] diff --git a/doc/examples/blog/index.mdwn b/doc/examples/blog/index.mdwn index 01b714fcd..a22c40c72 100644 --- a/doc/examples/blog/index.mdwn +++ b/doc/examples/blog/index.mdwn @@ -1,13 +1,6 @@ -[[!pagestats pages="./tags/*" among="./posts/*"]] - -Welcome to my blog. - -Have a look at the most recent posts below, or browse the tag cloud on the -right. Archives of all [[posts]] and all [[comments]] are also available. - [[!inline pages="./posts/* and !*/Discussion" show="10" actions=yes rootpage="posts"]] ----- +[[!sidebar]] This blog is powered by [ikiwiki](http://ikiwiki.info). diff --git a/doc/examples/blog/posts/first_post.mdwn b/doc/examples/blog/posts/first_post.mdwn index d49432341..f2729fcef 100644 --- a/doc/examples/blog/posts/first_post.mdwn +++ b/doc/examples/blog/posts/first_post.mdwn @@ -1,4 +1,4 @@ This is the first post to this example blog. To add new posts, just add files to the posts/ subdirectory, or use the web form. -[[!tag tags/tech]] +[[!tag tech]] diff --git a/doc/examples/blog/sidebar.mdwn b/doc/examples/blog/sidebar.mdwn index a9fac388e..5c1f17723 100644 --- a/doc/examples/blog/sidebar.mdwn +++ b/doc/examples/blog/sidebar.mdwn @@ -1,7 +1,10 @@ -Example sidebar +[[!if test="enabled(calendar)" then=""" +[[!calendar pages="./posts/* and !*/Discussion"]] +"""]] -* [[Blog|index]] -* [[Archive|posts]] +[[Recent Comments|comments]] -Categories: -[[!map pages="./tags/* and !*/Discussion"]] +[[Archives]] + +[[Tags]]: +[[!pagestats style="list" pages="./tags/*" among="./posts/*"]] diff --git a/doc/examples/softwaresite.mdwn b/doc/examples/softwaresite.mdwn index e43a9d116..99f791177 100644 --- a/doc/examples/softwaresite.mdwn +++ b/doc/examples/softwaresite.mdwn @@ -14,3 +14,6 @@ Some additional configuration you might want to do: * Read the [[tips/integrated_issue_tracking_with_ikiwiki]] article for tips about how to use ikiwiki as a BTS. + +* Read [[tips/spam_and_softwaresites]] for information on how to keep spam + and spam-fighting commits out of your main version control history. diff --git a/doc/examples/softwaresite/news.mdwn b/doc/examples/softwaresite/news.mdwn index 9b53c7d99..20efba6e0 100644 --- a/doc/examples/softwaresite/news.mdwn +++ b/doc/examples/softwaresite/news.mdwn @@ -1,4 +1,4 @@ -This is where annoucements of new releases, features, and other news is +This is where announcements of new releases, features, and other news is posted. FooBar users are recommended to subscribe to this page's RSS feed. diff --git a/doc/features.mdwn b/doc/features.mdwn index 3925d78ef..ab521213d 100644 --- a/doc/features.mdwn +++ b/doc/features.mdwn @@ -13,7 +13,7 @@ Instead of editing pages in a stupid web form, you can use vim and commit changes via [[Subversion|rcs/svn]], [[rcs/git]], or any of a number of other [[Revision_Control_Systems|rcs]]. -ikiwiki can be run from a [[post-commit]] hook to update your wiki +Ikiwiki can be run from a [[post-commit]] hook to update your wiki immediately whenever you commit a change using the RCS. It's even possible to securely let @@ -25,7 +25,7 @@ run a simple wiki without page history, it can do that too. ## A wiki compiler -ikiwiki is a wiki compiler; it builds a static website for your wiki, and +Ikiwiki is a wiki compiler; it builds a static website for your wiki, and updates it as pages are edited. It is fast and smart about updating a wiki, it only builds pages that have changed (and tracks things like creation of new pages and links that can indirectly cause a page to need a rebuild) @@ -45,7 +45,7 @@ easily be added by [[plugins]]. For example it also supports traditional [[plugins/HTML]], or pages written in [[reStructuredText|plugins/rst]] or [[Textile|plugins/textile]]. -ikiwiki also supports files of any other type, including plain text, +Ikiwiki also supports files of any other type, including plain text, images, etc. These are not converted to wiki pages, they are just copied unchanged by ikiwiki as it builds your wiki. So you can check in an image, program, or other special file and link to it from your wiki pages. @@ -70,8 +70,8 @@ you would care to syndicate. ## Valid html and [[css]] -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 can change the look and layout of all pages in any way you would like. @@ -163,7 +163,7 @@ Well, sorta. Rather than implementing YA history browser, it can link to ### Full text search -ikiwiki can use the xapian search engine to add powerful +Ikiwiki can use the xapian search engine to add powerful full text [[plugins/search]] capabilities to your wiki. ### Translation via po files diff --git a/doc/forum/How_does_ikiwiki_remember_times__63__.mdwn b/doc/forum/How_does_ikiwiki_remember_times__63__.mdwn index 6ce576db1..6b7739fd0 100644 --- a/doc/forum/How_does_ikiwiki_remember_times__63__.mdwn +++ b/doc/forum/How_does_ikiwiki_remember_times__63__.mdwn @@ -20,15 +20,17 @@ 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]] +> --[[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. +> +> > > Update: It's now renamed to `--gettime`, and pulls both the creation +> > > and modification times. Also, per [[todo/auto_getctime_on_fresh_build]], +> > > this is now done automatically the first time ikiwiki builds a +> > > srcdir. So, no need to worry about this any more! --[[Joey]] > > > > 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 @@ -91,19 +93,6 @@ Do I have it right? > A quick workaround for me to get modification times right is the following > little zsh script, which unfortunately only works for git: - #!/usr/bin/env zsh - - set +x - - for FILE in **/*(.); do - TIMES="`git log --pretty=format:%ai $FILE`" - MTIME="`echo $TIMES | head -n1`" - - if [ ! -z $MTIME ]; then - echo touch -m -d "$MTIME" $FILE - touch -m -d "$MTIME" $FILE - fi - - done +>> Elided; no longer needed since --gettime does that, and much faster! --[[Joey]] > --[[David_Riebenbauer]] 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 index fe67e6aba..d7a33b526 100644 --- a/doc/forum/Migrating_old_repository_to_new_ikiwiki_system__63__.mdwn +++ b/doc/forum/Migrating_old_repository_to_new_ikiwiki_system__63__.mdwn @@ -20,10 +20,6 @@ How do I set up an ikiwiki system using a pre-existing repository (instead of cr > 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 diff --git a/doc/forum/an_alternative_approach_to_structured_data.mdwn b/doc/forum/an_alternative_approach_to_structured_data.mdwn index eb6ee4445..6e6af8adb 100644 --- a/doc/forum/an_alternative_approach_to_structured_data.mdwn +++ b/doc/forum/an_alternative_approach_to_structured_data.mdwn @@ -18,6 +18,12 @@ I think it could be really powerful and useful, especially if it becomes part of > It looks like an interesting idea. I don't have time right now to look at it in depth, but it looks interesting. -- [[Will]] +> I agree such a separation makes some sense. But note that the discussion on [[todo/structured_page_data]] +> talks about associating data types with fields for a good reason: It's hard to later develop a good UI for +> querying or modifying a page's data if all the data has an implicit type "string". --[[Joey]] + +>> I'm not sure that having an implicit type of "string" is really such a bad thing. After all, Perl itself manages with just string and number, and easily converts from one to the other. Strong typing is generally used to (a) restrict what can be done with the data and/or (b) restrict how the data is input. The latter could be done with some sort of validated form, but that, too, could be decoupled from looking up and returning the value of a field. --[[KathrynAndersen]] + ## Second Pass I have written additional plugins which integrate with the [[plugins/contrib/field]] plugin to both set and get structured page data. @@ -27,3 +33,31 @@ I have written additional plugins which integrate with the [[plugins/contrib/fie * [[plugins/contrib/ymlfront]] - looks for YAML-format data at the front of a page; this is just one possible back-end for the structured data --[[KathrynAndersen]] + +> I'm not an IkiWiki committer ([[Joey]] is the only one I think) +> but I really like the look of this scheme. In particular, +> having `getfield` interop with `field` without being *part of* +> `field` makes me happy, since I'm not very keen on `getfield`'s +> syntax (i.e. "ugh, yet another mini-markup-language without a +> proper escaping mechanism"), but this way people can experiment +> with different syntaxes while keeping `field` for the +> behind-the-scenes bits. +> +>> I've started using `field` on a private site and it's working +>> well for me; I'll try to do some code review on its +>> [[plugins/contrib/field/discussion]] page. --s +> +> My [[plugins/contrib/album]] plugin could benefit from +> integration with `field` for photos' captions and so on, +> probably... I'll try to work on that at some point. +> +> [[plugins/contrib/report]] may be doing too much, though: +> it seems to be an variation on `\[[inline archive="yes"]]`, +> with an enhanced version of sorting, a mini version of +> [[todo/wikitrails]], and some other misc. I suspect it could +> usefully be divided up into discrete features? One good way +> to do that might be to shuffle bits of its functionality into +> the IkiWiki distribution and/or separate plugins, until there's +> nothing left in `report` itself and it can just go away. +> +> --[[smcv]] diff --git a/doc/forum/google_openid_broken__63__.mdwn b/doc/forum/google_openid_broken__63__.mdwn index 68b44f2c1..96ba2d791 100644 --- a/doc/forum/google_openid_broken__63__.mdwn +++ b/doc/forum/google_openid_broken__63__.mdwn @@ -50,3 +50,30 @@ The openid is <https://www.google.com/accounts/o8/id?id=AItOawltlTwUCL_Fr1siQn94GV65-XwQH5XSku4> (what a mouthfull!), and I don't know who that is or how to use it since it points to a fairly useless xml document, rather than a web page. --[[Joey]] + +> That string is what's received via the discovery protocol. The user logging in with a Google account is not supposed to write that when logging in, but rather <https://www.google.com/accounts/o8/id>. The OpenID client library will accept that and redirect the user to a sign in page, which will return that string as the OpenID. It's not really usable as an identifier for edits and whatnots, but an alternative would be to use the attribute exchange extension to get the email address and display that. See <http://code.google.com/apis/accounts/docs/OpenID.html#Parameters>. + +> Yahoo's OpenID implementation works alike, but I haven't looked at it as much. It uses <https://me.yahoo.com/> to receive the endpoint. + +> I've added buttons that submit the two above URLs for logging in with a Google and Yahoo OpenID, respectively, to my locally changed OpenID login plugin. + +> Using the Google profile page as the OpenID is really orthogonal to the above. --[[kaol]] + +>> First, I don't accept that the openid google returns from their +>> generic signin url *has* to be so freaking ugly. For contrast, +>> look at the openid you log in as if you use the yahoo url. +>> <https://me.yahoo.com/joeyhess#35f22>. Nice and clean, now +>> munged by ikiwiki to "joeyhess [me.yahoo.com]". +>> +>> Displaying email addresses is not really an option, because ikiwiki +>> can't leak user email addresses like that. Displaying nicknames or +>> usernames is, see [[todo/Separate_OpenIDs_and_usernames]]. +>> +>> It would probably be good if the openid plugin could be configured with +>> a list of generic openid urls, so it can add quick login buttons using +>> those urls. +>> +>> The ugly google url will still be exposed here and there where +>> a unique user id is needed. That can be avoided by not using the generic +>> <https://www.google.com/accounts/o8/id>, but instead your own profile +>> like <http://www.google.com/profiles/joeyhess>. --[[Joey]] diff --git a/doc/forum/how_to_setup_ikiwiki_on_a_remote_host.mdwn b/doc/forum/how_to_setup_ikiwiki_on_a_remote_host.mdwn new file mode 100644 index 000000000..1c0f8f561 --- /dev/null +++ b/doc/forum/how_to_setup_ikiwiki_on_a_remote_host.mdwn @@ -0,0 +1,35 @@ +Hi all! +I really like ikiwiki and i tested it on my local machine but i have one question that i can't answer reading documentation (my fault of course)... +I have an account and some space on a free hosting service. +Now, i want to put my ikiwiki on this remote web space so that i can browse it from wherever i want. +I have my source dir and my git dir on my local machine. +How can i upload my ikiwiki on the remote host and manage it via git as i can do when i test it locally? +Where is specified? Where can i find documentation about it? + +Thanks in advance! + +Pab + +> There are several ways to accomplish this, depending on what you really +> want to do. +> +> If your goal is to continue generating the site locally, but then +> transfer it to the remote host for serving, you could use the +> [[plugins/rsync]] plugin. +> +> If your goal is to install and run the ikiwiki software on the remote host, +> then you would follow a similar path to the ones described in these tips: +> [[tips/nearlyfreespeech]] [[tips/DreamHost]]. Or even [[install]] ikiwiki +> from a regular package if you have that kind of access. Then you could +> push changes from your local git to git on the remote host to update the +> wiki. [[tips/Laptop_wiki_with_git]] explains one way to do that. +> --[[Joey]] + +Thanks a lot for your answer. +rsync plugin would be perfect but... how would i manage blog post? +I mean... is it possible to manage ikiwiki blog too with rsync plugin in the way you told me? --Pab + +> If you want to allow people to make comments on your blog, no, the rsync plugin will not help, since it will upload a completely static site where nobody can make comments. Comments require a full IkiWiki setup with CGI enabled, so that people add content (comments) from the web. --[[KathrynAndersen]] + +Ok, i understand, thanks. +Is there any hosting service that permits to have a full installation of iwkiwiki or i am forced to get a vps or to mantain a personal server for that? --Pab diff --git a/doc/forum/navigation_of_wiki_pages_on_local_filesystem_with_vim.mdwn b/doc/forum/navigation_of_wiki_pages_on_local_filesystem_with_vim.mdwn index 1cb5ed27e..7bc032949 100644 --- a/doc/forum/navigation_of_wiki_pages_on_local_filesystem_with_vim.mdwn +++ b/doc/forum/navigation_of_wiki_pages_on_local_filesystem_with_vim.mdwn @@ -1,3 +1,7 @@ +**UPDATE** I have created a [[page|tips/follow_wikilinks_from_inside_vim]] in +the tips section about the plugin, how to get it, install it and use it. Check +that out. --[[jerojasro]] + I wrote a vim function to help me navigate the wiki when I'm editing it. It extends the 'gf' (goto file) functionality. Once installed, you place the cursor on a wiki page name and press 'gf' (without the quotes); if the file exists, it gets loaded. This function takes into account the ikiwiki linking rules when deciding which file to go to. @@ -64,7 +68,27 @@ the plugin has, as of now, two problems: > Seems about ready for me to think about pulling it into ikiwiki > alongside [[tips/vim_syntax_highlighting/ikiwiki.vim]]. If you'll > please slap a license on it. :) --[[Joey]] -> +> +>> GPL version 2 or later (if that doesn't cause any problems here). I'll add it +>> to the file --[[jerojasro]] +>> +>>> I see you've put the plugin on vim.org. Do you think it makes sense to +>>> also include a copy in ikiwiki? --[[Joey]] +>>> +>>>> mmm, no. There would be two copies of it, and the git repo. I'd rather have +>>>> a unique place for the "official" version (vim.org), and another for the dev +>>>> version (its git repo). +>>>> +>>>> actually, I would also suggest to upload the [[`ikiwiki.vim`|tips/vim_syntax_highlighting]] file to vim.org --[[jerojasro]] +>>>>> +>>>>> If you have any interest in maintaining the syntax highlighting +>>>>> plugin and putting it there, I'd be fine with that. I think it needs +>>>>> some slight work to catch up with changes to ikiwiki's directives +>>>>> (!-prefixed now), and wikilinks (able to have spaces now). --[[Joey]] +>>>>> +>>>>>> I don't really know too much about syntax definitions in vim. But I'll give it a stab. I know it fails when there are 2 \[[my text|link]] wikilinks in the same page. +>>>>>> I'm not promising anything, though ;) --[[jerojasro]] +> > Also, I have a possible other approach for finding ikiwiki's root. One > could consider that any subdirectory of an ikiwiki wiki is itself > a standalone wiki, though probably one missing a toplevel index page. @@ -80,6 +104,10 @@ the plugin has, as of now, two problems: > > And if that's the case, you can resolve an absolute link by looking for > the page closest to the root that matches the link. +> +>> I like your idea; it doesn't alter the matching of the relative links, and +>> should work fine with absolute links too. I'll implement it, though I see +>> some potential (but small) issues with it --[[jerojasro]] > > It may even make sense to change ikiwiki's own handling of "absolute" > links to work that way. But even without changing ikiwiki, I think it @@ -93,3 +121,7 @@ the plugin has, as of now, two problems: > and vim would go to that file. > > --[[Joey]] +> +>> your approach will add more noise when the plugin grows the page-creation +>> feature, since there will be no real root to limit the possible locations for +>> the new page. But it is far better than demanding for a `.ikiwiki` dir --[[jerojasro]] diff --git a/doc/forum/speeding_up_ikiwiki.mdwn b/doc/forum/speeding_up_ikiwiki.mdwn index 2c2ac240e..799186cf8 100644 --- a/doc/forum/speeding_up_ikiwiki.mdwn +++ b/doc/forum/speeding_up_ikiwiki.mdwn @@ -56,7 +56,7 @@ number is still too large to really visualize: the graphviz PNG and PDF output engines segfault for me, the PS one works but I can't get any PS software to render it without exploding. -Now, the relations in the links hash are not the same thing as IkiWiki's notion of dependencies. Can anyone point me at that data structure / where I might be able to add some debugging foo to generate a graph of it? +Now, the relations in the links hash are not the same thing as Ikiwiki's notion of dependencies. Can anyone point me at that data structure / where I might be able to add some debugging foo to generate a graph of it? Once I've figured out that I might be able to optimize some pagespecs. I understand pagespecs are essentially translated into sequential perl code. I diff --git a/doc/forum/utf8_warnings_for___34____92__xAB__34__.mdwn b/doc/forum/utf8_warnings_for___34____92__xAB__34__.mdwn new file mode 100644 index 000000000..72f2d38e0 --- /dev/null +++ b/doc/forum/utf8_warnings_for___34____92__xAB__34__.mdwn @@ -0,0 +1,47 @@ +# getting Warnings about UTF8-Chars. + +I'm getting multiple warnings: + + utf8 "\xAB" does not map to Unicode at /usr/share/perl5/IkiWiki.pm line 774, <$in> chunk 1. + + +I'm assuming this is once per File, but even in verbose mode, it doesn't tell me which file is a problem. +It first reads all the files, and afterwards when parsing/compiling them, it outputs the warning, so I can't +deduce the offending files. + +Is there a way to have ikiwiki output the position, where it encounters the character? + +Probably all this has to do with locale-settings, and usage of mixed locales in a distributed setup ... +I'd rather cleanup some of the file(name)s of unexpected characters. --[[jwalzer]] + +-------- + +**Update** : So I took the chance to insert debug into ikiwiki.pm: + + root@novalis:/usr/share/perl5# diff -p /tmp/IkiWiki.orig.pm IkiWiki.pm + *** /tmp/IkiWiki.orig.pm Sun Feb 14 15:16:08 2010 + --- IkiWiki.pm Sun Feb 14 15:16:28 2010 + *************** sub readfile ($;$$) { + *** 768,773 **** + --- 768,774 ---- + } + + local $/=undef; + + debug("opening File: $file:"); + open (my $in, "<", $file) || error("failed to read $file: $!"); + binmode($in) if ($binary); + return \*$in if $wantfd; + + +But what I see now is not quite helpful, as it seems, STDERR and DEBUG are asyncronous, so they mix up in a way, that I can't really see, whats the problem ... Maybe I'm better off for troubleshooting, to insert an printf to strerr to have it in the same stream.. --[[jwalzer]] + + +---- + +**Update:** The "print STDERR $file;"-Trick did it .. I was able to find a mdwn-file, that (was generated by a script of me) had \0xAB in it. + +Nevertheless I still wonder if this should be a problem. This character happend to be in an *\[\[meta title='$CHAR'\]\]-tag* and an *\[$CHAR\]http://foo)-Link* + +Should this throw an warning? Maybe this warning could be catched an reported inclusively the containing filename? maybe even with an override, if one knows that it is correct that way? --[[jwalzer]] + +[[!tag solved]] diff --git a/doc/forum/where_are_the_tags.mdwn b/doc/forum/where_are_the_tags.mdwn new file mode 100644 index 000000000..ecb49fe43 --- /dev/null +++ b/doc/forum/where_are_the_tags.mdwn @@ -0,0 +1,9 @@ +Where is the tag cloud/tag listing of all the tags used in this wiki? I know we +have tags enabled. --[[jerojasro]] + +> This wiki does not use one global toplevel set of tags (`tagbase` is not +> set). +> +> There are tags used for the [[plugins]], and a tag cloud of those +> there. [[wishlist]] and [[patch]] are tags too, but I don't see the point +> of a tag cloud for such tags. --[[Joey]] diff --git a/doc/forum/wishlist-discussion:_Editformular_showing_existing_tags.mdwn b/doc/forum/wishlist-discussion:_Editformular_showing_existing_tags.mdwn new file mode 100644 index 000000000..49c55e20e --- /dev/null +++ b/doc/forum/wishlist-discussion:_Editformular_showing_existing_tags.mdwn @@ -0,0 +1,15 @@ +# How about: + +having a list of all existing tags in the Edit-Formular as a selectionbox? + +Assume I have tagbase=/tags/ and for every tag I have given to articles an existing page there. + +Would it be possible to list all these tags together with the Formular, as selectionbox. +Maybe even with parsing of the content and preselecting the tags, that are given in the article and vice-versa when selecting the fields then also generating the \[\[\!tag\]\]-sourcecode ? + +this would need a bit JS-work and somehow on compiletime we need to put the list of tags somewhere, where the cgi could read them from. +This way, even a pagespec would suffice to determine the usable list of tags and not only the tagbase-variable. + +> I think this would be very hard to achieve with the current tag plugin, due to the nature of its implementation. +> +> I've had a "tag2" plugin on the go for a while which supports this. It's in a very rough stage but I'll try to find it and upload it somewhere. -- [[Jon]] diff --git a/doc/git.mdwn b/doc/git.mdwn index 30fed6afc..55967e543 100644 --- a/doc/git.mdwn +++ b/doc/git.mdwn @@ -26,7 +26,8 @@ be browsed, subscribed to etc on its You are of course free to set up your own ikiwiki git repository with your own [[patches|patch]]. If you list it here, the `gitremotes` script will automatically add it to git remotes. Your repo will automatically be pulled -into [[Joey]]'s working tree. This is recommended. :-) +into [[Joey]]'s working repository where he can see your branches and +think about merging them. This is recommended. :-) <!-- Machine-parsed format: * wikilink <git:url> --> @@ -56,7 +57,11 @@ into [[Joey]]'s working tree. This is recommended. :-) * [[ktf]] `git://github.com/ktf/ikiwiki.git` * [[tove]] `git://github.com/tove/ikiwiki.git` * [[GiuseppeBilotta]] `git://git.oblomov.eu/ikiwiki` -* [[roktas]] `git://github.com/roktas/ikiwiki.git`` +* [[roktas]] `git://github.com/roktas/ikiwiki.git` +* [[davrieb|David_Riebenbauer]] `git://git.liegesta.at/git/ikiwiki` + ([browse](http://git.liegesta.at/?p=ikiwiki.git;a=summary)) +* [[GustafThorslund]] `http://gustaf.thorslund.org/src/ikiwiki.git` +* [[peteg]] `git://git.hcoop.net/git/peteg/ikiwiki.git` ## branches diff --git a/doc/ikiwiki-calendar.mdwn b/doc/ikiwiki-calendar.mdwn index 982892fca..c1f4d7267 100644 --- a/doc/ikiwiki-calendar.mdwn +++ b/doc/ikiwiki-calendar.mdwn @@ -16,9 +16,11 @@ You must specify the setup file for your wiki. The pages will be created inside its `srcdir`, beneath the `archivebase` directory used by the calendar plugin (default "archives"). -You will probably want to specify a [[ikiwiki/PageSpec]] -to control which pages are included on the calendars. The -default is all pages. To limit it to only posts in a blog, +To control which pages are included on the calendars, +a [[ikiwiki/PageSpec]] can be specified. The default is +all pages, or the pages specified by the `comments_pagespec` +setting in the config file. A pagespec can also be specified +on the command line. To limit it to only posts in a blog, use something like "posts/* and !*/Discussion". It defaults to creating calendar pages for the current diff --git a/doc/ikiwiki/directive/calendar.mdwn b/doc/ikiwiki/directive/calendar.mdwn index b2ac75b11..198da9d51 100644 --- a/doc/ikiwiki/directive/calendar.mdwn +++ b/doc/ikiwiki/directive/calendar.mdwn @@ -40,9 +40,12 @@ An example crontab: "month" or "year". The default is a month view calendar. * `pages` - Specifies the [[ikiwiki/PageSpec]] of pages to link to from the month calendar. Defaults to "*". -* `archivebase` - Configures the base of the archives hierarchy. The - default is "archives". Note that this default can also be overridden +* `archivebase` - Configures the base of the archives hierarchy. + The default is "archives". Note that this default can also be overridden for the whole wiki by setting `archivebase` in ikiwiki's setup file. + Calendars link to pages under here, with names like "2010/04" and + "2010". These pages can be automatically created using the + `ikiwiki-calendar` program. * `year` - The year for which the calendar is requested. Defaults to the current year. * `month` - The numeric month for which the calendar is requested, in the diff --git a/doc/ikiwiki/directive/date.mdwn b/doc/ikiwiki/directive/date.mdwn index df45fa840..b89241e4c 100644 --- a/doc/ikiwiki/directive/date.mdwn +++ b/doc/ikiwiki/directive/date.mdwn @@ -12,3 +12,5 @@ For example, an update to a page with an embedded date stamp could look like: Updated \[[!date "Wed, 25 Nov 2009 01:11:55 -0500"]]: mumble mumble + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/format.mdwn b/doc/ikiwiki/directive/format.mdwn index 23830e9cd..7d11d225f 100644 --- a/doc/ikiwiki/directive/format.mdwn +++ b/doc/ikiwiki/directive/format.mdwn @@ -22,7 +22,7 @@ Note that if the highlight plugin is enabled, this directive can also be used to display syntax highlighted code. Many languages and formats are supported. For example: - \[[format perl """ + \[[!format perl """ print "hello, world\n"; """]] diff --git a/doc/ikiwiki/directive/inline/discussion.mdwn b/doc/ikiwiki/directive/inline/discussion.mdwn index 998ba642b..6a186cd93 100644 --- a/doc/ikiwiki/directive/inline/discussion.mdwn +++ b/doc/ikiwiki/directive/inline/discussion.mdwn @@ -1,3 +1,10 @@ +## Combine inline and toggle + +Is it possible to combine the behaviour of toggle and inline? ie, have it present of list of 'headlines' which are created from seperate subpages which can be clicked to expand to the body of the inlined page. Thanks. + +-- Thiana + +--- ## 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 diff --git a/doc/ikiwiki/directive/map/discussion.mdwn b/doc/ikiwiki/directive/map/discussion.mdwn index 062b4267a..f6eaa6b80 100644 --- a/doc/ikiwiki/directive/map/discussion.mdwn +++ b/doc/ikiwiki/directive/map/discussion.mdwn @@ -1,3 +1,14 @@ +### Sorting + +Is there a way to have the generated maps sorted by *title* instead of *filename* when show=title is used? +Thanks + +-- Thiana + +> [[bugs/map_sorts_by_pagename_and_not_title_when_show__61__title_is_used]] --[[Joey]] + +---- + Question: Is there a way to generate a listing that shows *both* title and description meta information? Currently, a \[\[!map ...]] shows only one of the two, but I'd like to generate a navigation that looks like a description list. For example: * This is the title meta information. diff --git a/doc/ikiwiki/directive/meta.mdwn b/doc/ikiwiki/directive/meta.mdwn index 557441c0b..5a3919dea 100644 --- a/doc/ikiwiki/directive/meta.mdwn +++ b/doc/ikiwiki/directive/meta.mdwn @@ -23,6 +23,13 @@ Supported fields: be set to a true value in the template; this can be used to format things differently in this case. + An optional `sortas` parameter will be used preferentially when + [[ikiwiki/pagespec/sorting]] by `meta(title)`: + + \[[!meta title="The Beatles" sortas="Beatles, The"]] + + \[[!meta title="David Bowie" sortas="Bowie, David"]] + * license Specifies a license for the page, for example, "GPL". Can contain @@ -37,6 +44,11 @@ Supported fields: Specifies the author of a page. + An optional `sortas` parameter will be used preferentially when + [[ikiwiki/pagespec/sorting]] by `meta(author)`: + + \[[!meta author="Joey Hess" sortas="Hess, Joey"]] + * authorurl Specifies an url for the author of a page. diff --git a/doc/ikiwiki/directive/pagestats.mdwn b/doc/ikiwiki/directive/pagestats.mdwn index 68f4d2734..d0e0e7be7 100644 --- a/doc/ikiwiki/directive/pagestats.mdwn +++ b/doc/ikiwiki/directive/pagestats.mdwn @@ -4,10 +4,16 @@ This directive can generate stats about how pages link to each other. It can produce either a tag cloud, or a table counting the number of links to each page. -Here's how to use it to create a [[tag]] cloud: +Here's how to use it to create a [[tag]] cloud, with tags sized based +on frequency of use: \[[!pagestats pages="tags/*"]] +Here's how to create a list of tags, sized by use as they would be in a +cloud. + + \[[!pagestats style="list" pages="tags/*"]] + And here's how to create a table of all the pages on the wiki: \[[!pagestats style="table"]] @@ -28,4 +34,7 @@ links: \[[!pagestats style="table" show="10"]] +The optional `class` parameter can be used to control the class +of the generated tag cloud `div` or page stats `table`. + [[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/sidebar.mdwn b/doc/ikiwiki/directive/sidebar.mdwn new file mode 100644 index 000000000..599695d22 --- /dev/null +++ b/doc/ikiwiki/directive/sidebar.mdwn @@ -0,0 +1,20 @@ +The `sidebar` directive is supplied by the [[!iki plugins/sidebar desc=sidebar]] plugin. + +This directive can specify a custom sidebar to display on the page, +overriding any sidebar that is displayed globally. + +If no custom sidebar content is specified, it forces the sidebar page to +be used as the sidebar, even if the `global_sidebars` setting has been +used to disable use of the sidebar page by default. + +## examples + + \[[!sidebar content=""" + This is my custom sidebar for this page. + + \[[!calendar pages="posts/*"]] + """]] + + \[[!sidebar]] + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/directive/table.mdwn b/doc/ikiwiki/directive/table.mdwn index e27a94b7c..a6692f92c 100644 --- a/doc/ikiwiki/directive/table.mdwn +++ b/doc/ikiwiki/directive/table.mdwn @@ -6,8 +6,8 @@ or DSV (delimiter-separated values) format. ## examples \[[!table data=""" - Customer|Amount - Fulanito|134,34 + Customer |Amount + Fulanito |134,34 Menganito|234,56 Menganito|234,56 """]] @@ -42,4 +42,9 @@ cells. For example: as the table header. Set it to "no" to make a table without a header, or "column" to make the first column be the header. +For tab-delimited tables (often obtained by copying and pasting from HTML +or a spreadsheet), `delimiter` must be set to a literal tab character. These +are difficult to type in most web browsers - copying and pasting one from +the table data is likely to be the easiest way. + [[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/pagespec.mdwn b/doc/ikiwiki/pagespec.mdwn index 5f0f44e2e..5c191f23f 100644 --- a/doc/ikiwiki/pagespec.mdwn +++ b/doc/ikiwiki/pagespec.mdwn @@ -44,7 +44,8 @@ Some more elaborate limits can be added to what matches using these functions: metadata, matching the specified glob. * "`user(username)`" - tests whether a modification is being made by a user with the specified username. If openid is enabled, an openid can also - be put here. + be put here. Glob patterns can be used in the username. For example, + to match all openid users, use `user(*://*)` * "`admin()`" - tests whether a modification is being made by one of the wiki admins. * "`ip(address)`" - tests whether a modification is being made from the diff --git a/doc/ikiwiki/pagespec/po.mdwn b/doc/ikiwiki/pagespec/po.mdwn index e0264dd50..40ed9efb6 100644 --- a/doc/ikiwiki/pagespec/po.mdwn +++ b/doc/ikiwiki/pagespec/po.mdwn @@ -14,3 +14,5 @@ wiki: Note that every non-po page is considered to be written in `po_master_language`, as specified in `ikiwiki.setup`. + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwiki/pagespec/sorting.mdwn b/doc/ikiwiki/pagespec/sorting.mdwn index 41aa58151..ccd7f7eaa 100644 --- a/doc/ikiwiki/pagespec/sorting.mdwn +++ b/doc/ikiwiki/pagespec/sorting.mdwn @@ -4,8 +4,23 @@ specifying the order that matching pages are shown in. The following sort orders can be specified. * `age` - List pages from the most recently created to the oldest. + * `mtime` - List pages with the most recently modified first. -* `title` - Order by title. -* `title_natural` - Only available if [[!cpan Sort::Naturally]] is - installed. Orders by title, but numbers in the title are treated + +* `title` - Order by title (page name). +[[!if test="enabled(sortnaturally)" then=""" +* `title_natural` - Orders by title, but numbers in the title are treated as such, ("1 2 9 10 20" instead of "1 10 2 20 9") +"""]] +[[!if test="enabled(meta)" then=""" +* `meta(title)` - Order according to the `\[[!meta title="foo" sortas="bar"]]` + or `\[[!meta title="foo"]]` [[ikiwiki/directive]], or the page name if no + full title was set. `meta(author)`, `meta(date)`, `meta(updated)`, etc. + also work. +"""]] + +In addition, you can combine several sort orders and/or reverse the order of +sorting, with a string like `age -title` (which would sort by age, then by +title in reverse order if two pages have the same age). + +[[!meta robots="noindex, follow"]] diff --git a/doc/ikiwikiusers.mdwn b/doc/ikiwikiusers.mdwn index f750fb4b0..4a3e41e83 100644 --- a/doc/ikiwikiusers.mdwn +++ b/doc/ikiwikiusers.mdwn @@ -40,9 +40,7 @@ Projects & Organizations * [Chaos Computer Club Düsseldorf](https://www.chaosdorf.de) * [monkeysphere](http://web.monkeysphere.info/) * [The Walden Effect](http://www.waldeneffect.org/) -* The support pages for [Trinity Centre for High Performance Computing](http://www.tchpc.tcd.ie/support/) * [St Hugh of Lincoln Catholic Primary School in Surrey](http://www.sthugh-of-lincoln.surrey.sch.uk/) -* [Pigro Network](http://www.pigro.net) is running a hg based ikiwiki. (And provides ikiwiki hosting for $10/m.) * [Cosin Homepage](http://cosin.ch) uses an Ikiwiki with a subversion repository. * [Bosco Free Orienteering Software](http://bosco.durcheinandertal.ch) * [MIT Student Information Processing Board](http://sipb.mit.edu/) @@ -51,6 +49,11 @@ Projects & Organizations * [The Philolexian Society of Columbia University](http://www.columbia.edu/cu/philo/) * [Fachschaft Informatik HU Berlin](http://fachschaft.informatik.hu-berlin.de/) * [Wetknee Books](http://www.wetknee.com/) +* [IPOL Image Processing On Line](http://www.ipol.im) +* [Debian Costa Rica](http://cr.debian.net/) +* [Fvwm Wiki](http://fvwmwiki.xteddy.org) +* [Serialist](http://serialist.net/)'s static pages (documentation, blog). We actually have ikiwiki generate its static content as HTML fragments using a modified page.tmpl template, and then the FastCGI powering our site grabs those fragments and embeds them in the standard dynamic site template. +* [Banu](https://www.banu.com/) Personal sites and blogs ======================== @@ -134,6 +137,12 @@ Personal sites and blogs * [Walden Effect](http://waldeneffect.org) * [Avian Aqua Miser](http://www.avianaquamiser.com/) * [Cosmic Cookout](http://www.cosmiccookout.com/) +* [Backyard Deer](http://www.backyarddeer.com/) +* [Alex Ghitza homepage and blog](http://aghitza.org/) +* [Andreas's homepage](http://0x7.ch/) - Ikiwiki, Subversion and CSS template +* [Chris Dombroski's boring bliki](https://www.icanttype.org/) +* [Josh Triplett's homepage](http://joshtriplett.org/) - Git backend with the CGI disabled, to publish a static site with the convenience of ikiwiki. +* [Gustaf Thorslund's blog](http://blog.thorslund.org) Please feel free to add your own ikiwiki site! diff --git a/doc/index.mdwn b/doc/index.mdwn index 732cf7a89..06acc9cec 100644 --- a/doc/index.mdwn +++ b/doc/index.mdwn @@ -24,5 +24,5 @@ The [[forum]] is open for discussions. [[Bugs]], [[TODO]] items, [[wishlist]] items, and [[patches|patch]] can be submitted and tracked using this wiki. -ikiwiki is developed by [[Joey]] and many contributors, +Ikiwiki is developed by [[Joey]] and many contributors, and is [[FreeSoftware]]. diff --git a/doc/news/version_3.20091113.mdwn b/doc/news/version_3.20091113.mdwn deleted file mode 100644 index 579174011..000000000 --- a/doc/news/version_3.20091113.mdwn +++ /dev/null @@ -1,18 +0,0 @@ -ikiwiki 3.20091113 released with [[!toggle text="these changes"]] -[[!toggleable text=""" - * underlay: Fix example values put in setup file to be array - references. - * underlay: Avoid crashing if lists of underlays (or template - directories) are not configured. - * Moved the postscan hook to run on the raw html of a page, before - the template is filled out. This improves the search plugin's indexing, - since it will not include navigational elements from the page template - or sidebar. - * localstyle: New plugin, allows overrding the toplevel local.css - with one that is closer to a page. - * httpauth: Add cgiauthurl setting that can be used to do http basic auth - only when ikiwiki needs authentication, rather than for any access to - the cgi/wiki. - * inline: Do not generate feeds for nested inlines. - * inline: Allow direct inclusion of non-page files in raw mode. - * inline: Fix display of all pages when archive=yes or show=0 are used."""]] diff --git a/doc/news/version_3.20091202.mdwn b/doc/news/version_3.20091202.mdwn deleted file mode 100644 index 60f17fe63..000000000 --- a/doc/news/version_3.20091202.mdwn +++ /dev/null @@ -1,17 +0,0 @@ -ikiwiki 3.20091202 released with [[!toggle text="these changes"]] -[[!toggleable text=""" - * meta: Generate meta description tags even when the html scrubber is - enabled. - * meta: Allow use of DESCRIPTION in templates to get at the meta description - value. (Thanks, NicolasLimare) - * inline: Use caching of inlined pages to speed up builds of inlines that - include feeds. Speedup of about 25% for small inlines; could be much - larger for inlines of many, or complex pages. - * Added (incomplete) Turkish po file. Closes: #[556744](http://bugs.debian.org/556744) - Thanks, Recai Oktaş - * date: New plugin that allows inserting date directives that expand to - pretty-printed dates, using the same formatting as used for page - modification date display, etc. - * htmllink: Allow a title attribute to be specified. - * calendar: Add title attributes for all links in the calendars. - * calendar: Fix month wraparound error that broke in December."""]]
\ No newline at end of file diff --git a/doc/news/version_3.20091218.mdwn b/doc/news/version_3.20091218.mdwn deleted file mode 100644 index 224e81c4e..000000000 --- a/doc/news/version_3.20091218.mdwn +++ /dev/null @@ -1,11 +0,0 @@ -ikiwiki 3.20091218 released with [[!toggle text="these changes"]] -[[!toggleable text=""" - * Add complete Spanish basewiki translation done by Fernando Gonzalez de - Requena. - * Improve javascript onload handling. - * monotone: Deal with format change in version 0.45. - (Thanks, Richard Levitte) - * cvs: Add missing bit to Automator. - * attachment: Fix reversion in attachment sorting by age. - * Fix utf-8 problems in rename, remove, attachment, 404, sourcepage, and - goto."""]]
\ No newline at end of file diff --git a/doc/news/version_3.20100102.3.mdwn b/doc/news/version_3.20100102.3.mdwn deleted file mode 100644 index b8f61978c..000000000 --- a/doc/news/version_3.20100102.3.mdwn +++ /dev/null @@ -1,21 +0,0 @@ -ikiwiki 3.20100102.3 released with [[!toggle text="these changes"]] -[[!toggleable text=""" - Happy palindrome day! - - * pagestats: Add show parameter. Closes: #[562129](http://bugs.debian.org/562129) (David Paleino) - * toc: Add startlevel parameter. (kerravonsen) - * Remove example ikiwiki setup file from the Debian package. This - re-enables linking to /usr/share/ikiwiki/examples which has the - example sites also used by auto-blog.setup. The example setup file - can be generated at any time using ikiwiki --dumpsetup so I do - not see a reason to ship it. Closes: #[562183](http://bugs.debian.org/562183) - * Use env hack in python scripts. - * comments: Add a checksum to the name of comment pages, to - avoid merge conflicts when comments are posted to two branches of a - site. - * linkmap: Add option to omit disconnected pages from the map. - * inline: Fix bug that limited displayed pages when feedshow was - specified w/o show. - * Fix several places that did not properly handle capitalization of - the discussionpage setting. Specifically, fixes discussion actions - on discussion pages, and unbreaks the opendiscussion plugin."""]] diff --git a/doc/news/version_3.20100212.mdwn b/doc/news/version_3.20100212.mdwn new file mode 100644 index 000000000..3dcfe5f84 --- /dev/null +++ b/doc/news/version_3.20100212.mdwn @@ -0,0 +1,26 @@ +ikiwiki 3.20100212 released with [[!toggle text="these changes"]] +[[!toggleable text=""" + * template: Preprocess parameters before htmlizing. + * img: Fix a bug that could taint @links with undef values. + * setup automator: Configure Term::Readline to use bold for prompt, rather + than default underline. Closes: #[517656](http://bugs.debian.org/517656) + * Allow jumping directly into account registration process by going to + ikiwiki.cgi?do=register + * Improve display of openid in preferences page. + * Add link to userpage (or creation link) to top of preferences page. + * opendiscussion: This plugin will also now allow posting comments + to otherwise locked-down sites. + * auto-blog.setup: Lock all pages, so only admin can post to the blog + by default, and enable opendiscussion so others can comment. + * Fix color and format plugins to appear in the websetup interface. + * amazon\_s3: Fix to support the EU S3 datacenter, which is more picky + about attempts to create already existing buckets. + * httpauth: When cgiauthurl is configured, httpauth can now be used + alongside other authentication methods (like openid or anonok). Rather + than always redirect to the cgiauthurl for authentication, there is now + a button on the login form to use it. + * httpauth: Add httpauth\_pagespec setting that can be used to limit + pages to only being edited via users authed with httpauth. + * Allow globs to be used in user() pagespecs. + * Group related plugins into sections in the setup file, and drop + unused rcs plugins from the setup file."""]]
\ No newline at end of file diff --git a/doc/news/version_3.20100302.mdwn b/doc/news/version_3.20100302.mdwn new file mode 100644 index 000000000..f439b1b23 --- /dev/null +++ b/doc/news/version_3.20100302.mdwn @@ -0,0 +1,12 @@ +ikiwiki 3.20100302 released with [[!toggle text="these changes"]] +[[!toggleable text=""" + * comments: Display number of comments in comment action link. + * Rebuild wikis on upgrade to this version to get the comment counts + added to existing pages. + * Loosen regexp, to allow empty quoted parameters in directives. + * Add force\_overwrite setting to make setup automator overwrite existing + files/directories. + * Fix admin openid detection in setup automator, and avoid prompting + for a password. + * Add new --clean option; this makes ikiwiki remove all built + files in the destdir, as well as wrappers and the .ikiwiki directory."""]]
\ No newline at end of file diff --git a/doc/news/version_3.20100312.mdwn b/doc/news/version_3.20100312.mdwn new file mode 100644 index 000000000..10c34425d --- /dev/null +++ b/doc/news/version_3.20100312.mdwn @@ -0,0 +1,16 @@ +ikiwiki 3.20100312 released with [[!toggle text="these changes"]] +[[!toggleable text=""" + * Fix utf8 issues in calls to md5\_hex. + * moderatedcomments: Added moderate\_pagespec that can be used + to control which users or comment locations are moderated. + This can be used, just for example, to moderate "user(http://myopenid.com/*)" + if you're getting a lot of spammers from one particular openid + provider (who should perhaps answer your emails about them), + while not moderating other users. + * moderatedcomments: The moderate\_users setting is deprecated. Instead, + set moderate\_pagespec to "!admin()" or "user(*)". + * Fix missing span on recentchanges page template. + * search: Avoid '$' in the wikiname appearing unescaped on omega's + query template, where it might crash omega. + * htmlscrubber: Security fix: In data:image/* uris, only allow a few + whitelisted image types. No svg."""]]
\ No newline at end of file diff --git a/doc/news/version_3.20100403.mdwn b/doc/news/version_3.20100403.mdwn new file mode 100644 index 000000000..3e9063028 --- /dev/null +++ b/doc/news/version_3.20100403.mdwn @@ -0,0 +1,30 @@ +ikiwiki 3.20100403 released with [[!toggle text="these changes"]] +[[!toggleable text=""" + * websetup: Add websetup\_unsafe to allow marking other settings + as unsafe. + * Improve openid url munging; do not display anchors and cgi parameters, + as used by yahoo and google urls. + * Add complete German basewiki and directives translation done by + Sebastian Kuhnert. + * Add a include setting, which can be used to make ikiwiki process + wiki source files, such as .htaccess, that would normally be skipped + for security or other reasons. Closes: #[447267](http://bugs.debian.org/447267) + (Thanks to Aaron Wilson for the original patch.) + * Add support for setup files written in YAML. + * Add --set-yaml switch for setting more complex config file options. + * filecheck: Fix bugs that prevented the pagespecs from matching when + not called by attachment plugin. + * Fix incorrect influence info returned by a failing link() pagespec, + that could lead to bad dependency handling in certain situations. + * Add preprocessed 'use lib' line to ikiwiki-transition and ikiwiki-calendar + if necessary for unusual install. + * auto-blog.setup: Set tagbase by default, since most bloggers will want it. + * Allow wrappers to be built using tcc. (Workaround #452876) + * openid: Use Openid Simple Registration or OpenID Attribute Exchange + to get the user's email address and username. (Neither is yet + used, but they are available in the session object now.) + * page.tmpl: Add Cache-Control must-revalidate to ensure that users + (especially of Firefox) see fresh page content. + * htmlscrubber: Allow colons in urls after '?' + * template: Search for templates in the templatedir, if they are not + found as pages in the wiki."""]] diff --git a/doc/plugins/404.mdwn b/doc/plugins/404.mdwn index ad332ee04..53dace3c9 100644 --- a/doc/plugins/404.mdwn +++ b/doc/plugins/404.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=404 author="[[Simon_McVittie|smcv]]"]] -[[!tag type/useful]] +[[!tag type/web]] This plugin lets you use the IkiWiki CGI script as an Apache 404 handler, to give the behaviour of various other wiki engines where visiting a diff --git a/doc/plugins/aggregate.mdwn b/doc/plugins/aggregate.mdwn index e2efcd83f..bb828b05c 100644 --- a/doc/plugins/aggregate.mdwn +++ b/doc/plugins/aggregate.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=aggregate author="[[Joey]]"]] -[[!tag type/useful]] +[[!tag type/special-purpose]] This plugin allows content from other feeds to be aggregated into the wiki. To specify feeds to aggregate, use the diff --git a/doc/plugins/autoindex.mdwn b/doc/plugins/autoindex.mdwn index 03e2d12f3..d1133e4f5 100644 --- a/doc/plugins/autoindex.mdwn +++ b/doc/plugins/autoindex.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=autoindex core=0 author="[[Joey]]"]] -[[!tag type/useful]] +[[!tag type/special-purpose]] This plugin searches for [[SubPages|ikiwiki/subpage]] with a missing parent page, and generates the parent pages. The generated page content is diff --git a/doc/plugins/calendar.mdwn b/doc/plugins/calendar.mdwn index bc1bc6c71..76e718a3b 100644 --- a/doc/plugins/calendar.mdwn +++ b/doc/plugins/calendar.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=calendar author="[[ManojSrivastava]]"]] -[[!tag type/chrome]] +[[!tag type/widget]] This plugin provides a [[ikiwiki/directive/calendar]] [[ikiwiki/directive]]. The directive displays a calendar, similar to the typical calendars shown on @@ -14,6 +14,7 @@ customization. * `month-calendar` - The month calendar as a whole. * `month-calendar-head` - The head of the month calendar (ie,"March"). +* `month-calendar-arrow` - Arrow pointing to previous/next month. * `month-calendar-day-head` - A column head in the month calendar (ie, a day-of-week abbreviation). * `month-calendar-day-noday`, `month-calendar-day-link`, @@ -27,6 +28,7 @@ customization. weekends. * `year-calendar` - The year calendar as a whole. * `year-calendar-head` - The head of the year calendar (ie, "2007"). +* `year-calendar-arrow` - Arrow pointing to previous/next year. * `year-calendar-subhead` - For example, "Months". * `year-calendar-month-link`, `year-calendar-month-nolink`, `year-calendar-month-future`, `year-calendar-this-month` - The month diff --git a/doc/plugins/color.mdwn b/doc/plugins/color.mdwn index dbb8b870c..d639bf563 100644 --- a/doc/plugins/color.mdwn +++ b/doc/plugins/color.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=color core=0 author="[[ptecza]]"]] -[[!tag type/chrome]] +[[!tag type/widget]] This plugin provides a [[ikiwiki/directive/color]] [[ikiwiki/directive]]. The directive can be used to color a piece of text on a page. diff --git a/doc/plugins/comments.mdwn b/doc/plugins/comments.mdwn index b6d4d252b..775ef75a0 100644 --- a/doc/plugins/comments.mdwn +++ b/doc/plugins/comments.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=comments author="[[Simon_McVittie|smcv]]"]] -[[!tag type/useful]] +[[!tag type/web]] This plugin adds "blog-style" comments. Unlike the wiki-style freeform Discussion pages, these comments are posted by a simple form, cannot later @@ -14,8 +14,8 @@ authorship should hopefully be unforgeable by CGI users. The intention is that on a non-wiki site (like a blog) you can lock all pages for admin-only access, then allow otherwise unprivileged (or perhaps even anonymous) users to comment on posts. See the documentation of the -[[lockedit]] and [[anonok]] pages for details on locking down a wiki so -users can only post comments. +[[opendiscussion]], [[lockedit]] and [[anonok]] pages for details on locking +down a wiki so readers can only post comments. Individual comments are stored as internal-use pages named something like `page/comment_1`, `page/comment_2`, etc. These pages internally use a diff --git a/doc/plugins/conditional.mdwn b/doc/plugins/conditional.mdwn index 95ffb2764..27a99bb7c 100644 --- a/doc/plugins/conditional.mdwn +++ b/doc/plugins/conditional.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=conditional core=1 author="[[Joey]]"]] -[[!tag type/format]] +[[!tag type/special-purpose]] This plugin provides the [[ikiwiki/directive/if]] [[ikiwiki/directive]]. With this directive, you can make text be conditionally displayed on a page. diff --git a/doc/plugins/conditional/discussion.mdwn b/doc/plugins/conditional/discussion.mdwn index 629d05940..6e84fdfc1 100644 --- a/doc/plugins/conditional/discussion.mdwn +++ b/doc/plugins/conditional/discussion.mdwn @@ -1,3 +1,28 @@ +## Conditional broken? + +Using \[\[!if test="tagged(plugin)" then="= Tagged as plugin =" else="*No plugins found*"]] on this wiki *should* present the 'Tagged as plugin' heading, instead it emits 'no plugins found'. Is the conditional plugin currently broken for tags or am I misusing it? Thanks. + +-- Thiana + +> This wiki has no page named "plugin", so nothing links to it; tags are a species of link +> so tagging a large number of pages with a tag that doesn't exist (which change has +> been reverted) doesn't make the pagespec match. It would if the tag's page existed. --[[Joey]] + +>> So if I understand this correctly... Assuming the tags Tag_A and Tag_B, the existence of +>> @wiki-home@/tags/Tag_A.creole, and a number of files with a \[\[!tag Tag_A Tag_B]] the +>> following is correct? +>> +>> * \[\[!if test="tagged(Tag_A)" then="OK" else="Fail"]] => OK +>> * \[\[!if test="tagged(Tag_B)" then="OK" else="Fail"]] => Fail +>> * \[\[!if test="tagged(Tag_A) and tagged(Tag_B)" then="OK" else="Fail"]] => Fail +>> +>> Is that the expected behaviour? If so, that's not what I'm seeing here since they all result +>> in a Fail. If not, what exactly is wrong with those conditionals? Thanks. +>> +>> -- Thiana + +---- + Would there be a way for this plugin to emit fewer blank lines (i.e. *none at all*)? For example, having a look at [this page](http://www.bddebian.com/~wiki/Hurd/)'s sidebar. diff --git a/doc/plugins/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn new file mode 100644 index 000000000..103e061e5 --- /dev/null +++ b/doc/plugins/contrib/field/discussion.mdwn @@ -0,0 +1,326 @@ +Having tried out `field`, some comments (from [[smcv]]): + +The general concept looks great. + +The `pagetemplate` hook seems quite namespace-polluting: on a site containing +a list of books, I'd like to have an `author` field, but that would collide +with IkiWiki's use of `<TMPL_VAR AUTHOR>` for the author of the *page* +(i.e. me). Perhaps it'd be better if the pagetemplate hook was only active for +`<TMPL_VAR FIELD_AUTHOR>` or something? (For those who want the current +behaviour, an auxiliary plugin would be easy.) + +> No, please. The idea is to be *able* to override field names if one wishes to, and choose, for yourself, non-colliding field names if one wishes not to. I don't wish to lose the power of being able to, say, define a page title with YAML format if I want to, or to write a site-specific plugin which calculates a page title, or other nifty things. +>It's not like one is going to lose the fields defined by the meta plugin; if "author" is defined by \[[!meta author=...]] then that's what will be found by "field" (provided the "meta" plugin is registered; that's what the "field_register" option is for). +>--[[KathrynAndersen]] + +>> Hmm. I suppose if you put the title (or whatever) in the YAML, then +>> "almost" all the places in IkiWiki that respect titles will do the +>> right thing due to the pagetemplate hook, with the exception being +>> anything that has special side-effects inside `meta` (like `date`), +>> or anything that looks in `$pagestate{foo}{meta}` directly +>> (like `map`). Is your plan that `meta` should register itself by +>> default, and `map` and friends should be adapted to +>> work based on `getfield()` instead of `$pagestate{foo}{meta}`, then? + +>>> Based on `field_get_value()`, yes. That would be my ideal. Do you think I should implement that as an ikiwiki branch? --[[KathrynAndersen]] + +>>>> This doesn't solve cases where certain fields are treated specially; for +>>>> instance, putting a `\[[!meta permalink]]` on a page is not the same as +>>>> putting it in `ymlfront` (in the latter case you won't get your +>>>> `<link>` header), and putting `\[[!meta date]]` is not the same as putting +>>>> `date` in `ymlfront` (in the latter case, `%pagectime` won't be changed). +>>>> +>>>> One way to resolve that would be to have `ymlfront`, or similar, be a +>>>> front-end for `meta` rather than for `field`, and call +>>>> `IkiWiki::Plugin::meta::preprocess` (or a refactored-out function that's +>>>> similar). +>>>> +>>>> There are also some cross-site scripting issues (see below)... --[[smcv]] + +>> (On the site I mentioned, I'm using an unmodified version of `field`, +>> and currently working around the collision by tagging books' pages +>> with `bookauthor` instead of `author` in the YAML.) --s + +>> Revisiting this after more thought, the problem here is similar to the +>> possibility that a wiki user adds a `meta` shortcut +>> to [[shortcuts]], or conversely, that a plugin adds a `cpan` directive +>> that conflicts with the `cpan` shortcut that pages already use. (In the +>> case of shortcuts, this is resolved by having plugin-defined directives +>> always win.) For plugin-defined meta keywords this is the plugin +>> author's/wiki admin's problem - just don't enable conflicting plugins! - +>> but it gets scary when you start introducing things like `ymlfront`, which +>> allow arbitrary, wiki-user-defined fields, even ones that subvert +>> other plugins' assumptions. +>> +>> The `pagetemplate` hook is particularly alarming because page templates are +>> evaluated in many contexts, not all of which are subject to the +>> htmlscrubber or escaping; because the output from `field` isn't filtered, +>> prefixed or delimited, when combined with an arbitrary-key-setting plugin +>> like `ymlfront` it can interfere with other plugins' expectations +>> and potentially cause cross-site scripting exploits. For instance, `inline` +>> has a `pagetemplate` hook which defines the `FEEDLINKS` template variable +>> to be a blob of HTML to put in the `<head>` of the page. As a result, this +>> YAML would be bad: +>> +>> --- +>> FEEDLINKS: <script>alert('code injection detected')</script> +>> --- +>> +>> (It might require a different case combination due to implementation +>> details, I'm not sure.) +>> +>> It's difficult for `field` to do anything about this, because it doesn't +>> know whether a field is meant to be plain text, HTML, a URL, or something +>> else. +>> +>> If `field`'s `pagetemplate` hook did something more limiting - like +>> only emitting template variables starting with `field_`, or from some +>> finite set, or something - then this would cease to be a problem, I think? +>> +>> `ftemplate` and `getfield` don't have this problem, as far as I can see, +>> because their output is in contexts where the user could equally well have +>> written raw HTML directly; the user can cause themselves confusion, but +>> can't cause harmful output. --[[smcv]] + +From a coding style point of view, the `$CamelCase` variable names aren't +IkiWiki style, and the `match_foo` functions look as though they could benefit +from being thin wrappers around a common `&IkiWiki::Plugin::field::match` +function (see `meta` for a similar approach). + +I think the documentation would probably be clearer in a less manpage-like +and more ikiwiki-like style? + +> I don't think ikiwiki *has* a "style" for docs, does it? So I followed the Perl Module style. And I'm rather baffled as to why having the docs laid out in clear sections... make them less clear. --[[KathrynAndersen]] + +>> I keep getting distracted by the big shouty headings :-) +>> I suppose what I was really getting at was that when this plugin +>> is merged, its docs will end up split between its plugin +>> page, [[plugins/write]] and [[ikiwiki/PageSpec]]; on some of the +>> contrib plugins I've added I've tried to separate the docs +>> according to how they'll hopefully be laid out after merge. --s + +If one of my branches from [[todo/allow_plugins_to_add_sorting_methods]] is +accepted, a `field()` cmp type would mean that [[plugins/contrib/report]] can +stop reimplementing sorting. Here's the implementation I'm using, with +your "sortspec" concept (a sort-hook would be very similar): if merged, +I think it should just be part of `field` rather than a separate plugin. + + # Copyright © 2010 Simon McVittie, released under GNU GPL >= 2 + package IkiWiki::Plugin::fieldsort; + use warnings; + use strict; + use IkiWiki 3.00; + use IkiWiki::Plugin::field; + + sub import { + hook(type => "getsetup", id => "fieldsort", call => \&getsetup); + } + + sub getsetup () { + return + plugin => { + safe => 1, + rebuild => undef, + }, + } + + package IkiWiki::SortSpec; + + sub cmp_field { + if (!length $_[0]) { + error("sort=field requires a parameter"); + } + + my $left = IkiWiki::Plugin::field::field_get_value($_[0], $a); + my $right = IkiWiki::Plugin::field::field_get_value($_[0], $b); + + $left = "" unless defined $left; + $right = "" unless defined $right; + return $left cmp $right; + } + + 1; + +---- + +Disclaimer: I've only looked at this plugin and ymlfront, not other related +stuff yet. (I quite like ymlfront, so I looked at this as its dependency. :) +I also don't want to annoy you with a lot of design discussion +if your main goal was to write a plugin that did exactly what you wanted. + +My first question is: Why we need another plugin storing metadata +about the page, when we already have the meta plugin? Much of the +complication around the field plugin has to do with it accessing info +belonging to the meta plugin, and generalizing that to be able to access +info stored by other plugins too. (But I don't see any other plugins that +currently store such info). Then too, it raises points of confusion like +smcv's discuission of field author vs meta author above. --[[Joey]] + +> The point is exactly in the generalization, to provide a uniform interface for accessing structured data, no matter what the source of it, whether that be the meta plugin or some other plugin. + +> There were a few reasons for this: + +>1. In converting my site over from PmWiki, I needed something that was equivalent to PmWiki's Page-Text-Variables (which is how PmWiki implements structured data). +>2. I also wanted an equivalent of PmWiki's Page-Variables, which, rather than being simple variables, are the return-value of a function. This gives one a lot of power, because one can do calculations, derive one thing from another. Heck, just being able to have a "basename" variable is useful. +>3. I noticed that in the discussion about structured data, it was mired down in disagreements about what form the structured data should take; I wanted to overcome that hurdle by decoupling the form from the content. +>4. I actually use this to solve (1), because, while I do use ymlfront, initially my pages were in PmWiki format (I wrote (another) unreleased plugin which parses PmWiki format) including PmWiki's Page-Text-Variables for structured data. So I needed something that could deal with multiple formats. + +> So, yes, it does cater to mostly my personal needs, but I think it is more generally useful, also. +> --[[KathrynAndersen]] + +>> Is it fair to say, then, that `field`'s purpose is to take other +>> plugins' arbitrary per-page data, and present it as a single +>> merged/flattened string => string map per page? From the plugins +>> here, things you then use that merged map for include: +>> +>> * sorting - stolen by [[todo/allow_plugins_to_add_sorting_methods]] +>> * substitution into pages with Perl-like syntax - `getfield` +>> * substitution into wiki-defined templates - the `pagetemplate` +>> hook +>> * substitution into user-defined templates - `ftemplate` +>> +>> As I mentioned above, the flattening can cause collisions (and in the +>> `pagetemplate` case, even security problems). +>> +>> I wonder whether conflating Page Text Variables with Page Variables +>> causes `field` to be more general than it needs to be? +>> To define a Page Variable (function-like field), you need to write +>> a plugin containing that Perl function; if we assume that `field` +>> or something resembling it gets merged into ikiwiki, then it's +>> reasonable to expect third-party plugins to integrate with whatever +>> scaffolding there is for these (either in an enabled-by-default +>> plugin that most people are expected to leave enabled, like `meta` +>> now, or in the core), and it doesn't seem onerous to expect each +>> plugin that wants to participate in this mechanism to have code to +>> do so. While it's still contrib, `field` could just have a special case +>> for the meta plugin, rather than the converse? +>> +>> If Page Text Variables are limited to being simple strings as you +>> suggest over in [[forum/an_alternative_approach_to_structured_data]], +>> then they're functionally similar to `meta` fields, so one way to +>> get their functionality would be to extend `meta` so that +>> +>> \[[!meta badger="mushroom"]] +>> +>> (for an unrecognised keyword `badger`) would store +>> `$pagestate{$page}{meta}{badger} = "mushroom"`? Getting this to +>> appear in templates might be problematic, because a naive +>> `pagetemplate` hook would have the same problem that `field` combined +>> with `ymlfront` currently does. +>> +>> One disadvantage that would appear if the function-like and +>> meta-like fields weren't in the same namespace would be that it +>> wouldn't be possible to switch a field from being meta-like to being +>> function-like without changing any wiki content that referenced it. +>> +>> Perhaps meta-like fields should just *be* `meta` (with the above +>> enhancement), as a trivial case of function-like fields? That would +>> turn `ymlfront` into an alternative syntax for `meta`, I think? +>> That, in turn, would hopefully solve the special-fields problem, +>> by just delegating it to meta. I've been glad of the ability to define +>> new ad-hoc fields with this plugin without having to write an extra plugin +>> to do so (listing books with a `bookauthor` and sorting them by +>> `"field(bookauthor) title"`), but that'd be just as easy if `meta` +>> accepted ad-hoc fields? +>> +>> --[[smcv]] + +>>> Your point above about cross-site scripting is a valid one, and something I +>>> hadn't thought of (oops). + +>>> I still want to be able to populate pagetemplate templates with field, because I +>>> use it for a number of things, such as setting which CSS files to use for a +>>> given page, and, as I said, for titles. But apart from the titles, I +>>> realize I've been setting them in places other than the page data itself. +>>> (Another unreleased plugin, `concon`, uses Config::Context to be able to +>>> set variables on a per-site, per-directory and a per-page basis). + +>>> The first possible solution is what you suggested above: for field to only +>>> set values in pagetemplate which are prefixed with *field_*. I don't think +>>> this is quite satisfactory, since that would still mean that people could +>>> put un-scrubbed values into a pagetemplate, albeit they would be values +>>> named field_foo, etc. --[[KathrynAndersen]] + +>>>> They can already do similar; `PERMALINK` is pre-sanitized to +>>>> ensure that it's a "safe" URL, but if an extremely confused wiki admin was +>>>> to put `COPYRIGHT` in their RSS/Atom feed's `<link>`, a malicious user +>>>> could put an unsafe (e.g. Javascript) URL in there (`COPYRIGHT` *is* +>>>> HTML-scrubbed, but "javascript:alert('pwned!')" is just text as far as a +>>>> HTML sanitizer is concerned, so it passes straight through). The solution +>>>> is to not use variables in situations where that variable would be +>>>> inappropriate. Because `field` is so generic, the definition of what's +>>>> appropriate is difficult. --[[smcv]] + +>>> An alternative solution would be to classify field registration as "secure" +>>> and "insecure". Sources such as ymlfront would be insecure, sources such +>>> as concon (or the $config hash) would be secure, since they can't be edited +>>> as pages. Then, when doing pagetemplate substitution (but not ftemplate +>>> substitution) the insecure sources could be HTML-escaped. +>>> --[[KathrynAndersen]] + +>>>> Whether you trust the supplier of data seems orthogonal to whether its value +>>>> is (meant to be) interpreted as plain text, HTML, a URL or what? +>>>> +>>>> Even in cases where you trust the supplier, you need to escape things +>>>> suitably for the context, not for security but for correctness. The +>>>> definition of the value, and the context it's being used in, changes the +>>>> processing you need to do. An incomplete list: +>>>> +>>>> * HTML used as HTML needs to be html-scrubbed if and only if untrusted +>>>> * URLs used as URLs need to be put through `safeurl()` if and only if +>>>> untrusted +>>>> * HTML used as plain text needs tags removed regardless +>>>> * URLs used as plain text are safe +>>>> * URLs or plain text used in HTML need HTML-escaping (and URLs also need +>>>> `safeurl()` if untrusted) +>>>> * HTML or plain text used in URLs need URL-escaping (and the resulting +>>>> URL might need sanitizing too?) +>>>> +>>>> I can't immediately think of other data types we'd be interested in beyond +>>>> text, HTML and URL, but I'm sure there are plenty. + +>>>>> But isn't this a problem with anything that uses pagetemplates? Or is +>>>>> the point that, with plugins other than `field`, they all know, +>>>>> beforehand, the names of all the fields that they are dealing with, and +>>>>> thus the writer of the plugin knows which treatment each particular field +>>>>> needs? For example, that `meta` knows that `title` needs to be +>>>>> HTML-escaped, and that `baseurl` doesn't. In that case, yes, I see the problem. +>>>>> It's a tricky one. It isn't as if there's only ever going to be a fixed set of fields that need different treatment, either. Because the site admin is free to add whatever fields they like to the page template (if they aren't using the default one, that is. I'm not using the default one myself). +>>>>> Mind you, for trusted sources, since the person writing the page template and the person providing the variable are the same, they themselves would know whether the value will be treated as HTML, plain text, or a URL, and thus could do the needed escaping themselves when writing down the value. + +>>>>> Looking at the content of the default `page.tmpl` let's see what variables fall into which categories: + +>>>>> * **Used as URL:** BASEURL, EDITURL, PARENTLINKS->URL, RECENTCHANGESURL, HISTORYURL, GETSOURCEURL, PREFSURL, OTHERLANGUAGES->URL, ADDCOMMENTURL, BACKLINKS->URL, MORE_BACKLINKS->URL +>>>>> * **Used as part of a URL:** FAVICON, LOCAL_CSS +>>>>> * **Needs to be HTML-escaped:** TITLE +>>>>> * **Used as-is (as HTML):** FEEDLINKS, RELVCS, META, PERCENTTRANSLATED, SEARCHFORM, COMMENTSLINK, DISCUSSIONLINK, OTHERLANGUAGES->PERCENT, SIDEBAR, CONTENT, COMMENTS, TAGS->LINK, COPYRIGHT, LICENSE, MTIME, EXTRAFOOTER + +>>>>> This looks as if only TITLE needs HTML-escaping all the time, and that the URLS all end with "URL" in their name. Unfortunately the FAVICON and LOCAL_CSS which are part of URLS don't have "URL" in their name, though that's fair enough, since they aren't full URLs. + +>>>>> --K.A. + +>>>> One reasonable option would be to declare that `field` takes text-valued +>>>> fields, in which case either consumers need to escape +>>>> it with `<TMPL_VAR FIELD_FOO ESCAPE=HTML>`, and not interpret it as a URL +>>>> without first checking `safeurl`), or the pagetemplate hook needs to +>>>> pre-escape. + +>>>>> Since HTML::Template does have the ability to do ESCAPE=HTML/URL/JS, why not take advantage of that? Some things, like TITLE, probably should have ESCAPE=HTML all the time; that would solve the "to escape or not to escape" problem that `meta` has with titles. After all, when one *sorts* by title, one doesn't really want HTML-escaping in it; only when one uses it in a template. -- K.A. + +>>>> Another reasonable option would be to declare that `field` takes raw HTML, +>>>> in which case consumers need to only use it in contexts that will be +>>>> HTML-scrubbed (but it becomes unsuitable for using as text - problematic +>>>> for text-based things like sorting or URLs, and not ideal for searching). +>>>> +>>>> You could even let each consumer choose how it's going to use the field, +>>>> by having the `foo` field generate `TEXT_FOO` and `HTML_FOO` variables? +>>>> --[[smcv]] + +>>>>> Something similar is already done in `template` and `ftemplate` with the `raw_` prefix, which determines whether the variable should have `htmlize` run over it first before the value is applied to the template. Of course, that isn't scrubbing or escaping, because with those templates, the scrubbing is done afterwards as part of the normal processing. + +>>> Another problem, as you point out, is special-case fields, such as a number of +>>> those defined by `meta`, which have side-effects associated with them, more +>>> than just providing a value to pagetemplate. Perhaps `meta` should deal with +>>> the side-effects, but use `field` as an interface to get the values of those special fields. + +>>> --[[KathrynAndersen]] diff --git a/doc/plugins/contrib/ftemplate/discussion.mdwn b/doc/plugins/contrib/ftemplate/discussion.mdwn new file mode 100644 index 000000000..1e0bca5d8 --- /dev/null +++ b/doc/plugins/contrib/ftemplate/discussion.mdwn @@ -0,0 +1,33 @@ +I initially thought this wasn't actually necessary - the combination +of [[plugins/template]] with [[plugins/contrib/field]]'s `pagetemplate` +hook ought to provide the same functionality. However, `template` +doesn't run `pagetemplate` hooks; a more general version of this +plugin would be to have a variant of `template` that runs `pagetemplate` +hooks (probably easiest to just patch `template` to implement a +second directive, or have a special parameter `run_hooks="yes"`, +or something). + +> I got the impression that `pagetemplate` hooks are intended to be completely independent of `template` variables; page-template is for the actual `page.tmpl` template, while `template` is for other templates which are used inside the page content. So I don't understand why one would need a run_hooks option. --[[KathrynAndersen]] + +>> `Render`, `inline`, `comments` and `recentchanges` run `pagetemplate` +>> hooks, as does anything that uses `IkiWiki::misctemplate`. From that +>> quick survey, it seems as though `template` is the only thing that +>> uses `HTML::Template` but *doesn't* run `pagetemplate` hooks? +>> +>> It just seems strange to me that `field` needs to have its own +>> variant of `template` (this), its own variant of `inline` (`report`), +>> and so on - I'd tend to lean more towards having `field` +>> enhance the existing plugins. I'm not an ikiwiki committer, +>> mind... Joey, your opinion would be appreciated! --[[smcv]] + +>>> I did it that way basically because I needed the functionality ASAP, and I didn't want to step on anyone's toes, so I made them as separate plugins. If Joey wants to integrate the functionality into IkiWiki proper, I would be very happy, but I don't want to put pressure on him. --[[KathrynAndersen]] + +Another missing thing is that `ftemplate` looks in +the "system" templates directories, not just in the wiki, but that +seems orthogonal (and might be a good enhancement to `template` anyway). +--[[smcv]] + +> Yes, I added that because I wanted the option of not having to make all my templates work as wiki pages also. --[[KathrynAndersen]] + +>> Joey has added support for +>> [[todo/user-defined_templates_outside_the_wiki]] now. --s diff --git a/doc/plugins/contrib/highlightcode.mdwn b/doc/plugins/contrib/highlightcode.mdwn index 8abb76583..f1df204bb 100644 --- a/doc/plugins/contrib/highlightcode.mdwn +++ b/doc/plugins/contrib/highlightcode.mdwn @@ -1,6 +1,8 @@ [[!template id=plugin name=highlightcode author="[[sabr]]"]] [[!tag type/format]] +(An alternative to this plugin, [[plugins/highlight]], is now provided with IkiWiki. --[[smcv]]) + A small plugin to allow Ikiwiki to display source files complete with syntax highlighting. Files with recognized extensions (i.e. my-file.cpp) are be rendered just like any other Ikiwiki page. You can even edit your source files with Ikiwiki's editor. It uses the Syntax::Highlight::Engine::Kate Perl module to do the highlighting. diff --git a/doc/plugins/contrib/pod/discussion.mdwn b/doc/plugins/contrib/pod/discussion.mdwn new file mode 100644 index 000000000..9187b1350 --- /dev/null +++ b/doc/plugins/contrib/pod/discussion.mdwn @@ -0,0 +1,14 @@ +My one concern about this plugin is the `=for` markup in POD. + +> Some format names that formatters currently are known to +> accept include "roff", "man", "latex", "tex", "text", and "html". + +I don't know which of these [[!cpan Pod::Xhtml]] supports. If it currently +supports, or later support latex, that could be problimatic since that +could maybe be used to include files or run code. --[[Joey]] + +> I don't know, either; the documentation for [[!cpan Pod:Xhtml]] is silent on this subject. --[[KathrynAndersen]] + +>> I'm afraid the only approach is to audit the existing code in the perl +>> module(s), and then hope nothing is added to them later that opens a +>> security hole. --[[Joey]] diff --git a/doc/plugins/contrib/postal.mdwn b/doc/plugins/contrib/postal.mdwn index b2f875393..c522f8bcb 100644 --- a/doc/plugins/contrib/postal.mdwn +++ b/doc/plugins/contrib/postal.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=postal author="[[DavidBremner]]"]] -[[!tag type/useful]] +[[!tag type/special-purpose]] The `postal` plugin allows users to send mail to a special address to comment on a page. It uses the [[mailbox]] diff --git a/doc/plugins/contrib/report.mdwn b/doc/plugins/contrib/report.mdwn index 7130bcb5f..c364d4a3a 100644 --- a/doc/plugins/contrib/report.mdwn +++ b/doc/plugins/contrib/report.mdwn @@ -18,7 +18,7 @@ IkiWiki::Plugin::report - Produce templated reports from page field data. This plugin provides the **report** directive. This enables one to report on the structured data ("field" values) of multiple pages; the output is formatted -via a template. This depends on the "field" plugin. +via a template. This depends on the [[plugins/contrib/field]] plugin. The pages to report on are selected by a PageSpec given by the "pages" parameter. The template is given by the "template" parameter. @@ -89,7 +89,7 @@ The "mood_summary" template might be like this: ## <TMPL_VAR NAME="HEADER1"> </TMPL_IF> ### <TMPL_VAR NAME="TITLE"> - (<TMPL_VAR NAME="DATE">) \[[<TMPL_VAR NAME="PAGE"]] + (<TMPL_VAR NAME="DATE">) \[[<TMPL_VAR NAME="PAGE">]] <TMPL_VAR NAME="DESCRIPTION"> ### Advanced Options diff --git a/doc/plugins/contrib/report/discussion.mdwn b/doc/plugins/contrib/report/discussion.mdwn new file mode 100644 index 000000000..e23a4ced4 --- /dev/null +++ b/doc/plugins/contrib/report/discussion.mdwn @@ -0,0 +1,75 @@ +Wow, this plugin does a lot... it seems to be `inline` (but without the feeds +or the ability to not have `archive="yes"`), plus part of +[[plugins/contrib/trail]], plus some sorting, plus an ingenious workaround +for template evaluation being relatively stateless. + +A large part of this plugin would just fall off if one of the versions of +"[[todo/allow_plugins_to_add_sorting_methods]]" was merged, which was a +large part of the idea of that feature request :-) To make use of that +you'd have to use `pagespec_match_list` in the trail case too, but that's +easy enough - just add `list => [@the_trail_pages]` to the arguments. + +Another large part would fall off if this plugin required, and internally +invoked, `inline` (like my `comments` plugin does) - `inline` runs +`pagetemplate` hooks, and in particular, it'll run the `field` hook. +Alternatively, this plugin could invoke `pagetemplate` hooks itself, +removing the special case for `field`. + +Perhaps the `headers` thing could migrate into inline somehow? That might +lead to making inline too big, though. + +> I think inline is *already* too big, honestly. --[[KathrynAndersen]] + +>> A fair point; perhaps my complaint should be that *inline* does +>> too many orthogonal things. I suppose the headers feature wouldn't +>> really make sense in an inline that didn't have `archive="yes"`, +>> so it'd make sense to recommend this plugin as a replacement +>> for inlining with archive=yes (for which I now realise "inline" +>> is the wrong verb anyway :-) ) --s + +>>> I think *inline* would be a bit less unwieldy if there was some way of factoring out the feed stuff into a separate plugin, but I don't know if that's possible. --K.A. + +Is the intention that the `trail` part is a performance hack, or a way +to select pages? How does it relate to [[todo/wikitrails]] or +[[plugins/contrib/trail]]? --[[smcv]] + +> The `trail` part is *both* a performance hack, and a way to select pages. I have over 5000 pages on my site, I need all the performance hacks I can get. +> For the performance hack, it is a way of reducing the need to iterate through every single page in the wiki in order to find matching pages. +> For the way-to-select-pages, yes, it is intended to be similar to [[todo/wikitrails]] and [[plugins/contrib/trail]] (and will be more similar with the new release which will be happening soon; it will add prev_* and next_* variables). +> The idea is that, rather than having to add special "trail" links on PageA to indicate that a page is part of the trail, +> it takes advantage of the `%links` hash, which already contains, for each page, an array of the links from that page to other pages. No need for special markup, just use what's there; a trail is defined as "all the pages linked to from page X", and since it's an array, it has an order already. +> But to avoid that being too limiting, one can use a `pages=...` pagespec to filter that list to a subset; only the pages one is interested in. +> And one can also sort it, if one so desires. +> --[[KathrynAndersen]] + +>> That's an interesting approach to trails; I'd missed the fact that +>> links are already ordered. +>> +>> This does have the same problems as tags, though: see +>> [[bugs/tagged()_matching_wikilinks]] and +>> [[todo/matching_different_kinds_of_links]]. I suppose the question +>> now is whether new code should be consistent with `tag` (and +>> potentially be fixed at the same time as tag itself), or try to +>> avoid those problems? +>> +>> The combination of `trail` with another pagespec in this plugin +>> does provide a neat way for it to work around having unwanted +>> pages in the report, by limiting by a suitable tag or subdirectory +>> or something. --s + +>>> Either that, or somehow combine tagging with fields, such that one could declare a tag, and it would create both a link and a field with a given value. (I've been working on something like that, but it still has bugs). +>>> That way, the test for whether something is tagged would be something like "link(tag/foo) and field(tag foo)". +>>> --K.A. + +>>>> I can see that this'd work well for 1:1 relationships like next +>>>> and previous, but I don't think that'd work for pages with more than +>>>> one tag - as far as I can see, `field`'s data model is that each +>>>> page has no more than one value for each field? +>>>> [[todo/Matching_different_kinds_of_links]] has some thoughts about +>>>> how it could be implemented, though. --s + +>>>>> You have a point there. I'm not sure what would be better: to add the concept of arrays/sets to `field`, or to think of tags as a special case. Problem is, I find tags as they currently exist to be too limiting. I prefer something that can be used for Faceted Tagging <http://en.wikipedia.org/wiki/Faceted_classification>; that is, things like Author:Fred Nurk, Genre:Historical, Rating:Good, and so on. Of course, that doesn't mean that each tag is limited to only one value, either; just to take the above examples, something might have more than one author, or have multiple genres (such as Historical + Romance). + +>>>>> It might be that adding arrays to the `field` plugin is a good way to go: after all, even though field=value is the most common, with the flexibility of things like YAML, one could define all sorts of things. What I'm not so sure about is how to return the values when queried, since some things would be expecting scalars all the time. Ah, perhaps I could use wantarray? +>>>>> Is there a way of checking a HTML::Template template to see if it expecting an array for a particular value? +>>>>> --[[KathrynAndersen]] diff --git a/doc/plugins/contrib/xslt/discussion.mdwn b/doc/plugins/contrib/xslt/discussion.mdwn index 9cda02f88..72cce083c 100644 --- a/doc/plugins/contrib/xslt/discussion.mdwn +++ b/doc/plugins/contrib/xslt/discussion.mdwn @@ -20,3 +20,30 @@ possible. Can it also read other arbitrary files, run other programs, etc? > For the second point, I think the main concern would be resource usage. XSLT is a pretty limited language; it can read other XML files, but it can't run other programs so far as I know. > -- [[KathrynAndersen]] + +>> XSLT is, indeed, a Turing-complete programming language. + However, [XML::LibXSLT][] provides a set of functions to help + to minimize the damage that may be caused by running a random + program. + +>> In particular, `max_depth ()` allows for the maximum + recursion depth to be set, while + `read_file ()`, `write_file ()`, `create_dir ()`, + `read_net ()` and `write_net ()` + are the callbacks that allow any of the possible file + operations to be denied. + +>> To be honest, I'd prefer for the `read_file ()` callback to + only grant access to the files below the Ikiwiki source + directory, and for all the `write_`… and + …`_net` callbacks to deny the access unconditionally. + +>> One more wishlist item: allow the set of locations to take + `.xsl` files from to be preconfigured, so that, e. g., + one could allow (preasumably trusted) system stylesheets, + while disallowing any stylesheets that are placed on the Wiki + itself. + +>> — Ivan Shmakov, 2010-03-28Z. + +[XML::LibXSLT]: http://search.cpan.org/~PAJAS/XML-LibXSLT/LibXSLT.pm diff --git a/doc/plugins/contrib/ymlfront/discussion.mdwn b/doc/plugins/contrib/ymlfront/discussion.mdwn new file mode 100644 index 000000000..3ad02af29 --- /dev/null +++ b/doc/plugins/contrib/ymlfront/discussion.mdwn @@ -0,0 +1,11 @@ +My field-etc branch in git://git.pseudorandom.co.uk/git/smcv/ikiwiki.git (gitweb: +<http://git.pseudorandom.co.uk/smcv/ikiwiki.git?a=shortlog;h=refs/heads/field-etc>) +has some fixes for compatibility with old YAML modules, mostly done by imitating +Joey's code in IkiWiki::Setup::Yaml. Please consider merging :-) --[[smcv]] + +> I would if I could *find* it. I checked out the "field-etc" branch, but I can't find the plugins in question under IkiWiki/Plugin; am I looking in the wrong place, or what? +> --[[KathrynAndersen]] + +>> Sorry, I accidentally removed `field-etc` by pushing with `--mirror` from a +>> different checkout. I've put it back; it's a branch from your `ikiplugins.git`, +>> so yes, the code should be in `IkiWiki/Plugin`. --[[smcv]] diff --git a/doc/plugins/creole/discussion.mdwn b/doc/plugins/creole/discussion.mdwn index 38ee2bd78..7f47c2c97 100644 --- a/doc/plugins/creole/discussion.mdwn +++ b/doc/plugins/creole/discussion.mdwn @@ -12,4 +12,11 @@ I've installed Text::WikiCreole 0.05 and enabled the plugin, but I get an error >>> forgot, done now --[[Joey]] +--- +## External Links + I'm moving over a really stinkingly old UseMod and creole seems the nearest match. I've worked out that Bare /Subpage links need to become \[\[Subpage\]\], and Top/Sub links need to be \[\[Top/Sub\]\] (or \[\[Top/Sub|Top/Sub\]\], to display in exactly the same way), but I'm stuck on generic hyperlinks. The creole cheat sheet says I should be able to do \[\[http://url.path/foo|LinkText\]\], but that comes out as a link to create the "linktext" page, and Markdown-style \[Link Text\](http://url.path/foo) just gets rendered as is. Any suggestions? --[[schmonz]] + +> Was this problem ever solved? -- Thiana + +>> Not by me. If I were looking at the problem now, with fresh eyes, I'd probably bite the bullet and just convert everything to Markdown. --[[schmonz]] diff --git a/doc/plugins/cutpaste.mdwn b/doc/plugins/cutpaste.mdwn index f74f8a269..ea3665c44 100644 --- a/doc/plugins/cutpaste.mdwn +++ b/doc/plugins/cutpaste.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=cutpaste author="[[Enrico]]"]] -[[!tag type/chrome]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/cut]], [[ikiwiki/directive/copy]] and [[ikiwiki/directive/paste]] diff --git a/doc/plugins/date.mdwn b/doc/plugins/date.mdwn index b8dbdfee5..2a33f014c 100644 --- a/doc/plugins/date.mdwn +++ b/doc/plugins/date.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=date author="[[Joey]]"]] -[[!tag type/meta]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/date]] [[ikiwiki/directive]], which provides a way to display an arbitrary date diff --git a/doc/plugins/ddate.mdwn b/doc/plugins/ddate.mdwn index 741606a6e..17bb16cff 100644 --- a/doc/plugins/ddate.mdwn +++ b/doc/plugins/ddate.mdwn @@ -1,6 +1,7 @@ [[!template id=plugin name=ddate author="[[Joey]]"]] [[!tag type/fun]] [[!tag type/date]] +[[!tag type/chrome]] Enables use of Discordian dates. `--timeformat` can be used to change the date format; see `ddate(1)`. diff --git a/doc/plugins/editpage.mdwn b/doc/plugins/editpage.mdwn index b830e51aa..346ee7c78 100644 --- a/doc/plugins/editpage.mdwn +++ b/doc/plugins/editpage.mdwn @@ -1,4 +1,5 @@ [[!template id=plugin name=editpage core=1 author="[[Joey]]"]] +[[!tag type/web]] This plugin allows editing wiki pages in the web interface. It's enabled by default if [[cgi]] is enabled; disable it if you want cgi for other things diff --git a/doc/plugins/filecheck.mdwn b/doc/plugins/filecheck.mdwn index f4563d58e..e5f68b29c 100644 --- a/doc/plugins/filecheck.mdwn +++ b/doc/plugins/filecheck.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=filecheck core=0 author="[[Joey]]"]] -[[!tag type/useful]] +[[!tag type/special-purpose]] This plugin enhances the regular [[ikiwiki/PageSpec]] syntax with some additional tests, for things like file size, mime type, and virus diff --git a/doc/plugins/format.mdwn b/doc/plugins/format.mdwn index 91e707fcf..b41d365aa 100644 --- a/doc/plugins/format.mdwn +++ b/doc/plugins/format.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=format core=0 author="[[Joey]]"]] -[[!tag type/format]] +[[!tag type/widget]] This plugin allows mixing different page formats together, by embedding text formatted one way inside a page formatted another way. This is done diff --git a/doc/plugins/fortune.mdwn b/doc/plugins/fortune.mdwn index 9966f456d..3cb125ac1 100644 --- a/doc/plugins/fortune.mdwn +++ b/doc/plugins/fortune.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=fortune author="[[Joey]]"]] [[!tag type/fun]] +[[!tag type/widget]] This plugin implements the [[ikiwiki/directive/fortune]] [[ikiwiki/directive]]. This directive uses the `fortune` program to insert a fortune into the page. diff --git a/doc/plugins/getsource.mdwn b/doc/plugins/getsource.mdwn index 20040ccee..d5404a628 100644 --- a/doc/plugins/getsource.mdwn +++ b/doc/plugins/getsource.mdwn @@ -1,4 +1,5 @@ [[!template id=plugin name=getsource author="[[Will_Uther|Will]]"]] +[[!tag type/web]] This plugin adds a "Source" link to the top of each page that uses the CGI to display the page's source. diff --git a/doc/plugins/getsource/discussion.mdwn b/doc/plugins/getsource/discussion.mdwn new file mode 100644 index 000000000..45a1d62b5 --- /dev/null +++ b/doc/plugins/getsource/discussion.mdwn @@ -0,0 +1 @@ +It would be very cool if this plugin was enabled by default. One of the best ways to learn how to do various advanced things is to be able to "view source" on other wiki's which do things you like. -- [[AdamShand]] diff --git a/doc/plugins/goto.mdwn b/doc/plugins/goto.mdwn index 9c401c5d2..8e1de7a10 100644 --- a/doc/plugins/goto.mdwn +++ b/doc/plugins/goto.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=goto author="[[Simon_McVittie|smcv]]"]] -[[!tag type/useful]] +[[!tag type/web]] This plugin adds a `do=goto` mode for the IkiWiki CGI script. It's mainly for internal use by the [[404]], [[comments]] and [[recentchanges]] diff --git a/doc/plugins/graphviz.mdwn b/doc/plugins/graphviz.mdwn index b89f16b59..65130ae8c 100644 --- a/doc/plugins/graphviz.mdwn +++ b/doc/plugins/graphviz.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=graphviz author="[[JoshTriplett]]"]] -[[!tag type/chrome type/format]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/graph]] [[ikiwiki/directive]]. This directive allows embedding [graphviz](http://www.graphviz.org/) graphs in a diff --git a/doc/plugins/haiku.mdwn b/doc/plugins/haiku.mdwn index 74eac1c29..448733d95 100644 --- a/doc/plugins/haiku.mdwn +++ b/doc/plugins/haiku.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=haiku author="[[Joey]]"]] [[!tag type/fun]] +[[!tag type/widget]] This plugin provides a [[ikiwiki/directive/haiku]] [[ikiwiki/directive]]. The directive allows inserting a randomly generated haiku into a wiki page. diff --git a/doc/plugins/httpauth.mdwn b/doc/plugins/httpauth.mdwn index 77796a3d7..0eda5554f 100644 --- a/doc/plugins/httpauth.mdwn +++ b/doc/plugins/httpauth.mdwn @@ -14,12 +14,22 @@ signed into the wiki. This method is suitable only for private wikis. ## separate cgiauthurl To use httpauth for a wiki where the content is public, and where -the `ikiwiki.cgi` needs to be usable without authentication (for searching -and so on), you can configure a separate url that is used for -authentication, via the `cgiauthurl` option in the setup file. This -url will then be redirected to whenever authentication is needed. +the `ikiwiki.cgi` needs to be usable without authentication (for searching, +or logging in using other methods, and so on), you can configure a separate +url that is used for authentication, via the `cgiauthurl` option in the setup +file. This url will then be redirected to when a user chooses to log in using +httpauth. A typical setup is to make an `auth` subdirectory, and symlink `ikiwiki.cgi` into it. Then configure the web server to require authentication only for access to the `auth` subdirectory. Then `cgiauthurl` is pointed at this symlink. + +## using only httpauth for some pages + +If you want to only use httpauth for editing some pages, while allowing +other authentication methods to be used for other pages, you can +configure `httpauth_pagespec` in the setup file. This makes Edit +links on pages that match the [[ikiwiki/PageSpec]] automatically use +the `cgiauthurl`, and prevents matching pages from being edited by +users authentication via other methods. diff --git a/doc/plugins/img.mdwn b/doc/plugins/img.mdwn index 114438765..a6cd90f28 100644 --- a/doc/plugins/img.mdwn +++ b/doc/plugins/img.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=img author="Christian Mock"]] -[[!tag type/chrome]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/img]] [[ikiwiki/directive]]. While ikiwiki supports inlining full-size images by making a diff --git a/doc/plugins/inline.mdwn b/doc/plugins/inline.mdwn index 6c3282576..3eb849fdb 100644 --- a/doc/plugins/inline.mdwn +++ b/doc/plugins/inline.mdwn @@ -1,4 +1,5 @@ [[!template id=plugin name=inline core=1 author="[[Joey]]"]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/inline]] [[ikiwiki/directive]], which allows including one wiki page diff --git a/doc/plugins/linkmap.mdwn b/doc/plugins/linkmap.mdwn index 89cb9d8ae..7e51cd935 100644 --- a/doc/plugins/linkmap.mdwn +++ b/doc/plugins/linkmap.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=linkmap author="[[Joey]]"]] [[!tag type/meta]] +[[!tag type/widget]] [[!tag type/slow]] This plugin provides the [[ikiwiki/directive/linkmap]] [[ikiwiki/directive]]. diff --git a/doc/plugins/listdirectives.mdwn b/doc/plugins/listdirectives.mdwn index 2d9bce01d..df854de52 100644 --- a/doc/plugins/listdirectives.mdwn +++ b/doc/plugins/listdirectives.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=listdirectives author="Will"]] [[!tag type/meta]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/listdirectives]] [[ikiwiki/directive]], which inserts a list of currently available diff --git a/doc/plugins/lockedit.mdwn b/doc/plugins/lockedit.mdwn index c8f64ea47..681163203 100644 --- a/doc/plugins/lockedit.mdwn +++ b/doc/plugins/lockedit.mdwn @@ -12,14 +12,9 @@ to lock. For example, you could choose to lock all pages created before 2006, or all pages that are linked to from the page named "locked". More usually though, you'll just list some names of pages to lock. -One handy thing to do if you're using ikiwiki for your blog is to lock -"* and !*/Discussion". This prevents others from adding to or modifying -posts in your blog, while still letting them comment via the Discussion -pages. - -Alternatively, if you're using the [[comments]] plugin, you can lock -"!postcomment(*)" to allow users to comment on pages, but not edit anything -else. +If you want to lock down a blog so only you can post to it, you can just +lock "*", and enable the [[opendiscussion]] plugin, so readers can still post +[[comments]]. Wiki administrators can always edit locked pages. The [[ikiwiki/PageSpec]] can specify that some pages are not locked for some users. For example, diff --git a/doc/plugins/map.mdwn b/doc/plugins/map.mdwn index 8f5a9f15e..b164d5ca8 100644 --- a/doc/plugins/map.mdwn +++ b/doc/plugins/map.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=map author="Alessandro Dotti Contra"]] -[[!tag type/meta]] +[[!tag type/meta type/widget]] This plugin provides the [[ikiwiki/directive/map]] [[ikiwiki/directive]], which generates a hierarchical page map for the wiki. diff --git a/doc/plugins/mirrorlist.mdwn b/doc/plugins/mirrorlist.mdwn index b371e8eb7..aedc1f4a0 100644 --- a/doc/plugins/mirrorlist.mdwn +++ b/doc/plugins/mirrorlist.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=mirror author="[[Joey]]"]] -[[!tag type/special-purpose]] +[[!tag type/web]] This plugin allows adding links a list of mirrors to each page in the wiki. For each mirror, a name and an url should be specified. Pages are diff --git a/doc/plugins/moderatedcomments.mdwn b/doc/plugins/moderatedcomments.mdwn index 97924d742..f9466e833 100644 --- a/doc/plugins/moderatedcomments.mdwn +++ b/doc/plugins/moderatedcomments.mdwn @@ -5,6 +5,8 @@ This plugin causes [[comments]] to be held for manual moderation. Admins can access the comment moderation queue via their preferences page. By default, all comments made by anyone who is not an admin will be held -for moderation. The `moderate_users` setting can be set to false to avoid -moderating comments of logged-in users, while still moderating anonymous -comments. +for moderation. The `moderate_pagespec` setting can be used to specify a +[[ikiwiki/PageSpec]] to match comments and users who should be moderated. +For example, to avoid moderating comments from logged-in users, set +`moderate_pagespec` to "`!user(*)`". Or to moderate everyone except for +admins, set it to "`!admin(*)`". diff --git a/doc/plugins/more.mdwn b/doc/plugins/more.mdwn index e9a971289..a0664e843 100644 --- a/doc/plugins/more.mdwn +++ b/doc/plugins/more.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=more author="Ben"]] -[[!tag type/format]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/more]] [[ikiwiki/directive]], which is a way to have a "more" link on a post in a blog, that leads to the diff --git a/doc/plugins/opendiscussion.mdwn b/doc/plugins/opendiscussion.mdwn index b2ba68bf7..3b5ab4858 100644 --- a/doc/plugins/opendiscussion.mdwn +++ b/doc/plugins/opendiscussion.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=opendiscussion author="[[Joey]]"]] [[!tag type/auth]] -This plugin allows editing of Discussion pages by anonymous users who have -not logged into the wiki. +This plugin allows editing of Discussion pages, and posting of comments, +even when the [[lockedit]] plugin has been configured to otherwise prevent +editing. diff --git a/doc/plugins/orphans.mdwn b/doc/plugins/orphans.mdwn index e403c2d18..09ad0a51d 100644 --- a/doc/plugins/orphans.mdwn +++ b/doc/plugins/orphans.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=orphans author="[[Joey]]"]] [[!tag type/meta]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/orphans]] [[ikiwiki/directive]], which generates a list of possibly orphaned pages -- diff --git a/doc/plugins/pagecount.mdwn b/doc/plugins/pagecount.mdwn index a56027e60..71872fae8 100644 --- a/doc/plugins/pagecount.mdwn +++ b/doc/plugins/pagecount.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=pagecount author="[[Joey]]"]] [[!tag type/meta]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/pagecount]] [[ikiwiki/directive]], which displays the number of pages diff --git a/doc/plugins/pagestats.mdwn b/doc/plugins/pagestats.mdwn index c3eba6363..347e39a89 100644 --- a/doc/plugins/pagestats.mdwn +++ b/doc/plugins/pagestats.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=pagestats author="Enrico Zini"]] -[[!tag type/meta type/tags]] +[[!tag type/meta type/tags type/widget]] This plugin provides the [[ikiwiki/directive/pagestats]] [[ikiwiki/directive]], which can generate stats about how pages link to diff --git a/doc/plugins/parentlinks.mdwn b/doc/plugins/parentlinks.mdwn index ef262a30c..c2d364bef 100644 --- a/doc/plugins/parentlinks.mdwn +++ b/doc/plugins/parentlinks.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=parentlinks core=1 author="[[intrigeri]]"]] -[[!tag type/link]] +[[!tag type/link type/chrome]] This plugin generates the links to a page's parents that typically appear at the top of a wiki page. diff --git a/doc/plugins/poll.mdwn b/doc/plugins/poll.mdwn index 510f67798..099cb399c 100644 --- a/doc/plugins/poll.mdwn +++ b/doc/plugins/poll.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=poll author="[[Joey]]"]] -[[!tag type/web]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/poll]] [[ikiwiki/directive]], which allows inserting an online poll into a page. diff --git a/doc/plugins/polygen.mdwn b/doc/plugins/polygen.mdwn index 6045c1ec9..f9cea1f4d 100644 --- a/doc/plugins/polygen.mdwn +++ b/doc/plugins/polygen.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=polygen author="Enrico Zini"]] [[!tag type/fun]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/polygen]] [[ikiwiki/directive]], which allows inserting text generated by polygen into a wiki page. diff --git a/doc/plugins/postsparkline.mdwn b/doc/plugins/postsparkline.mdwn index c81f91bdc..b0733e343 100644 --- a/doc/plugins/postsparkline.mdwn +++ b/doc/plugins/postsparkline.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=postsparkline author="[[Joey]]"]] -[[!tag type/chrome]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/postsparkline]] [[ikiwiki/directive]]. It uses the [[sparkline]] plugin to create a sparkline of diff --git a/doc/plugins/prettydate.mdwn b/doc/plugins/prettydate.mdwn index 11ad4252f..149b7c29c 100644 --- a/doc/plugins/prettydate.mdwn +++ b/doc/plugins/prettydate.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=prettydate author="[[Joey]]"]] [[!tag type/date]] +[[!tag type/chrome]] Enabling this plugin changes the dates displayed on pages in the wiki to a format that is nice and easy to read. Examples: "late Wednesday evening, diff --git a/doc/plugins/progress.mdwn b/doc/plugins/progress.mdwn index e1b560cc8..20736d18c 100644 --- a/doc/plugins/progress.mdwn +++ b/doc/plugins/progress.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=progress author="[[Will]]"]] -[[!tag type/meta]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/progress]] [[ikiwiki/directive]], which generates a progress bar. diff --git a/doc/plugins/recentchanges.mdwn b/doc/plugins/recentchanges.mdwn index 9375296a4..823f68502 100644 --- a/doc/plugins/recentchanges.mdwn +++ b/doc/plugins/recentchanges.mdwn @@ -1,4 +1,5 @@ [[!template id=plugin name=recentchanges core=1 author="[[Joey]]"]] +[[!tag type/meta]] This plugin examines the [[revision_control_system|rcs]] history and generates a page describing each recent change made to the wiki. These diff --git a/doc/plugins/recentchangesdiff.mdwn b/doc/plugins/recentchangesdiff.mdwn index a7b113ade..57299f92d 100644 --- a/doc/plugins/recentchangesdiff.mdwn +++ b/doc/plugins/recentchangesdiff.mdwn @@ -1,4 +1,5 @@ [[!template id=plugin name=recentchangesdiff core=0 author="[[Joey]]"]] +[[!tag type/meta]] This plugin extends the [[recentchanges]] plugin, adding a diff for each change. The diffs are by default hidden from display on the recentchanges diff --git a/doc/plugins/relativedate.mdwn b/doc/plugins/relativedate.mdwn index 50c96c5d7..d6e8eb08b 100644 --- a/doc/plugins/relativedate.mdwn +++ b/doc/plugins/relativedate.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=relativedate author="[[Joey]]"]] [[!tag type/date]] +[[!tag type/chrome]] This plugin lets dates be displayed in relative form. Examples: "2 days ago", "1 month and 3 days ago", "30 minutes ago". Hovering over the date will diff --git a/doc/plugins/rename.mdwn b/doc/plugins/rename.mdwn index ddaede8b0..abb361329 100644 --- a/doc/plugins/rename.mdwn +++ b/doc/plugins/rename.mdwn @@ -2,7 +2,8 @@ [[!tag type/web]] This plugin allows pages or other files to be renamed using the web -interface. +interface. Following Unix tradition, renaming also allows moving to a +different directory. Users can only rename things that they are allowed to edit or upload. diff --git a/doc/plugins/repolist.mdwn b/doc/plugins/repolist.mdwn index 9b3a7575e..efd9c9352 100644 --- a/doc/plugins/repolist.mdwn +++ b/doc/plugins/repolist.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=repolist author="[[Joey]]"]] -[[!tag type/useful]] +[[!tag type/web]] This plugin allows you to configure ikiwiki with the location of [[rcs]] repositories for your wiki's source. This is done via the diff --git a/doc/plugins/rsync.mdwn b/doc/plugins/rsync.mdwn index 315b663c0..e48886168 100644 --- a/doc/plugins/rsync.mdwn +++ b/doc/plugins/rsync.mdwn @@ -1,4 +1,5 @@ [[!template id=plugin name=rsync author="[[schmonz]]"]] +[[!tag type/special-purpose]] This plugin allows ikiwiki to push generated pages to another host by running a command such as `rsync`. diff --git a/doc/plugins/shortcut.mdwn b/doc/plugins/shortcut.mdwn index cca1f4bdd..1e8e85ed8 100644 --- a/doc/plugins/shortcut.mdwn +++ b/doc/plugins/shortcut.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=shortcut author="[[Joey]]"]] -[[!tag type/format]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/shortcut]] [[ikiwiki/directive]]. It allows external links to commonly linked to sites to be made diff --git a/doc/plugins/sidebar.mdwn b/doc/plugins/sidebar.mdwn index 4e356d65a..012733456 100644 --- a/doc/plugins/sidebar.mdwn +++ b/doc/plugins/sidebar.mdwn @@ -1,24 +1,27 @@ [[!template id=plugin name=sidebar author="Tuomo Valkonen"]] [[!tag type/chrome]] -If this plugin is enabled, then a sidebar is added to pages in the wiki. -The content of the sidebar is simply the content of a page named -"sidebar" (ie, create a "sidebar.mdwn"). +This plugin allows adding a sidebar to pages in the wiki. + +By default, and unless the `global_sidebars` setting is turned off, +a sidebar is added to all pages in the wiki. The content of the sidebar +is simply the content of a page named "sidebar" (ie, create a "sidebar.mdwn"). Typically this will be a page in the root of the wiki, but it can also be a [[ikiwiki/SubPage]]. In fact, this page, [[plugins/sidebar|plugins/sidebar]], will be treated as a sidebar for the [[plugins]] page, and of all of its SubPages, if the plugin is enabled. -Note that to disable a sidebar for a [[ikiwiki/SubPage]] of a page that has -a sidebar, you can create a sidebar page that is completely empty. This -will turn off the sidebar altogether. +There is also a [[ikiwiki/directive/sidebar]] directive that can be used +to provide a custom sidebar content for a page. + +---- -Warning: Any change to the sidebar will cause a rebuild of the whole wiki, -since every page includes a copy that has to be updated. This can -especially be a problem if the sidebar includes an [[ikiwiki/directive/inline]] -directive, since any changes to pages inlined into the sidebar -will change the sidebar and cause a full wiki rebuild. +Warning: Any change to the sidebar page will cause a rebuild of the whole +wiki, since every page includes a copy that has to be updated. This can +especially be a problem if the sidebar includes an +[[ikiwiki/directive/inline]] directive, since any changes to pages inlined +into the sidebar will change the sidebar and cause a full wiki rebuild. Instead, if you include a [[ikiwiki/directive/map]] directive on the sidebar, and it does not use the `show` parameter, only adding or removing pages diff --git a/doc/plugins/sortnaturally.mdwn b/doc/plugins/sortnaturally.mdwn new file mode 100644 index 000000000..a16381946 --- /dev/null +++ b/doc/plugins/sortnaturally.mdwn @@ -0,0 +1,6 @@ +[[!template id=plugin name=sortnaturally core=1 author="[[chrysn]], [[smcv]]"]] +[[!tag type/meta]] + +This plugin provides the `title_natural` [[ikiwiki/pagespec/sorting]] +order, which uses [[!cpan Sort::Naturally]] to sort numbered pages in a +more natural order. diff --git a/doc/plugins/sparkline.mdwn b/doc/plugins/sparkline.mdwn index bcc5daec6..ee3928d7e 100644 --- a/doc/plugins/sparkline.mdwn +++ b/doc/plugins/sparkline.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=sparkline author="[[Joey]]"]] -[[!tag type/chrome]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/sparkline]] [[ikiwiki/directive]], which allows for easily embedding sparklines into diff --git a/doc/plugins/table.mdwn b/doc/plugins/table.mdwn index 10a85bb2c..fe66f90a8 100644 --- a/doc/plugins/table.mdwn +++ b/doc/plugins/table.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=table author="[[VictorMoral]]"]] -[[!tag type/format]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/table]] [[ikiwiki/directive]]. It can build HTML tables from data in CSV (comma-separated values) diff --git a/doc/plugins/template.mdwn b/doc/plugins/template.mdwn index 3485fe64c..da775f232 100644 --- a/doc/plugins/template.mdwn +++ b/doc/plugins/template.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=template author="[[Joey]]"]] -[[!tag type/format]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/template]] [[ikiwiki/directive]]. With this plugin, you can set up templates, and cause them to be filled out diff --git a/doc/plugins/testpagespec.mdwn b/doc/plugins/testpagespec.mdwn index dabcb0bec..8180d5d4b 100644 --- a/doc/plugins/testpagespec.mdwn +++ b/doc/plugins/testpagespec.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=testpagespec author="[[Joey]]"]] -[[!tag type/useful]] +[[!tag type/special-purpose]] This plugin provides a [[ikiwiki/directive/testpagespec]] [[ikiwiki/directive]]. The directive allows testing a [[ikiwiki/PageSpec]] to see if it matches a diff --git a/doc/plugins/teximg.mdwn b/doc/plugins/teximg.mdwn index ae052837f..f3cade85f 100644 --- a/doc/plugins/teximg.mdwn +++ b/doc/plugins/teximg.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=teximg author="[[PatrickWinnertz]]"]] -[[!tag type/chrome type/slow]] +[[!tag type/widget type/slow]] This plugin provides a [[ikiwiki/directive/teximg]] [[ikiwiki/directive]], that renders LaTeX formulas into images. diff --git a/doc/plugins/toc.mdwn b/doc/plugins/toc.mdwn index 2b7686681..a0ad3a5d0 100644 --- a/doc/plugins/toc.mdwn +++ b/doc/plugins/toc.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=toc author="[[Joey]]"]] -[[!tag type/chrome]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/toc]] [[ikiwiki/directive]], which adds a table of contents to a page. diff --git a/doc/plugins/toggle.mdwn b/doc/plugins/toggle.mdwn index 69ac613e0..d1500eba0 100644 --- a/doc/plugins/toggle.mdwn +++ b/doc/plugins/toggle.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=toggle author="[[Joey]]"]] -[[!tag type/chrome]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/toggle]] and [[ikiwiki/directive/toggleable]] [[directives|ikiwiki/directive]]. diff --git a/doc/plugins/txt.mdwn b/doc/plugins/txt.mdwn index 420898d09..a3087c9e0 100644 --- a/doc/plugins/txt.mdwn +++ b/doc/plugins/txt.mdwn @@ -12,3 +12,8 @@ The only exceptions are that [[WikiLinks|ikiwiki/WikiLink]] and [[directives|ikiwiki/directive]] are still expanded by ikiwiki, and that, if the [[!cpan URI::Find]] perl module is installed, URLs in the txt file are converted to hyperlinks. + +---- + +As a special case, a file `robots.txt` will be copied intact into the +`destdir`, as well as creating a wiki page named "robots". diff --git a/doc/plugins/type/chrome.mdwn b/doc/plugins/type/chrome.mdwn index d3f0eb3d3..a1c6d0728 100644 --- a/doc/plugins/type/chrome.mdwn +++ b/doc/plugins/type/chrome.mdwn @@ -1 +1 @@ -These plugins affect the look and feel of the wiki. +These plugins affect the look and feel of the overall wiki. diff --git a/doc/plugins/type/useful.mdwn b/doc/plugins/type/useful.mdwn deleted file mode 100644 index 92fcf5af1..000000000 --- a/doc/plugins/type/useful.mdwn +++ /dev/null @@ -1 +0,0 @@ -These plugins perform various miscellaneous useful functions. diff --git a/doc/plugins/type/widget.mdwn b/doc/plugins/type/widget.mdwn new file mode 100644 index 000000000..875829d0b --- /dev/null +++ b/doc/plugins/type/widget.mdwn @@ -0,0 +1,2 @@ +These plugins allow inserting various things into pages via a +[[ikiwiki/directive]]. diff --git a/doc/plugins/typography.mdwn b/doc/plugins/typography.mdwn index 030ef8052..9ff6c4ffd 100644 --- a/doc/plugins/typography.mdwn +++ b/doc/plugins/typography.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=typography author="[[Roktas]]"]] -[[!tag type/format]] +[[!tag type/chrome]] This plugin, also known as [SmartyPants](http://daringfireball.net/projects/smartypants/), translates diff --git a/doc/plugins/underlay.mdwn b/doc/plugins/underlay.mdwn index f7eafee7c..8836a394c 100644 --- a/doc/plugins/underlay.mdwn +++ b/doc/plugins/underlay.mdwn @@ -1,17 +1,17 @@ [[!template id=plugin name=underlay author="[[Simon_McVittie|smcv]]"]] -[[!tag type/useful]] +[[!tag type/special-purpose]] -This plugin adds an `add_underlays` option to the setup file. -Its value is a list of underlay directories whose content is added to the wiki. +This plugin adds an `add_underlays` option to the setup file. Its value is +a list of underlay directories whose content is added to the wiki. Multiple underlays are normally set up automatically by other plugins (for -instance, the images used by the [[plugins/smiley]] plugin), but they can also be -used as a way to pull in external files that you don't want in revision control, -like photos or software releases. +instance, the images used by the [[plugins/smiley]] plugin), but they can +also be used as a way to pull in external files that you don't want in +revision control, like photos or software releases. -Directories in `add_underlays` should usually be absolute. If relative, they're -interpreted as relative to the parent directory of the basewiki underlay, which -is probably not particularly useful in this context. +Directories in `add_underlays` should usually be absolute. If relative, +they're interpreted as relative to the parent directory of the basewiki +underlay, which is probably not particularly useful in this context. -- diff --git a/doc/plugins/version.mdwn b/doc/plugins/version.mdwn index 43027bdd7..326a2e7ce 100644 --- a/doc/plugins/version.mdwn +++ b/doc/plugins/version.mdwn @@ -1,5 +1,6 @@ [[!template id=plugin name=version author="[[Joey]]"]] [[!tag type/meta]] +[[!tag type/widget]] This plugin provides the [[ikiwiki/directive/version]] [[ikiwiki/directive]], which inserts the current version diff --git a/doc/plugins/websetup.mdwn b/doc/plugins/websetup.mdwn index f1756ba8f..b4d23ba9c 100644 --- a/doc/plugins/websetup.mdwn +++ b/doc/plugins/websetup.mdwn @@ -16,7 +16,8 @@ enabled and disabled using it too. Some settings are not considered safe enough to be manipulated over the web; these are still shown, by default, but cannot be modified. To hide them, set `websetup_show_unsafe` to false in the setup file. A few settings have too complex a data type to be -configured via the web. +configured via the web. To mark additional settings as unsafe, you can +list them in `websetup_unsafe`. Plugins that should not be enabled/disabled via the web interface can be listed in `websetup_force_plugins` in the setup file. diff --git a/doc/plugins/wmd.mdwn b/doc/plugins/wmd.mdwn index dc9a30703..96c6e2e6c 100644 --- a/doc/plugins/wmd.mdwn +++ b/doc/plugins/wmd.mdwn @@ -1,5 +1,5 @@ [[!template id=plugin name=wmd author="[[Will]]"]] -[[!tag type/chrome]] +[[!tag type/web]] [WMD](http://wmd-editor.com/) is a What You See Is What You Mean editor for [[mdwn]]. This plugin makes WMD be used for editing pages in the wiki. diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index 082f0e38f..0bf6fcf48 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -3,8 +3,84 @@ written to extend ikiwiki in many ways. Despite the length of this page, it's not really hard. This page is a complete reference to everything a plugin might want to do. There is also a quick [[tutorial]]. +[[!template id="note" text=""" +Ikiwiki is a compiler + +One thing to keep in mind when writing a plugin is that ikiwiki is a wiki +*compiler*. So plugins influence pages when they are built, not when they +are loaded. A plugin that inserts the current time into a page, for +example, will insert the build time. + +Also, as a compiler, ikiwiki avoids rebuilding pages unless they have +changed, so a plugin that prints some random or changing thing on a page +will generate a static page that won't change until ikiwiki rebuilds the +page for some other reason, like the page being edited. + +The [[tutorial]] has some other examples of ways that ikiwiki being a +compiler may trip up the unwary. +"""]] + [[!toc levels=2]] +## Highlevel view of ikiwiki + +Ikiwiki mostly has two modes of operation. It can either be running +as a compiler, building or updating a wiki; or as a cgi program, providing +user interface for editing pages, etc. Almost everything ikiwiki does +is accomplished by calling various hooks provided by plugins. + +### compiler + +As a compiler, ikiwiki starts by calling the `refresh` hook. Then it checks +the wiki's source to find new or changed pages. The `needsbuild` hook is +then called to allow manipulation of the list of pages that need to be +built. + +Now that it knows what pages it needs to build, ikiwiki runs two +compile passes. First, it runs `scan` hooks, which collect metadata about +the pages. Then it runs a page rendering pipeline, by calling in turn these +hooks: `filter`, `preprocess`, `linkify`, `htmlize`, `postscan`, +`pagetemplate`, `sanitize`, `format`. + +After all necessary pages are built, it calls the `change` hook. Finally, +if a page is was deleted, the `delete` hook is called, and the files that +page had previously produced are removed. + +### cgi + +The flow between hooks when ikiwiki is run as a cgi is best illustrated by +an example. + +Alice browses to a page and clicks Edit. + +* Ikiwiki is run as a cgi. It assigns Alice a session cookie, and, + by calling the `auth` hooks, sees that she is not yet logged in. +* The `sessioncgi` hooks are then called, and one of them, + from the [[editpage]] plugin, notices that the cgi has been told "do=edit". +* The [[editpage]] plugin calls the `canedit` hook to check if this + page edit is allowed. The [[signinedit]] plugin has a hook that says not: + Alice is not signed in. +* The [[signinedit]] plugin then launches the signin process. A signin + page is built by calling the `formbuilder_setup` hook. + +Alice signs in with her openid. + +* The [[openid]] plugin's `formbuilder` hook sees that an openid was + entered in the signin form, and redirects to Alice's openid provider. +* Alice's openid provider calls back to ikiwiki. The [[openid]] plugin + has an `auth` hook that finishes the openid signin process. +* Signin complete, ikiwiki returns to what Alice was doing before; editing + a page. +* Now all the `canedit` hooks are happy. The [[editpage]] plugin calls + `formbuilder_setup` to display the page editing form. + +Alice saves her change to the page. + +* The [[editpage]] plugin's `formbuilder` hook sees that the Save button + was pressed, and calls the `checkcontent` and `editcontent` hooks. + Then it saves the page to disk, and branches into the compiler part + of ikiwiki to refresh the wiki. + ## Types of plugins Most ikiwiki [[plugins]] are written in perl, like ikiwiki. This gives the @@ -31,16 +107,20 @@ they're the same as far as how they hook into ikiwiki. This document will explain how to write both sorts of plugins, albeit with an emphasis on perl plugins. -## Considerations +## Plugin interface -One thing to keep in mind when writing a plugin is that ikiwiki is a wiki -*compiler*. So plugins influence pages when they are built, not when they -are loaded. A plugin that inserts the current time into a page, for -example, will insert the build time. Also, as a compiler, ikiwiki avoids -rebuilding pages unless they have changed, so a plugin that prints some -random or changing thing on a page will generate a static page that won't -change until ikiwiki rebuilds the page for some other reason, like the page -being edited. +To import the ikiwiki plugin interface: + + use IkiWiki '3.00'; + +This will import several variables and functions into your plugin's +namespace. These variables and functions are the ones most plugins need, +and a special effort will be made to avoid changing them in incompatible +ways, and to document any changes that have to be made in the future. + +Note that IkiWiki also provides other variables and functions that are not +exported by default. No guarantee is made about these in the future, so if +it's not exported, the wise choice is to not use it. ## Registering plugins @@ -456,7 +536,13 @@ The data returned is a list of `%config` options, followed by a hash describing the option. There can also be an item named "plugin", which describes the plugin as a whole. For example: - return + return + plugin => { + description => "description of this plugin", + safe => 1, + rebuild => 1, + section => "misc", + }, option_foo => { type => "boolean", description => "enable foo?", @@ -471,11 +557,6 @@ describes the plugin as a whole. For example: safe => 1, rebuild => 0, }, - plugin => { - description => "description of this plugin", - safe => 1, - rebuild => 1, - }, * `type` can be "boolean", "string", "integer", "pagespec", or "internal" (used for values that are not user-visible). The type is @@ -496,6 +577,9 @@ describes the plugin as a whole. For example: the plugin) will require a wiki rebuild, false if no rebuild is needed, and undef if a rebuild could be needed in some circumstances, but is not strictly required. +* `section` can optionally specify which section in the config file + the plugin fits in. The convention is to name the sections the + same as the tags used for [[plugins|plugin]] on this wiki. ### genwrapper @@ -504,28 +588,17 @@ describes the plugin as a whole. For example: This hook is used to inject C code (which it returns) into the `main` function of the ikiwiki wrapper when it is being generated. -## Plugin interface - -To import the ikiwiki plugin interface: - - use IkiWiki '3.00'; - -This will import several variables and functions into your plugin's -namespace. These variables and functions are the ones most plugins need, -and a special effort will be made to avoid changing them in incompatible -ways, and to document any changes that have to be made in the future. +## Exported variables -Note that IkiWiki also provides other variables and functions that are not -exported by default. No guarantee is made about these in the future, so if -it's not exported, the wise choice is to not use it. +Several variables are exported to your plugin when you `use IkiWiki;` -### %config +### `%config` A plugin can access the wiki's configuration via the `%config` hash. The best way to understand the contents of the hash is to look at your ikiwiki setup file, which sets the hash content to configure the wiki. -### %pagestate +### `%pagestate` The `%pagestate` hash can be used by plugins to save state that they will need next time ikiwiki is run. The hash holds per-page state, so to set a value, @@ -543,7 +616,7 @@ When pages are deleted, ikiwiki automatically deletes their pagestate too. Note that page state does not persist across wiki rebuilds, only across wiki updates. -### %wikistate +### `%wikistate` The `%wikistate` hash can be used by a plugin to store persistant state that is not bound to any one page. To set a value, use @@ -552,23 +625,53 @@ serialize, `$key` is any string you like, and `$id` must be the same as the "id" parameter passed to `hook()` when registering the plugin, so that the state can be dropped if the plugin is no longer used. -### Other variables +### `%links` + +The `%links` hash can be used to look up the names of each page that +a page links to. The name of the page is the key; the value is an array +reference. Do not modify this hash directly; call `add_link()`. + + $links{"foo"} = ["bar", "baz"]; + +### `%typedlinks` + +The `%typedlinks` hash records links of specific types. Do not modify this +hash directly; call `add_link()`. The keys are page names, and the values +are hash references. In each page's hash reference, the keys are link types +defined by plugins, and the values are hash references with link targets +as keys, and 1 as a dummy value, something like this: + + $typedlinks{"foo"} = { + tag => { short_word => 1, metasyntactic_variable => 1 }, + next_page => { bar => 1 }, + }; -If your plugin needs to access data about other pages in the wiki. It can -use the following hashes, using a page name as the key: +Ordinary [[WikiLinks|ikiwiki/WikiLink]] appear in `%links`, but not in +`%typedlinks`. -* `%links` lists the names of each page that a page links to, in an array - reference. -* `%destsources` contains the name of the source file used to create each - destination file. -* `%pagesources` contains the name of the source file for each page. +### `%pagesources` -Also, the `%IkiWiki::version` variable contains the version number for the -ikiwiki program. +The `%pagesources` has can be used to look up the source filename +of a page. So the key is the page name, and the value is the source +filename. Do not modify this hash. -### Library functions + $pagesources{"foo"} = "foo.mdwn"; -#### `hook(@)` +### `%destsources` + +The `%destsources` hash records the name of the source file used to +create each destination file. The key is the output filename (ie, +"foo/index.html"), and the value is the source filename that it was built +from (eg, "foo.mdwn"). Note that a single source file may create multiple +destination files. Do not modify this hash directly; call `will_render()`. + + $destsources{"foo/index.html"} = "foo.mdwn"; + +## Library functions + +Several functions are exported to your plugin when you `use IkiWiki;` + +### `hook(@)` Hook into ikiwiki's processing. See the discussion of hooks above. @@ -577,12 +680,12 @@ named `no_override` is supported, If it's set to a true value, then this hook will not override any existing hook with the same id. This is useful if the id can be controled by the user. -#### `debug($)` +### `debug($)` Logs a debugging message. These are supressed unless verbose mode is turned on. -#### `error($;$)` +### `error($;$)` Aborts with an error message. If the second parameter is passed, it is a function that is called after the error message is printed, to do any final @@ -596,13 +699,13 @@ In other hooks, error() is a fatal error, so use with care. Try to avoid dying on bad input when building a page, as that will halt the entire wiki build and make the wiki unusable. -#### `template($;@)` +### `template($;@)` Creates and returns a [[!cpan HTML::Template]] object. The first parameter is the name of the file in the template directory. The optional remaining parameters are passed to `HTML::Template->new`. -#### `htmlpage($)` +### `htmlpage($)` Passed a page name, returns the base name that will be used for a the html page created from it. (Ie, it appends ".html".) @@ -610,23 +713,7 @@ page created from it. (Ie, it appends ".html".) Use this when constructing the filename of a html file. Use `urlto` when generating a link to a page. -### `deptype(@)` - -Use this function to generate ikiwiki's internal representation of a -dependency type from one or more of these keywords: - -* `content` is the default. Any change to the content - of a page triggers the dependency. -* `presence` is only triggered by a change to the presence - of a page. -* `links` is only triggered by a change to the links of a page. - This includes when a link is added, removed, or changes what - it points to due to other changes. It does not include the - addition or removal of a duplicate link. - -If multiple types are specified, they are combined. - -#### `pagespec_match_list($$;@)` +### `pagespec_match_list($$;@)` Passed a page name, and [[ikiwiki/PageSpec]], returns a list of pages in the wiki that match the [[ikiwiki/PageSpec]]. @@ -647,7 +734,10 @@ Additional named parameters can be specified: * `filter` is a reference to a function, that is called and passed a page, and returns true if the page should be filtered out of the list. * `sort` specifies a sort order for the list. See - [[ikiwiki/PageSpec/sorting]] for the avilable sort methods. + [[ikiwiki/PageSpec/sorting]] for the avilable sort methods. Note that + if a sort method is specified that depends on the + page content (such as 'meta(foo)'), the deptype needs to be set to + a content dependency. * `reverse` if true, sorts in reverse. * `num` if nonzero, specifies the maximum number of matching pages that will be returned. @@ -657,7 +747,7 @@ Additional named parameters can be specified: Any other named parameters are passed on to `pagespec_match`, to further limit the match. -#### `add_depends($$;$)` +### `add_depends($$;$)` Makes the specified page depend on the specified [[ikiwiki/PageSpec]]. @@ -665,7 +755,7 @@ By default, dependencies are full content dependencies, meaning that the page will be updated whenever anything matching the PageSpec is modified. This can be overridden by passing a `deptype` value as the third parameter. -#### `pagespec_match($$;@)` +### `pagespec_match($$;@)` Passed a page name, and [[ikiwiki/PageSpec]], returns a true value if the [[ikiwiki/PageSpec]] matches the page. @@ -679,7 +769,23 @@ The most often used is "location", which specifies the location the PageSpec should match against. If not passed, relative PageSpecs will match relative to the top of the wiki. -#### `bestlink($$)` +### `deptype(@)` + +Use this function to generate ikiwiki's internal representation of a +dependency type from one or more of these keywords: + +* `content` is the default. Any change to the content + of a page triggers the dependency. +* `presence` is only triggered by a change to the presence + of a page. +* `links` is only triggered by a change to the links of a page. + This includes when a link is added, removed, or changes what + it points to due to other changes. It does not include the + addition or removal of a duplicate link. + +If multiple types are specified, they are combined. + +### `bestlink($$)` Given a page and the text of a link on the page, determine which existing page that link best points to. Prefers pages under a @@ -687,7 +793,7 @@ subdirectory with the same name as the source page, failing that goes down the directory tree to the base looking for matching pages, as described in [[ikiwiki/SubPage/LinkingRules]]. -#### `htmllink($$$;@)` +### `htmllink($$$;@)` Many plugins need to generate html links and add them to a page. This is done by using the `htmllink` function. The usual way to call @@ -715,7 +821,7 @@ control some options. These are: * class - set to add a css class to the link * title - set to add a title attribute to the link -#### `readfile($;$)` +### `readfile($;$)` Given a filename, reads and returns the entire file. @@ -724,7 +830,7 @@ in binary mode. A failure to read the file will result in it dying with an error. -#### `writefile($$$;$$)` +### `writefile($$$;$$)` Given a filename, a directory to put it in, and the file's content, writes a file. @@ -752,7 +858,7 @@ generally the directory parameter is a trusted toplevel directory like the srcdir or destdir, and any subdirectories of this are included in the filename parameter. -#### `will_render($$)` +### `will_render($$)` Given a page name and a destination file name (not including the base destination directory), register that the page will result in that file @@ -768,34 +874,34 @@ Ikiwiki uses this information to automatically clean up rendered files when the page that rendered them goes away or is changed to no longer render them. will_render also does a few important security checks. -#### `pagetype($)` +### `pagetype($)` Given the name of a source file, returns the type of page it is, if it's a type that ikiwiki knowns how to htmlize. Otherwise, returns undef. -#### `pagename($)` +### `pagename($)` Given the name of a source file, returns the name of the wiki page that corresponds to that file. -#### `pagetitle($)` +### `pagetitle($)` Give the name of a wiki page, returns a version suitable to be displayed as the page's title. This is accomplished by de-escaping escaped characters in the page name. "_" is replaced with a space, and '__NN__' is replaced by the UTF character with code NN. -#### `titlepage($)` +### `titlepage($)` This performs the inverse of `pagetitle`, ie, it converts a page title into a wiki page name. -#### `linkpage($)` +### `linkpage($)` This converts text that could have been entered by the user as a [[ikiwiki/WikiLink]] into a wiki page name. -#### `srcfile($;$)` +### `srcfile($;$)` Given the name of a source file in the wiki, searches for the file in the source directory and the underlay directories (most recently added @@ -805,7 +911,7 @@ Normally srcfile will fail with an error message if the source file cannot be found. The second parameter can be set to a true value to make it return undef instead. -#### `add_underlay($)` +### `add_underlay($)` Adds a directory to the set of underlay directories that ikiwiki will search for files. @@ -813,18 +919,22 @@ search for files. If the directory name is not absolute, ikiwiki will assume it is in the parent directory of the configured underlaydir. -#### `displaytime($;$)` +### `displaytime($;$)` Given a time, formats it for display. The optional second parameter is a strftime format to use to format the time. -#### `gettext` +### `gettext` This is the standard gettext function, although slightly optimised. -#### `urlto($$;$)` +### `ngettext` + +This is the standard ngettext function, although slightly optimised. + +### `urlto($$;$)` Construct a relative url to the first parameter from the page named by the second. The first parameter can be either a page name, or some other @@ -833,13 +943,13 @@ destination file, as registered by `will_render`. If the third parameter is passed and is true, an absolute url will be constructed instead of the default relative url. -#### `newpagefile($$)` +### `newpagefile($$)` This can be called when creating a new page, to determine what filename to save the page to. It's passed a page name, and its type, and returns the name of the file to create, relative to the srcdir. -#### `targetpage($$;$)` +### `targetpage($$;$)` Passed a page and an extension, returns the filename that page will be rendered to. @@ -848,11 +958,14 @@ Optionally, a third parameter can be passed, to specify the preferred filename of the page. For example, `targetpage("foo", "rss", "feed")` will yield something like `foo/feed.rss`. -#### `add_link($$)` +### `add_link($$;$)` This adds a link to `%links`, ensuring that duplicate links are not added. Pass it the page that contains the link, and the link text. +An optional third parameter sets the link type. If not specified, +it is an ordinary [[ikiwiki/WikiLink]]. + ## Miscellaneous ### Internal use pages @@ -972,6 +1085,17 @@ it up in the history. It's ok if this is not implemented, and throws an error. +If the RCS cannot determine a ctime for the file, return 0. + +#### `rcs_getmtime($)` + +This is used to get the page modification time for a file from the RCS, by +looking it up in the history. + +It's ok if this is not implemented, and throws an error. + +If the RCS cannot determine a mtime for the file, return 0. + #### `rcs_receive()` This is called when ikiwiki is running as a pre-receive hook (or @@ -1019,6 +1143,24 @@ For example, "backlink(foo)" is influenced by the contents of page foo; they match; "created_before(foo)" is influenced by the metadata of foo; while "glob(*)" is not influenced by the contents of any page. +### Sorting plugins + +Similarly, it's possible to write plugins that add new functions as +[[ikiwiki/pagespec/sorting]] methods. To achieve this, add a function to +the IkiWiki::SortSpec package named `cmp_foo`, which will be used when sorting +by `foo` or `foo(...)` is requested. + +The names of pages to be compared are in the global variables `$a` and `$b` +in the IkiWiki::SortSpec package. The function should return the same thing +as Perl's `cmp` and `<=>` operators: negative if `$a` is less than `$b`, +positive if `$a` is greater, or zero if they are considered equal. It may +also raise an error using `error`, for instance if it needs a parameter but +one isn't provided. + +The function will also be passed one or more parameters. The first is +`undef` if invoked as `foo`, or the parameter `"bar"` if invoked as `foo(bar)`; +it may also be passed additional, named parameters. + ### Setup plugins The ikiwiki setup file is loaded using a pluggable mechanism. If you look diff --git a/doc/rcs.mdwn b/doc/rcs.mdwn index f66b85495..450d16800 100644 --- a/doc/rcs.mdwn +++ b/doc/rcs.mdwn @@ -7,10 +7,31 @@ Ikiwiki started out supporting only [[Subversion|svn]], but the interface ikiwiki uses to a revision control system is sufficiently simple and generic that it can be adapted to work with many systems by writing a [[plugin|plugins/write]]. [[Subversion|svn]] is still a recommended choice; -[[git]] is another well-tested option. +[[git]] is another well-tested option. -These are all the supported revision control systems: -[[!inline pages="rcs/* and !*/Discussion and !rcs/details" archive=yes]] +While all supported revision control systems work well enough for basic +use, some advanced or special features are not supported in all of them. +Lack of support in [[ikiwiki-makerepo]] or auto.setup can make it harder to +set up a wiki using that revision control system. The `rcs_commit_staged` +hook is needed to use [[attachments|plugins/attachment]] or +[[plugins/comments]]. `rcs_getctime` may be implemented in a fast way +(ie, one log lookup for all files), or very slowly (one lookup per file). +And so on. The table below summarises this for each revision control +system and links to more information about each. + +[[!table data=""" +feature |[[git]]|[[svn]]|[[bzr]] |[[monotone]]|[[mercurial]]|[[darcs]]|[[tla]] |[[cvs]] +[[ikiwiki-makerepo]]|yes |yes |yes |yes |yes |yes |no |yes +auto.setup |yes |yes |incomplete|yes |incomplete |yes |incomplete|yes +`rcs_commit_staged` |yes |yes |yes |yes |no |yes |no |yes +`rcs_rename` |yes |yes |yes |yes |no |yes |no |yes +`rcs_remove` |yes |yes |yes |yes |no |yes |no |yes +`rcs_diff` |yes |yes |yes |yes |no |yes |yes |yes +`rcs_getctime` |fast |slow |slow |slow |slow |slow |slow |slow +`rcs_getmtime` |fast |slow |no |no |no |no |no |no +anonymous push |yes |no |no |no |no |no |no |no +conflict handling |yes |yes |yes |buggy |yes |yes |yes |yes +"""]] There is a page with [[details]] about how the different systems work with ikiwiki, for the curious. diff --git a/doc/roadmap.mdwn b/doc/roadmap.mdwn index a701a2685..0c7bf2fa8 100644 --- a/doc/roadmap.mdwn +++ b/doc/roadmap.mdwn @@ -69,6 +69,20 @@ backwards compatability. ---- +# compatability breaking changes + +Probably incomplete list: + +* Drop old `--getctime` option. +* Remove compatability code in `loadindex` to handle old index data layouts. +* Make pagespecs match relative by default? (see [[discussion]]) +* Flip wikilinks? (see [[todo/link_plugin_perhaps_too_general?]]) +* YADA format setup files per default? + +In general, we try to use [[ikiwiki-transition]] or forced rebuilds on +upgrade to deal with changes that break compatability. Some things that +can't help with. + # future goals * Conversion support for existing other wikis. diff --git a/doc/roadmap/discussion.mdwn b/doc/roadmap/discussion.mdwn index 0b69867bf..8233b1990 100644 --- a/doc/roadmap/discussion.mdwn +++ b/doc/roadmap/discussion.mdwn @@ -3,6 +3,7 @@ backwards compatibility problems. Should this be marked as a future plan, perhap major version number like 2.0? --Ethan Yes, I'm looking at making this kind of change at 2.0, added to the list. +(Update: Didn't make it in 2.0 or 3.0...) However, I have doubts that it makes good sense to go relative by default. While it's not consitent with links, it seems to work better overall to have pagespecs be absolute by default, IMHO. --[[Joey]] diff --git a/doc/sandbox.mdwn b/doc/sandbox.mdwn index afd7dbeab..c323153c8 100644 --- a/doc/sandbox.mdwn +++ b/doc/sandbox.mdwn @@ -1,9 +1,9 @@ This is the [[SandBox]], a page anyone can edit to try out ikiwiki (version [[!version ]]). - +[[Testing 1 2 3| test]] # Header -## Subheader +## Subheader2 > This is a blockquote. > @@ -77,3 +77,5 @@ bar Hmm, can I dig it? Test +test2 + diff --git a/doc/sandbox/danc.mdwn b/doc/sandbox/danc.mdwn new file mode 100644 index 000000000..9766475a4 --- /dev/null +++ b/doc/sandbox/danc.mdwn @@ -0,0 +1 @@ +ok diff --git a/doc/sandbox/prova_blog.html b/doc/sandbox/prova_blog.html new file mode 100644 index 000000000..d69937ea8 --- /dev/null +++ b/doc/sandbox/prova_blog.html @@ -0,0 +1,8 @@ +Questa è una prova. +Vediamo se funziona + +<pre> +#!/bin/bash + +echo "ciao" +</pre> diff --git a/doc/security.mdwn b/doc/security.mdwn index 3924186c2..21aef316b 100644 --- a/doc/security.mdwn +++ b/doc/security.mdwn @@ -427,3 +427,15 @@ enabling TeX configuration options that disallow unsafe TeX commands. The fix was released on 30 Aug 2009 in version 3.1415926, and was backported to stable in version 2.53.4. If you use the teximg plugin, I recommend upgrading. ([[!cve CVE-2009-2944]]) + +## javascript insertion via svg uris + +Ivan Shmakov pointed out that the htmlscrubber allowed `data:image/*` urls, +including `data:image/svg+xml`. But svg can contain javascript, so that is +unsafe. + +This hole was discovered on 12 March 2010 and fixed the same day +with the release of ikiwiki 3.20100312. +A fix was also backported to Debian etch, as version 2.53.5. I recommend +upgrading to one of these versions if your wiki can be edited by third +parties. diff --git a/doc/style.css b/doc/style.css index 317d4c7aa..7ffcf9fe2 100644 --- a/doc/style.css +++ b/doc/style.css @@ -228,14 +228,15 @@ div.recentchanges { .bigPC { font-size: 115%; } .biggestPC { font-size: 130%; } -#sidebar { - line-height: 3ex; - width: 20ex; +.sidebar { + width: 30ex; float: right; - margin-left: 40px; - margin-bottom: 40px; - padding: 2ex 2ex; + margin-left: 4px; + margin-bottom: 4px; + margin-top: -1px; + padding: 0ex 2ex; background: white; + border: 1px solid black; color: black !important; } @@ -430,3 +431,11 @@ pre.hl { color:#000000; background-color:#ffffff; } /* For the calendar plugin. */ .month-calendar-day-this-day { background-color: #eee; } .year-calendar-this-month { background-color: #eee; } +.month-calendar-arrow A:link, +.year-calendar-arrow A:link, +.month-calendar-arrow A:visited, +.year-calendar-arrow A:visited { + text-decoration: none; + font-weight: normal; + font-size: 150%; +} diff --git a/doc/templates.mdwn b/doc/templates.mdwn index eff0e15e9..07531ae98 100644 --- a/doc/templates.mdwn +++ b/doc/templates.mdwn @@ -43,6 +43,12 @@ page will provide a link that can be used to create the template. The template is a regular wiki page, located in the `templates/` subdirectory inside the source directory of the wiki. +(Alternatively, templates can be stored in a directory outside the wiki, +as files with the extension ".tmpl". +By default, these are searched for in `/usr/share/ikiwiki/templates`; +the `templatedir` setting can be used to make another directory be searched +first.) + The template uses the syntax used by the [[!cpan HTML::Template]] perl module, which allows for some fairly complex things to be done. Consult its documentation for the full syntax, but all you really need to know are a diff --git a/doc/tips/Importing_posts_from_Wordpress.mdwn b/doc/tips/Importing_posts_from_Wordpress.mdwn index 59330caa4..ecc6ae505 100644 --- a/doc/tips/Importing_posts_from_Wordpress.mdwn +++ b/doc/tips/Importing_posts_from_Wordpress.mdwn @@ -1,6 +1,6 @@ Use case: You want to move away from Wordpress to Ikiwiki as your blogging/website platform, but you want to retain your old posts. -[This](http://git.chris-lamb.co.uk/?p=ikiwiki-wordpress-import.git) is a simple tool that generates [git-fast-import](http://www.kernel.org/pub/software/scm/git/docs/git-fast-import.html)-compatible data from a WordPress export XML file. It retains creation time of each post, so you can use Ikiwiki's <tt>--getctime</tt> to get the preserve creation times on checkout. +[This](http://git.chris-lamb.co.uk/?p=ikiwiki-wordpress-import.git) is a simple tool that generates [git-fast-import](http://www.kernel.org/pub/software/scm/git/docs/git-fast-import.html)-compatible data from a WordPress export XML file. WordPress categories are mapped onto Ikiwiki tags. The ability to import comments is planned. diff --git a/doc/tips/follow_wikilinks_from_inside_vim.mdwn b/doc/tips/follow_wikilinks_from_inside_vim.mdwn new file mode 100644 index 000000000..015a4ecee --- /dev/null +++ b/doc/tips/follow_wikilinks_from_inside_vim.mdwn @@ -0,0 +1,47 @@ +The [ikiwiki-nav](http://www.vim.org/scripts/script.php?script_id=2968) plugin +for vim eases the editing of IkiWiki wikis, by letting you "follow" the +wikilinks on your file (page), by loading the file associated with a given +wikilink in vim. The plugin takes care of following the ikiwiki linking rules +to figure out which file a wikilink points to + +The plugin also includes commands (and mappings) to make the cursor jump to the +previous/next wikilink in the current file + +## Jumping to pages + +To open the file associated to a wikilink, place the cursor over its text, and +hit Enter (`<CR>`). This functionality is also available through the +`:IkiJumpToPage` command + +## Moving to next/previous wikilink in current file + +`Ctrl-j` will move the cursor to the next wikilink. `Ctrl-k` will move it to the +previous wikilink. This functionality is also available through the +`:IkiNextWikiLink` command. This command takes one argument, the direction to +move into + + * `:IkiNextWikiLink 0` will look forward for the wikilink + * `:IkiNextWikiLink 1` will look backwards for the wikilink + +## Installation + +Copy the `ikiwiki_nav.vim` file to your `.vim/ftplugin` directory. + +## Current issues: + + * The plugin only works for wikilinks contained in a single text line; + multiline wikilinks are not (yet) seen as such + +## Notes + +The official releases of the plugin are in the +[vim.org script page](http://www.vim.org/scripts/script.php?script_id=2968) + +The latest version of this script can be found in the following location + +<http://git.devnull.li/cgi-bin/gitweb.cgi?p=ikiwiki-nav.git;a=blob;f=ftplugin/ikiwiki_nav.vim;hb=HEAD> + +Any feedback you can provide is appreciated; the contact details can be found +inside the plugin + +[[!tag vim]] diff --git a/doc/tips/htaccess_file.mdwn b/doc/tips/htaccess_file.mdwn new file mode 100644 index 000000000..6964cf24e --- /dev/null +++ b/doc/tips/htaccess_file.mdwn @@ -0,0 +1,27 @@ +If you try to include a `.htaccess` file in your wiki's source, in order to +configure the web server, you'll find that ikiwiki excludes it from +processing. In fact, ikiwiki excludes any file starting with a dot, as well +as a lot of other files, for good security reasons. + +You can tell ikiwiki not to exclude the .htaccess file by adding this to +your setup file: + + include => '^\.htaccess$', + +Caution! Before you do that, please think for a minute about who can edit +your wiki. Are attachment uploads enabled? Can users commit changes +directly to the version control system? Do you trust everyone who can +make a change to not do Bad Things with the htaccess file? Do you trust +everyone who *might* be able to make a change in the future? Note that a +determined attacker who can write to the htaccess file can probably get a +shell on your web server. + +If any of these questions have given you pause, I suggest you find a +different way to configure the web server. One way is to not put the +`.htaccess` file under ikiwiki's control, and just manually install it +in the destdir. --[[Joey]] + +[Apache's documentation](http://httpd.apache.org/docs/2.2/howto/htaccess.html) +says: +> In general, you should never use .htaccess files unless you don't have +> access to the main server configuration file. diff --git a/doc/tips/inside_dot_ikiwiki/discussion.mdwn b/doc/tips/inside_dot_ikiwiki/discussion.mdwn index 34d5b9252..69df369ec 100644 --- a/doc/tips/inside_dot_ikiwiki/discussion.mdwn +++ b/doc/tips/inside_dot_ikiwiki/discussion.mdwn @@ -6,14 +6,15 @@ My database appears corrupted: No idea how this happened. I've blown it away and recreated it but, for future reference, is there any less violent way to recover from this situation? I miss having the correct created and last edited times. --[[sabr]] > update: fixed ctimes and mtimes using [these instructions](http://u32.net/Mediawiki_Conversion/Git_Import/#Correct%20Creation%20and%20Last%20Edited%20time) --[[sabr]] -> That's overly complex. Just run `ikiwiki -setup your.setup -getctime`. +> That's overly complex. Just run `ikiwiki -setup your.setup -gettime`. > BTW, I'd be interested in examining such a corrupt storable file to try > to see what happened to it. --[[Joey]] ->> --getctime appears to only set the last edited date. It's not supposed to set the creation date, is it? The only place that info is stored is in the git repo. +>> --gettime appears to only set the last edited date. It's not supposed to set the creation date, is it? The only place that info is stored is in the git repo. >>> Pulling the page creation date out of the git history is exactly what ->>> --getctime does. --[[Joey]] +>>> --gettime does. (It used to be called --getctime, and only do that; now +>>> it also pulls out the last modified date). --[[Joey]] >> Alas, I seem to have lost the bad index file to periodic /tmp wiping; I'll send it to you if it happens again. --[[sabr]] diff --git a/doc/tips/laptop_wiki_with_git.mdwn b/doc/tips/laptop_wiki_with_git.mdwn index 85e26c729..cfa565d1a 100644 --- a/doc/tips/laptop_wiki_with_git.mdwn +++ b/doc/tips/laptop_wiki_with_git.mdwn @@ -67,6 +67,5 @@ as many times as you want (thus being able to have a repository which is used by the ikiwiki CGI, and another which you can use for updating via git). -When you want to update the server from the laptop, do a `git push` from -within the laptop's bare repository, and likewise do a `git pull` to update -the laptop from the server. +Use standard git commands, run in the laptop's bare git repository +to handle pulling from and pushing to the server. diff --git a/doc/tips/spam_and_softwaresites.mdwn b/doc/tips/spam_and_softwaresites.mdwn new file mode 100644 index 000000000..a07889e6b --- /dev/null +++ b/doc/tips/spam_and_softwaresites.mdwn @@ -0,0 +1,87 @@ +Any wiki with a form of web-editing enabled will have to deal with +spam. (See the [[plugins/blogspam]] plugin for one defensive tool you +can deploy). + +If: + + * you are using ikiwiki to manage the website for a [[examples/softwaresite]] + * you allow web-based commits, to let people correct documentation, or report + bugs, etc. + * the documentation is stored in the same revision control repository as your + software + +It is undesirable to have your software's VCS history tainted by spam and spam +clean-up commits. Here is one approach you can use to prevent this. This +example is for the [[git]] version control system, but the principles should +apply to others. + +## Isolate web commits to a specific branch + +Create a separate branch to contain web-originated edits (named `doc` in this +example): + + $ git checkout -b doc + +Adjust your setup file accordingly: + + gitmaster_branch => 'doc', + +## merging good web commits into the master branch + +You will want to periodically merge legitimate web-based commits back into +your master branch. Ensure that there is no spam in the documentation +branch. If there is, see 'erase spam from the commit history', below, first. + +Once you are confident it's clean: + + # ensure you are on the master branch + $ git branch + doc + * master + $ git merge --ff doc + +## removing spam + +### short term + +In the short term, just revert the spammy commit. + +If the spammy commit was the top-most: + + $ git revert HEAD + +This will clean the spam out of the files, but it will leave both the spam +commit and the revert commit in the history. + +### erase spam from the commit history + +Git allows you to rewrite your commit history. We will take advantage of this +to eradicate spam from the history of the doc branch. + +This is a useful tool, but it is considered bad practise to rewrite the +history of public repositories. If your software's repository is public, you +should make it clear that the history of the `doc` branch in your repository +is unstable. + +Once you have been spammed, use `git rebase` to remove the spam commits from +the history. Assuming that your `doc` branch was split off from a branch +called `master`: + + # ensure you are on the doc branch + $ git branch + * doc + master + $ git rebase --interactive master + +In your editor session, you will see a series of lines for each commit made to +the `doc` branch since it was branched from `master` (or since the last merge +back into `master`). Delete the lines corresponding to spammy commits, then +save and exit your editor. + +Caveat: if there are no commits you want to keep (i.e. all the commits since +the last merge into master are either spam or spam reverts) then `git rebase` +will abort. Therefore, this approach only works if you have at least one +non-spam commit to the documentation since the last merge into `master`. For +this reason, it's best to wait until you have at least one +commit you want merged back into the main history before doing a rebase, +and until then, tackle spam with reverts. diff --git a/doc/tips/vim_syntax_highlighting.mdwn b/doc/tips/vim_syntax_highlighting.mdwn index 172b763c3..18b2f1c92 100644 --- a/doc/tips/vim_syntax_highlighting.mdwn +++ b/doc/tips/vim_syntax_highlighting.mdwn @@ -1,4 +1,7 @@ [[ikiwiki.vim]] is a vim syntax highlighting file for ikiwiki -[[ikiwiki/markdown]] files. +[[ikiwiki/markdown]] files. Installation instructions are at the top of the file. + +See also: [[follow_wikilinks_from_inside_vim]] +[[!tag vim]] diff --git a/doc/tips/yaml_setup_files.mdwn b/doc/tips/yaml_setup_files.mdwn new file mode 100644 index 000000000..4ae0de4aa --- /dev/null +++ b/doc/tips/yaml_setup_files.mdwn @@ -0,0 +1,10 @@ +Here's how to convert your existing standard format ikiwiki setup file into +the new YAML format recently added to ikiwiki. + +1. First, make sure you have the [[!cpan YAML]] perl module installed. + (Run: `apt-get install libyaml-perl`) +2. Run: `ikiwiki -setup my.setup -dumpsetup my.setup --set setuptype=Yaml` + +The format of the YAML setup file should be fairly self-explanatory. + +--[[Joey]] diff --git a/doc/todo/ACL.mdwn b/doc/todo/ACL.mdwn index d40701d60..dd9793233 100644 --- a/doc/todo/ACL.mdwn +++ b/doc/todo/ACL.mdwn @@ -21,6 +21,11 @@ something, that I think is very valuable. >>>> Which would rule out openid, or other fun forms of auth. And routing all access >>>> through the CGI sort of defeats the purpose of ikiwiki. --[[Ethan]] +>>>>> I think what Joey is suggesting is to use apache ACLs in conjunction +>>>>> with basic HTTP auth to control read access, and ikiwiki can use the +>>>>> information via the httpauth plugin for other ACLs (write, admin). But +>>>>> yes, that would rule out non-httpauth mechanisms. -- [[Jon]] + Also see [[!debbug 443346]]. > Just a few quick thoughts about this: @@ -76,3 +81,18 @@ Any idea when this is going to be finished? If you want, I am happy to beta tes > Example of use to only allow two users to edit the tipjar page: > locked_pages => 'tipjar and !(user(joey) or user(bob))', > --[[Joey]] + +> > Thank you for the hint but I am being still confused (read: dense)... What I am trying to do is this: + +> > * No anonymous access. +> > * Logged in users can edit and create pages. +> > * Users can set who can edit their pages. +> > * Some pages are only viewable by admins. + +> > Is it possible? If so how?... + +>>> I don't believe this is currently possible. What is missing is the concept +>>> of page 'ownership'. -- [[Jon]] + +>>>> GAH! That is really a shame... Any chance of adding that? No, I do not really expect it to be added, after all my requirements are pushing the boundary of what a wikiwiki + should be. Nonetheless, thanks for your help! diff --git a/doc/todo/More_flexible_po-plugin_for_translation.mdwn b/doc/todo/More_flexible_po-plugin_for_translation.mdwn new file mode 100644 index 000000000..3399f7834 --- /dev/null +++ b/doc/todo/More_flexible_po-plugin_for_translation.mdwn @@ -0,0 +1,5 @@ +I have a website with multi-language content, where some content is only in English, some in German, and some is available in both languages. + +The po-module currently has only one master-language, with slave languages, and a PageSpec should be considered. + +It would be nice to flag the content which should have a translation on a file-by-file basis (with some inline directive?) which could contain the information of the master-language for that file and the desired target-languages. diff --git a/doc/todo/Multiple_categorization_namespaces.mdwn b/doc/todo/Multiple_categorization_namespaces.mdwn new file mode 100644 index 000000000..ee3bbd88d --- /dev/null +++ b/doc/todo/Multiple_categorization_namespaces.mdwn @@ -0,0 +1,72 @@ +I came across this when working on converting my old blog into an ikiwiki, but I think it could be of more general use. + +The background: I have a (currently suspended, waiting to be converted) blog on the [il Cannocchiale](http://www.ilcannocchiale.it) hosting platform. Aside from the usual metatadata (title, author), il Cannocchiale also provides tags and two additional categorization namespaces: a blog-specific user-defind "column" (Rubrica) and a platform-wide "category" (Categoria). The latter is used to group and label a couple of platform-wide lists of latest posts, the former may be used in many different ways (e.g. multi-author blogs could have one column per author or so, or as a form of 'macro-tagging'). Columns are also a little more sophisticated than classical tags because you can assign them a subtitle too. + +When I started working on the conversion, my first idea was to convert Rubriche to subdirectories of an ikiwiki blog. However, this left me with a few annoying things: when rebuilding links from the import, I had to (programmatically) dive into each subdirectory to see where each post was; this would also be problematic for future posting, too. It also meant that moving a post from a Rubrica to the other would break all links (unless ikiwiki has a way to fix this automagically). And I wasn't too keen on the fact that the Rubrica would come up in the URL of the post. And finally, of course, I couldn't use this to preserve the Categoria metadata. + +Another solution I thought about was to use special deeper tags for the Rubrica and Categoria (like: `\[[!tag "Rubrica/Some name"]]`), but this is horrible, clumsy, and makes special treatment of these tags a PITN (for example you wouldn't want the Rubrica to be displayed together with the other tags, and you would want it displayed somewhere else like next to the title of the post). This solution however looks to me as the proper path, as long as tags could support totally separate namespaces. I have a tentative implementation of this `tagtype` feature at [my git clone of ikiwiki](http://git.oblomov.eu/ikiwiki). + +The feature is currently implemented as follows: a `tagtypes` config options takes an array of strings: the tag types to be defined _aside from the usual tags_. Each tag type automatically provides a new directive which sets up tags that different from standard tags by having a different tagbase (the same as the tagtype) and link type (again, the same as the tagtype) (a TODO item for this would to make the directive, tagbase and link type customizable). For example, for my imported blog I would define + + tagtypes => [qw{Categoria Rubrica}] + +and then in the blog posts I would have stuff like + + \[[!Categoria "LAVORO/Vita da impiegato"]] + \[[!Rubrica "Il mio mondo"]] + \[[!meta title="Blah blah"]] + \[[!meta author="oblomov"]] + + The body of the article + + \[[!tag a bunch of tags]] + +and the tags would appear at the bottom of the post, the Rubrica next to the title, etc. All of this information would end up as categories in the feeds (although I would like to rework that code to make use of namespaces, terms and labels in a different way). + +> Note [[plugins/contrib/report/discussion]]. To quote myself from the latter page: +> *I find tags as they currently exist to be too limiting. I prefer something that can be used for Faceted Tagging http://en.wikipedia.org/wiki/Faceted_classification; that is, things like Author:Fred Nurk, Genre:Historical, Rating:Good, and so on. Of course, that doesn't mean that each tag is limited to only one value, either; just to take the above examples, something might have more than one author, or have multiple genres (such as Historical + Romance).* + +> So you aren't the only one who wants to do more with tags, but I don't think that adding a new directive for each tag type is the way to go; I think it would be simpler to just have one directive, and take advantage of the new [[matching different kinds of links]] functionality, and enhance the tag directive. +> Perhaps something like this: + + \[[!tag categorica="LAVORO/Vita da impiegato" rubrica="Il mio mondo"]] + +> Part of my thinking in this is to also combine tags with [[plugins/contrib/field]], so that the tags for a page could be queried and displayed; that way, one could put them wherever you wanted on the page, using any of [[plugins/contrib/getfield]], [[plugins/contrib/ftemplate]], or [[plugins/contrib/report]]. +> --[[KathrynAndersen]] + +>> A very generic metadata framework could cover all possible usages of fields, tags, and related metadata, but keeping its _user interface_ generic would only make it hard to use. Note that this is not an objection to the idea of collapsing the fields and tags functionality (at quick glance, I cannot see a real difference between single-valued custom tagtypes and fields, but see below), but more about the syntax. + +>> I had thought about the `\[[!tag type1=value1 type2=value2]]` syntax myself, but ultimately decided against it for a number of reasons, most importantly the fact that (1) it's harder to type, (2) it's harder to spot errors in the tag types (so for example if one misspelled `categoria` as `categorica`, he might not notice it as quickly as seeing the un-parsed `\[[!categorica ]]` directive in the output html) and (3) it encourages collapsing possibly unrelated metadata together (for example, I would never consider putting the categoria information together with the rubrica one; of course with your syntax it's perfectly possible to keep them separate as well). + +>> Point (2) may be considered a downside as well as an upside, depending on perspective, of course. And it would be possible to have a set of predefined tag types to match against, like in my tagtype directive approach but with your syntax. + +>>> You seem to have answered your own objections already. -- K.A. + +>>Point (3) is of course entirely in the hands of the user, but that's exactly what syntax should be about. There is nothing functionally wrong with e.g. `\[[!meta tag=sometag author=someauthor title=sometitle rubrica=somecolumn]]`, but I honestly find it horrible. + +>>> So, really, point 3 comes down to differing aesthetics. -- K.A. + +>> A solution could be to allow both syntaxes, getting to have for example `\[[!sometagtype "blah"]]` as a shortcut for `\[[!tag sometagtype="blah"]]` (or, in the more general case, `\[[!somefieldname "blah"]]` as a shortcut for `\[[!meta fieldname="blah"]]`). + +>> I would like to point out however that there are some functional differences between categorization metadata vs other metadata that might suggest to keep fields and (my extended) tags separate. For examples, in feeds you'd want all categorization metadata to fall in one place, with some appropriate manipulation (which I still have to implement, by the way), while things like author or title would go to the corresponding feed item properties. Although it all would be possible with appropriate report or template juggling, having such default metadata handled natively looks like a bonus to me. + +>>> Whereas I prefer being able to control such things with templates, because it gives more flexibility AND control. - K.A. + +>>>> Flexibility and control is good for tuning and power-usage, but sensible defaults are a must for a platform to be usable out of the box without much intervention. Moreover, there's a possible problem with what kind of data must be passed over to templates. + +Aside from the name of the plugin (and thus of the main directive), which could be `tag`, `meta`, `field` or whatever (maybe extending `meta` would be the most sensible choice), the features we want are + + 1. allow multiple values per type/attribute/field/whatever (fields currently only allows one) + 2. allow both hidden and visible references (à la tag vs taglink) + 3. allow each type/attribute/field to be exposed under multiple queries (e.g. tags and categories; this is mostly important for backwards compatibility, not sure if it might have other uses too) + 4. allow arbitrary types/attributes/fields/whatever (even 'undefined' ones) + +Each type/attribute/field/whatever (predefined, user-defined, arbitrary) would thus have the following parameters: + + * `directive` : the name of the directive that can be used to set the value as a hidden reference; we can discuss whether, for pre- or user-defined types, it being undef means no directive or a default directive matching the attribute name would be defined. + * `linkdirective` : the name of the directive that can be used for a visible reference; no such directive would be defined by default + * `linktype` : link type for (hidden and visible) references + * `linkbase` : akin to the tagbase parameter + * `queries` : list of template queries this type/attribute/field/whatever is exposed to + +Where this approach is limiting is on the kind of data that is passed to (template) queries. The value of the metadata fields might need some massaging (e.g. compare how tags are passed to tags queries vs cateogires queries). I have problems on picturing an easy way to make this possible user-side (i.e. via templates and not in Perl modules). Suggestions welcome. diff --git a/doc/todo/Separate_OpenIDs_and_usernames.mdwn b/doc/todo/Separate_OpenIDs_and_usernames.mdwn index 2cd52e8c4..fcdb49f6d 100644 --- a/doc/todo/Separate_OpenIDs_and_usernames.mdwn +++ b/doc/todo/Separate_OpenIDs_and_usernames.mdwn @@ -6,6 +6,45 @@ I see this being implemented in one of two possible ways. The easiest seems like A slightly more complex next step would be to request sreg from the provider and, if provided, automatically set the identity's username and email address from the provided persona. If username login to accounts with blank passwords is disabled, then you have the best of both worlds. Passwordless signin, human-friendly attribution, automatic setting of preferences. +> Given that openids are a global user identifier, that can look as pretty +> as the user cares to make it look via delegation, I am not a fan of +> having a site-local identifier that layered on top of that. Perhaps +> partly because every site that I have seen that does that has openid +> implemented as a badly-done wart on the side of their regular login +> system. +> +> The openid plugin now attempts to get an email and a username, and stores +> them in the session database for later use (ie, when the user edits a +> page). +> +> I am considering displaying the userid or fullname, if available, +> instead of the munged openid url in recentchanges and comments. +> It would be nice for those nasty [[google_openids|forum/google_openid_broken?]]. +> But, I first have to find a way to encode the name in the VCS commit log, +> while still keeping the openid of the committer in there too. +> Perhaps something like this (for git): --[[Joey]] +> +> Author: Joey Hess <http://joey.kitenet.net/@web> +> +> Only problem with the above is that the openid will still be displayed +> by CIA. Other option is this, which solves that, but at the expense of +> having to munge the username to fit inside the email address, +> and generally seems backwards: --[[Joey]] +> +> Author: http://joey.kitenet.net/ <Joey_Hess@web> +> +> So, what needs to be done: +> +> * Change `rcs_commit` and `rcs_commit_staged` to take a session object, +> instead of just a userid. (For back-compat, if the parameter is +> not an object, it's a userid.) Bump ikiwiki plugin interface version. +> * Modify all RCS plugins to include the session username somewhere +> in the commit, and parse it back out in `rcs_recentchanges`. +> * Modify recentchanges plugin to display the username instead of the +> `openiduser`. +> * Modify comment plugin to put the session username in the comment +> template instead of the `openiduser`. + Unfortunately I don't speak Perl, so hopefully someone thinks these suggestions are good enough to code up. I've hacked on openid code in Ruby before, so hopefully these changes aren't all that difficult to implement. Even if you don't get any data via sreg, you're no worse off than where you are now, so I don't think there'd need to be much in the way of error/sanity-checking of returned data. If it's null or not available then no big deal, typing in a username is no sweat. [[!tag wishlist]] diff --git a/doc/todo/abbreviation.mdwn b/doc/todo/abbreviation.mdwn index d24166710..f2880091c 100644 --- a/doc/todo/abbreviation.mdwn +++ b/doc/todo/abbreviation.mdwn @@ -2,4 +2,6 @@ We might want some kind of abbreviation and acronym plugin. --[[JoshTriplett]] * Not sure if this is what you mean, but I'd love a way to make works which match existing page names automatically like (eg. if there is a page called "MySQL" then any time the word MySQL is mentioned it should become a link to that page). -- [[AdamShand]] + * The python-markdown-extras package has support for [abbreviations](http://www.freewisdom.org/projects/python-markdown/Abbreviations), with the syntax that you just use the abbreviation in text (e.g. HTML) and then define the abbreviations at the end (like "footnote-style" links). For consistency, it might be good to use the same syntax, which apparently derives from [PHP-markdown-extra](http://michelf.com/projects/php-markdown/extra/#abbr). + [[wishlist]] diff --git a/doc/todo/allow_plugins_to_add_sorting_methods.mdwn b/doc/todo/allow_plugins_to_add_sorting_methods.mdwn new file mode 100644 index 000000000..b523cd19f --- /dev/null +++ b/doc/todo/allow_plugins_to_add_sorting_methods.mdwn @@ -0,0 +1,304 @@ +[[!tag patch]] + +The available [[ikiwiki/pagespec/sorting]] methods are currently hard-coded in +IkiWiki.pm, making it difficult to add any extra sorting mechanisms. I've +prepared a branch which adds 'sort' as a hook type and uses it to implement a +new `meta_title` sort type. + +Someone could use this hook to make `\[[!inline sort=title]]` prefer the meta +title over the page name, but for compatibility, I'm not going to (I do wonder +whether it would be worth making sort=name an alias for the current sort=title, +and changing the meaning of sort=title in 4.0, though). + +> What compatability concerns, exactly, are there that prevent making that +> change now? --[[Joey]] + +*[sort-hooks branch now withdrawn in favour of sort-package --s]* + +I briefly tried to turn *all* the current sort types into hook functions, and +have some of them pre-registered, but decided that probably wasn't a good idea. +That earlier version of the branch is also available for comparison: + +*[also withdrawn in favour of sort-package --s]* + +>> I wonder if IkiWiki would benefit from the concept of a "sortspec", like a [[ikiwiki/PageSpec]] but dedicated to sorting lists of pages rather than defining lists of pages? Rather than defining a sort-hook, define a SortSpec class, and enable people to add their own sort methods as functions defined inside that class, similarly to the way they can add their own pagespec definitions. --[[KathrynAndersen]] + +>>> [[!template id=gitbranch branch=smcv/ready/sort-package author="[[Simon_McVittie|smcv]]"]] +>>> I'd be inclined to think that's overkill, but it wasn't very hard to +>>> implement, and in a way is more elegant. I set it up so sort mechanisms +>>> share the `IkiWiki::PageSpec` package, but with a `cmp_` prefix. Gitweb: +>>> <http://git.pseudorandom.co.uk/smcv/ikiwiki.git?a=shortlog;h=refs/heads/sort-package> + +>>>> I agree it seems more elegant, so I have focused on it. +>>>> +>>>> I don't know about reusing `IkiWiki::PageSpec` for this. +>>>> --[[Joey]] + +>>>>> Fair enough, `IkiWiki::SortSpec::cmp_foo` would be just +>>>>> as easy, or `IkiWiki::Sorting::cmp_foo` if you don't like +>>>>> introducing "sort spec" in the API. I took a cue from +>>>>> [[ikiwiki/pagespec/sorting]] being a subpage of +>>>>> [[ikiwiki/pagespec]], and decided that yes, sorting is +>>>>> a bit like a pagespec :-) Which name would you prefer? --s + +>>>>>> `SortSpec` --[[Joey]] + +>>>>>>> [[Done]]. --s + +>>>> I would be inclined to drop the `check_` stuff. --[[Joey]] + +>>>>> It basically exists to support `title_natural`, to avoid +>>>>> firing up the whole import mechanism on every `cmp` +>>>>> (although I suppose that could just be a call to a +>>>>> memoized helper function). It also lets sort specs that +>>>>> *must* have a parameter, like +>>>>> [[field|plugins/contrib/field/discussion]], fail early +>>>>> (again, not so valuable). +>>>>> +>>>>>> AFAIK, `use foo` has very low overhead when the module is already +>>>>>> loaded. There could be some evalation overhead in `eval q{use foo}`, +>>>>>> if so it would be worth addressing across the whole codebase. +>>>>>> --[[Joey]] +>>>>>> +>>>>>>> check_cmp_foo now dropped. --s +>>>>> +>>>>> The former function could be achieved at a small +>>>>> compatibility cost by putting `title_natural` in a new +>>>>> `sortnatural` plugin (that fails to load if you don't +>>>>> have `title_natural`), if you'd prefer - that's what would +>>>>> have happened if `title_natural` was written after this +>>>>> code had been merged, I suspect. Would you prefer this? --s + +>>>>>> Yes! (Assuming it does not make sense to support +>>>>>> natural order sort of other keys than the title, at least..) +>>>>>> --[[Joey]] + +>>>>>>> Done. I added some NEWS.Debian for it, too. --s + +>>>> Wouldn't it make sense to have `meta(title)` instead +>>>> of `meta_title`? --[[Joey]] + +>>>>> Yes, you're right. I added parameters to support `field`, +>>>>> and didn't think about making `meta` use them too. +>>>>> However, `title` does need a special case to make it +>>>>> default to the basename instead of the empty string. +>>>>> +>>>>> Another special case for `title` is to use `titlesort` +>>>>> first (the name `titlesort` is derived from Ogg/FLAC +>>>>> tags, which can have `titlesort` and `artistsort`). +>>>>> I could easily extend that to other metas, though; +>>>>> in fact, for e.g. book lists it would be nice for +>>>>> `field(bookauthor)` to behave similarly, so you can +>>>>> display "Douglas Adams" but sort by "Adams, Douglas". +>>>>> +>>>>> `meta_title` is also meant to be a prototype of how +>>>>> `sort=title` could behave in 4.0 or something - sorting +>>>>> by page name (which usually sorts in approximately the +>>>>> same place as the meta-title, but occasionally not), while +>>>>> displaying meta-titles, does look quite odd. --s + +>>>>>> Agreed. --[[Joey]] + +>>>>>>> I've implemented meta(title). meta(author) also has the +>>>>>>> `sortas` special case; meta(updated) and meta(date) +>>>>>>> should also work how you'd expect them to (but they're +>>>>>>> earliest-first, unlike age). --s + +>>>> As I read the regexp in `cmpspec_translate`, the "command" +>>>> is required to have params. They should be optional, +>>>> to match the documentation and because most sort methods +>>>> do not need parameters. --[[Joey]] + +>>>>> No, `$2` is either `\w+\([^\)]*\)` or `[^\s]+` (with the +>>>>> latter causing an error later if it doesn't also match `\w+`). +>>>>> This branch doesn't add any parameterized sort methods, +>>>>> in fact, although I did provide one on +>>>>> [[field's_discussion_page|plugins/contrib/report/discussion]]. --s + +>>>> I wonder if it would make sense to add some combining keywords, so +>>>> a sortspec reads like `sort="age then ascending title"` +>>>> In a way, this reduces the amount of syntax that needs to be learned. +>>>> I like the "then" (and it could allow other operations than +>>>> simple combination, if any others make sense). Not so sure about the +>>>> "ascending", which could be "reverse" instead, but "descending age" and +>>>> "ascending age" both seem useful to be able to explicitly specify. +>>>> --[[Joey]] + +>>>>> Perhaps. I do like the simplicity of [[KathrynAndersen]]'s syntax +>>>>> from [[plugins/contrib/report]] (which I copied verbatim, except for +>>>>> turning sort-by-`field` into a parameterized spec). +>>>>> +>>>>> If we're getting into English-like (or at least SQL-like) queries, +>>>>> it might make sense to change the signature of the hook function +>>>>> so it's a function to return a key, e.g. +>>>>> `sub key_age { return -%pagemtime{$_[0]) }`. Then we could sort like +>>>>> this: +>>>>> +>>>>> field(artistsort) or field(artist) or constant(Various Artists) then meta(titlesort) or meta(title) or title +>>>>> +>>>>> with "or" binding more closely than "then". Does this seem valuable? +>>>>> I think the implementation would be somewhat more difficult. and +>>>>> it's probably getting too complicated to be worthwhile, though? +>>>>> (The keys that actually benefit from this could just +>>>>> have smarter cmp functions, I think.) +>>>>> +>>>>> If the hooks return keys rather than cmp results, then we could even +>>>>> have "lowercase" as an adjective used like "ascending"... maybe. +>>>>> However, there are two types of adjective here: "lowercase" +>>>>> really applies to the keys, whereas "ascending" applies to the "cmp" +>>>>> result. Again, I think this is getting too complex, and could just +>>>>> be solved with smarter cmp functions. +>>>>> +>>>>>> I agree. (Also, I think returning keys may make it harder to write +>>>>>> smarter cmp functions.) --[[Joey]] +>>>>> +>>>>> Unfortunately, `sort="ascending mtime"` actually sorts by *descending* +>>>>> timestamp (but`sort=age` is fine, because `age` could be defined as +>>>>> now minus `ctime`). `sort=freshness` isn't right either, because +>>>>> "sort by freshness" seems as though it ought to mean freshest first, +>>>>> but "sort by ascending freshness" means put the least fresh first. If +>>>>> we have ascending and descending keywords which are optional, I don't +>>>>> think we really want different sort types to have different default +>>>>> directions - it seems clearer to have `ascending` always be a no-op, +>>>>> and `descending` always negate. +>>>>> +>>>>>> I think you've convinced me that ascending/descending impose too +>>>>>> much semantics on it, so "-" is better. --[[Joey]] + +>>>>>>> I've kept the semantics from `report` as-is, then: +>>>>>>> e.g. `sort="age -title"`. --s + +>>>>> Perhaps we could borrow from `meta updated` and use `update_age`? +>>>>> `updateage` would perhaps be a more normal IkiWiki style - but that +>>>>> makes me think that updateage is a quantity analagous to tonnage or +>>>>> voltage, with more or less recently updated pages being said to have +>>>>> more or less updateage. I don't know whether that's good or bad :-) +>>>>> +>>>>> I'm sure there's a much better word, but I can't see it. Do you have +>>>>> a better idea? --s + +[Regarding the `meta title=foo sort=bar` special case] + +> I feel it sould be clearer to call that "sortas", since "sort=" is used +> to specify a sort method in other directives. --[[Joey]] +>> Done. --[[smcv]] + +## speed + +I notice the implementation does not use the magic `$a` and `$b` globals. +That nasty perl optimisation is still worthwhile: + + perl -e 'use warnings; use strict; use Benchmark; sub a { $a <=> $b } sub b ($$) { $_[0] <=> $_[1] }; my @list=reverse(1..9999); timethese(10000, {a => sub {my @f=sort a @list}, b => sub {my @f=sort b @list}, c => => sub {my @f=sort { b($a,$b) } @list}})' + Benchmark: timing 10000 iterations of a, b, c... + a: 80 wallclock secs (76.74 usr + 0.05 sys = 76.79 CPU) @ 130.23/s (n=10000) + b: 112 wallclock secs (106.14 usr + 0.20 sys = 106.34 CPU) @ 94.04/s (n=10000) + c: 330 wallclock secs (320.25 usr + 0.17 sys = 320.42 CPU) @ 31.21/s (n=10000) + +Unfortunatly, I think that c is closest to the new implementation. +--[[Joey]] + +> Unfortunately, `$a` isn't always `$main::a` - it's `$Package::a` where +> `Package` is the call site of the sort call. This was a showstopper when +> `sort` was a hook implemented in many packages, but now that it's a +> `SortSpec`, I may be able to fix this by putting a `sort` wrapper in the +> `SortSpec` namespace, so it's like this: +> +> sub sort ($@) +> { +> my $cmp = shift; +> return sort $cmp @_; +> } +> +> which would mean that the comparison used `$IkiWiki::SortSpec::a`. +> --s + +>> I've now done this. On a wiki with many [[plugins/contrib/album]]s +>> (a full rebuild takes half an hour!), I tested a refresh after +>> `touch tags/*.mdwn` (my tag pages contain inlines of the form +>> `tagged(foo)` sorted by date, so they exercise sorting). +>> I also tried removing sorting from `pagespec_match_list` +>> altogether, as an upper bound for how fast we can possibly make it. +>> +>> * `master` at branch point: 63.72user 0.29system +>> * `master` at branch point: 63.91user 0.37system +>> * my branch, with `@_`: 65.28user 0.29system +>> * my branch, with `@_`: 65.21user 0.28system +>> * my branch, with `$a`: 64.09user 0.28system +>> * my branch, with `$a`: 63.83user 0.36system +>> * not sorted at all: 58.99user 0.29system +>> * not sorted at all: 58.92user 0.29system +>> +>> --s + +> I do notice that `pagespec_match_list` performs the sort before the +> filter by pagespec. Is this a deliberate design choice, or +> coincidence? I can see that when `limit` is used, this could be +> used to only run the pagespec match function until `limit` pages +> have been selected, but the cost is that every page in the wiki +> is sorted. Or, it might be useful to do the filtering first, then +> sort the sub-list thus produced, then finally apply the limit? --s + +>> Yes, it was deliberate, pagespec matching can be expensive enough that +>> needing to sort a lot of pages seems likely to be less work. (I don't +>> remember what benchmarking was done though.) --[[Joey]] + +>>> We discussed this on IRC and Joey pointed out that this also affects +>>> dependency calculation, so I'm not going to get into this now... --s + +Joey pointed out on IRC that the `titlesort` feature duplicates all the +meta titles. I did that in order to sort by the unescaped version, but +I've now changed the branch to only store that if it makes a difference. +--s + +## Documentation from sort-package branch + +### advanced sort orders (conditionally added to [[ikiwiki/pagespec/sorting]]) + +* `title_natural` - Orders by title, but numbers in the title are treated + as such, ("1 2 9 10 20" instead of "1 10 2 20 9") +* `meta(title)` - Order according to the `\[[!meta title="foo" sortas="bar"]]` + or `\[[!meta title="foo"]]` [[ikiwiki/directive]], or the page name if no + full title was set. `meta(author)`, `meta(date)`, `meta(updated)`, etc. + also work. + +### Multiple sort orders (added to [[ikiwiki/pagespec/sorting]]) + +In addition, you can combine several sort orders and/or reverse the order of +sorting, with a string like `age -title` (which would sort by age, then by +title in reverse order if two pages have the same age). + +### meta sortas parameter (added to [[ikiwiki/directive/meta]]) + +[in title] + +An optional `sort` parameter will be used preferentially when +[[ikiwiki/pagespec/sorting]] by `meta(title)`: + + \[[!meta title="The Beatles" sort="Beatles, The"]] + + \[[!meta title="David Bowie" sort="Bowie, David"]] + +[in author] + + An optional `sortas` parameter will be used preferentially when + [[ikiwiki/pagespec/sorting]] by `meta(author)`: + + \[[!meta author="Joey Hess" sortas="Hess, Joey"]] + +### Sorting plugins (added to [[plugins/write]]) + +Similarly, it's possible to write plugins that add new functions as +[[ikiwiki/pagespec/sorting]] methods. To achieve this, add a function to +the IkiWiki::SortSpec package named `cmp_foo`, which will be used when sorting +by `foo` or `foo(...)` is requested. + +The names of pages to be compared are in the global variables `$a` and `$b` +in the IkiWiki::SortSpec package. The function should return the same thing +as Perl's `cmp` and `<=>` operators: negative if `$a` is less than `$b`, +positive if `$a` is greater, or zero if they are considered equal. It may +also raise an error using `error`, for instance if it needs a parameter but +one isn't provided. + +The function will also be passed one or more parameters. The first is +`undef` if invoked as `foo`, or the parameter `"bar"` if invoked as `foo(bar)`; +it may also be passed additional, named parameters. diff --git a/doc/todo/allow_site-wide_meta_definitions.mdwn b/doc/todo/allow_site-wide_meta_definitions.mdwn index 99a9cf1e2..82670250e 100644 --- a/doc/todo/allow_site-wide_meta_definitions.mdwn +++ b/doc/todo/allow_site-wide_meta_definitions.mdwn @@ -36,6 +36,30 @@ definitions essentially. >> I've made may not be acceptable, though -- I'd appreciate someone providing >> some feedback on that hunk! +>>> Well, re that hunk, taint checking is currently disabled, but +>>> if the perl bug that disallows it is fixed and it is turned back on, +>>> the hash values will remain tainted, which will probably lead to +>>> problems. +>>> +>>> I'm also leery of using such a complex data structure in config. +>>> The websetup plugin would be hard pressed to provide a UI for such a +>>> data structure. (It lacks even UI for a single hash ref yet, let alone +>>> a list.) +>>> +>>> Also, it seems sorta wrong to have two so very different syntaxes to +>>> represent the same meta data. A user without a lot of experience will +>>> be hard pressed to map from a directive to this in the setup file. +>>> +>>> All of which leads me to think the setup file could just contain +>>> a text that could hold meta directives. Which generalizes really to +>>> a text that contains any directives, and is, perhaps appended to the +>>> top of every page. Which nearly generalizes to the sidebar plugin, +>>> or perhaps something more general than that... +>>> +>>> However, excessive generalization is the root of all evil, so +>>> I'm not necessarily saying that's a good idea. Indeed, my memory +>>> concerns below invalidate this idea pretty well. --[[Joey]] + diff --git a/IkiWiki/Plugin/meta.pm b/IkiWiki/Plugin/meta.pm index 6fe9cda..2f8c098 100644 --- a/IkiWiki/Plugin/meta.pm @@ -125,6 +149,10 @@ definitions essentially. >> are only relevant to defined fields that you wouldn't want to specify a >> global default for anyway. >> +>>> I generally agree with this. It is *possible* that meta would have a new +>>> field added, that takes parameters and make sense to use globally. +>>> --[[Joey]] +>> >> Due to this, and the added complexity of the second patch (having to adjust >> `IkiWiki/Setup.pm`), I think the first patch makes more sense. I've thus >> reverted to it here. @@ -183,3 +211,36 @@ definitions essentially. >>> ikiwiki for the break, and now I've returned to watching recentchanges. >>> Hopefully I'll be back in the mix soon, too. In the meantime, Joey, have >>> you had a chance to look at this yet? -- [[Jon]] + +>>>> Ping :) Hi. [[Joey]], would you consider this patch for the next +>>>> ikiwiki release? -- [[Jon]] + +>>> For this to work with websetup and --dumpsetup, it needs to define the +>>> `meta_*` settings in the getsetup function. +>>>> +>>>> I think this will be problematic with the current implementation of this +>>>> patch. The datatype here is an array of hash references, with each hash +>>>> having a variable (and arbitrary) number of key/value pairs. I can't +>>>> think of an intuitive way of implementing a way of editing such a +>>>> datatype in the web interface, let alone registering the option in +>>>> getsetup. +>>>> +>>>> Perhaps a limited set of defined meta values could be exposed via +>>>> websetup (the obvious ones: author, copyright, license, etc.) -- [[Jon]] +>>> +>>> I also have some concerns about both these patches, since both throw +>>> a lot of redundant data at meta, which then stores it in a very redundant +>>> way. Specifically, meta populates a per-page `%metaheaders` hash +>>> as well as storing per-page metadata in `%pagestate`. So, if you have +>>> a wiki with 10 thousand pages, and you add a 1k site-wide license text, +>>> that will bloat the memory usage of ikiwiki by in excess of 2 +>>> megabytes. It will also cause ikiwiki to write a similar amount more data +>>> to its state file which has to be loaded back in each +>>> run. +>>> +>>> Seems that this could be managed much more efficiently by having +>>> meta special-case the site-wide settings, not store them in these +>>> per-page data structures, and just make them be used if no per-page +>>> metadata of the given type is present. --[[Joey]] +>>>> +>>>> that should be easy enough to do. I will work on a patch. -- [[Jon]] 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 f1d33114f..def55f3ee 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 @@ -4,7 +4,7 @@ Tags are mainly specific to the object to which they’re stuck. However, I ofte Also see: <http://madduck.net/blog/2008.01.06:new-blog/> and <http://users.itk.ppke.hu/~cstamas/code/ikiwiki/autocreatetagpage/> -[[!tag wishlist plugins/tag patch]] +[[!tag wishlist plugins/tag patch patch/core]] I would love to see this as well. -- dato @@ -123,3 +123,164 @@ On the second extra pass, it doesn't notice that it has to update the "?"-link. } is not satisfied for the newly created tag page. I shall put debug msgs into Render.pm to find out better how it works. --Ivan Z. + +--- + +I've made another attempt at fixing this + +The current progress can be found at my [git repository][gitweb] on branch +`autotag`: + + git://git.liegesta.at/git/ikiwiki + +[gitweb]: http://git.liegesta.at/?p=ikiwiki.git;a=shortlog;h=refs/heads/autotag (gitweb for branch autotag) + +It's not entirely finished yet, but already quite usable. Testing and comments +on code quality, implementation details, as well as other patches would be +appreciated. + +Here's what it does right now: + +* enabled by setting `tag_autocreate=1` in the configuration. +* Tag pages will be created in `tagbase` from the template `autotag.tmpl`. +* Will correctly render all links, and dependencies. Well, AFAIK. +* When a tag page is deleted it will automatically recreated from template. (I +consider this a feature, not a bug) +* Requires a rebuild on first use. +* Adds a function `add_autofile()` to the plugin API, to do all this. + +Todo/Bugs: + +* Will still create a page even if there's a page other than `$tag` under +`tagbase` satisfying the tag link. +* Call from `IkiWiki.pm` to `Render.pm`, which adds a module dependency in the +wrong direction. +* Add files to RCS. +* Unit tests. +* Proper documentation. + +--[[David_Riebenbauer]] + +> Starting review of this. Some of your commits are to very delicate, +> optimised, and security-sensitive ground, so I have to look at them very +> carefully. --[[Joey]] + +>> First of, sorry that it took me so damn long to answer. I didn't lose +>> interest but it took a while for me to find the time and motivation +>> to address you suggestions. --[[David_Riebenbauer]] + +> * In the refactoring in [f3abeac919c4736429bd3362af6edf51ede8e7fe][], +> you introduced at least 2 bugs, one a possible security hole. +> Now one part of the code tests `if ($file)` and the other +> caller tests `if ($f)`. These two tests both tested `if (! defined $f)` +> before. Notice that the variable needs to be the untainted variable +> for both. Also notice that `if ($f)` fails if `$f` contains `0`, +> which is a very common perl gotcha. +> * Your refactored code changes `-l $_ || -d _` to `-l $file || -d $file`. +> The latter makes one more stat system call; note the use of a +> bare `_` in the first to make perl reuse the stat buffer. +> * (As a matter of style, could you put a space after the commas in your +> perl?) + +>> The first two points should be addressed in +>> [da5d29f95f6e693e8c14be1b896cf25cf4fdb3c0][]. And sure, I can add the +>> spaces. --[[David_Riebenbauer]] + +> I'd like to cherry-pick the above commit, once it's in shape, before +> looking at the rest in detail. So just a few other things that stood out. +> +> * Commit [4af4d26582f0c2b915d7102fb4a604b176385748][] seems unnecessary. +> `srcfile($file, 1)` already is documented to return undef if the +> file does not exist. (But without the second parameter, it throws +> an error.) + +>> You're right. I must have been some confused by some other promplem I +>> introduced then. Reverted. --[[David_Riebenbauer]] + +> * Commit [f58f3e1bec41ccf9316f37b014ce0b373c8e49e1][] adds a line +> that is intented by a space, not a tab. + +>> Sorry, That one was reverted anyway. --[[David_Riebenbauer]] + +> * Commit [f58f3e1bec41ccf9316f37b014ce0b373c8e49e1][] says that auto-added +> files will be recreated if the user deletes them. That seems bad. +> `autoindex` goes to some trouble to not recreate deleted files. + +>> I reverted the commit and addressed the issue in +>> [a358d74bef51dae31332ff27e897fe04834571e6][] and +>> [981400177d68a279f485727be3f013e68f0bf691][]. + --[[David_Riebenbauer]] + +>>> This doesn't seem to have all the refinements that autoindex has: +>>> +>>> * `autoindex` attaches the record of deletions to the `index` page, which +>>> is (nearly) guaranteed to exist; this one attaches the record of +>>> deletions to the deleted page's page state. Won't that tend to result +>>> in losing the record along with the deleted page? + +>>>> This is probably on of the harder things to do, 'cause there are (most of the +>>>> time) several pages that are responsible for the creation of a single tag page. +>>>> Of course I could attach the info to all of them. + +>>>> With current behaviour I think the information in `%pagestate` is kept around +>>>> regardless whether the corresponding page exists or not. +>>>> --[[David_Riebenbauer]] + +>>>>> Sorry, I'll try to be clearer: `autoindex` hard-codes that the [[index]] page +>>>>> of the entire wiki is the one responsible for storing the page state. That +>>>>> page isn't responsible for the creation of the tag page, it's just an +>>>>> arbitrary page that's (more or less) guaranteed to exist. --[[smcv]] + +>>>>> I don't like that [[plugins/autoindex]] has to do that, +>>>>> but `%pagestate` values are only stored for pages that exist, +>>>>> so it was necessary. (Another way to look at this is that +>>>>> `%pagestate` is not the ideal data structure.) --[[Joey]] + +>>>>>> Aha! Having looked at [[plugins/write]] again, it turns out that what this +>>>>>> feature should really use is `%wikistate`, I think? :-) --[[smcv]] + +>>>>>>> Ah, indeed, that came after I wrote autoindex. I've fixed autoindex to +>>>>>>> use it. --[[Joey]] + +>>>>> Ok, now I know what you mean. --[[David_Riebenbauer]] + +>>> * `autoindex` forgets that a page was deleted when that page is +>>> re-created + +>>>> Yes, I forgot about that and that is a bug. I'll fix that. +>>>> --[[David_Riebenbauer]] + +>>> * `autoindex` forgets that a page was deleted when it's no longer needed +>>> anyway (this may be harder for `autotag`?) + +>>>> I don't think so. AFAIK ikiwiki can detect whether there are taglinks to a page +>>>> anyway, so it should be quite easy. I'll try to implement that too. +>>>> --[[David_Riebenbauer]] + +>>> It'd probably be an interesting test of the core change to port +>>> `autoindex` to use it? (Adding the file to the RCS would be +>>> necessary to get parity with `autoindex`.) --[[smcv]] + +>>>> Good suggestion. Adding the files to RCS is on my todo list anyway. +>>>> --[[David_Riebenbauer]] + +> Regarding the call from `IkiWiki.pm` to `Render.pm`, wouldn't this be +> quite easy to solve by moving `verify_src_file` to IkiWiki.pm? --[[smcv]] + +>> True. I'll do that. --[[David_Riebenbauer]] + +> Seems that `%autofiles` stores plugin names as keys, but never +> really uses them. So it could just as easily be an array. +> +> I'd be happy if the `%del_hash` global were not needed. +> Looks like it could be avoided by moving the checks +> that `add_autofile` does into the autofile handling loop in +> `Render`. (Also, that loop should probably be in its own +> function anyway.) --[[Joey]] + +[f3abeac919c4736429bd3362af6edf51ede8e7fe]: http://git.liegesta.at/?p=ikiwiki.git;a=commitdiff;h=f3abeac919c4736429bd3362af6edf51ede8e7fe (commitdiff for f3abeac919c4736429bd3362af6edf51ede8e7fe) +[4af4d26582f0c2b915d7102fb4a604b176385748]: http://git.liegesta.at/?p=ikiwiki.git;a=commitdiff;h=4af4d26582f0c2b915d7102fb4a604b176385748 (commitdiff for 4af4d26582f0c2b915d7102fb4a604b176385748) +[f58f3e1bec41ccf9316f37b014ce0b373c8e49e1]: http://git.liegesta.at/?p=ikiwiki.git;a=commitdiff;h=f58f3e1bec41ccf9316f37b014ce0b373c8e49e1 (commitdiff for f58f3e1bec41ccf9316f37b014ce0b373c8e49e1) +[da5d29f95f6e693e8c14be1b896cf25cf4fdb3c0]: http://git.liegesta.at/?p=ikiwiki.git;a=commitdiff;h=da5d29f95f6e693e8c14be1b896cf25cf4fdb3c0 (commitdiff for da5d29f95f6e693e8c14be1b896cf25cf4fdb3c0) +[a358d74bef51dae31332ff27e897fe04834571e6]: http://git.liegesta.at/?p=ikiwiki.git;a=commitdiff;h=a358d74bef51dae31332ff27e897fe04834571e6 (commitdiff for a358d74bef51dae31332ff27e897fe04834571e6) +[981400177d68a279f485727be3f013e68f0bf691]: http://git.liegesta.at/?p=ikiwiki.git;a=commitdiff;h=981400177d68a279f485727be3f013e68f0bf691 (commitdiff for 981400177d68a279f485727be3f013e68f0bf691) diff --git a/doc/todo/auto_getctime_on_fresh_build.mdwn b/doc/todo/auto_getctime_on_fresh_build.mdwn new file mode 100644 index 000000000..760c56fa1 --- /dev/null +++ b/doc/todo/auto_getctime_on_fresh_build.mdwn @@ -0,0 +1,13 @@ +[[!tag wishlist]] + +It might be a good idea to enable --gettime when `.ikiwiki` does not +exist. This way a new checkout of a `srcdir` would automatically get +ctimes right. (Running --gettime whenever a rebuild is done would be too +slow.) --[[Joey]] + +Could this be too annoying in some cases, eg, checking out a large wiki +that needs to get set up right away? --[[Joey]] + +> Not for git with the new, optimised --getctime. For other VCS.. well, +> pity they're not as fast as git ;), but it is a one-time expense... +> [[done]] --[[Joey]] diff --git a/doc/todo/avatar.mdwn b/doc/todo/avatar.mdwn index b8aa2327f..f0599e4ed 100644 --- a/doc/todo/avatar.mdwn +++ b/doc/todo/avatar.mdwn @@ -1,38 +1,19 @@ [[!tag wishlist]] It would be nice if ikiwiki, particularly [[plugins/comments]] -supported user avatar icons. I was considering adding a directive for this, -as designed below. +(but also, ideally, recentchanges) supported user avatar icons. -However, there is no *good* service for mapping openids to avatars -- -openavatar has many issues, including not supporting delegated openids, and -after trying it, I don't trust it to push users toward. -Perhaps instead ikiwiki could get the email address from the openid -provider, though I think the perl openid modules don't support the openid -2.x feature that allows that. - -At the moment, working on this doesn't feel like a good use of my time. ---[[Joey]] - -Hmm.. unless is just always used a single provider (gravatar) and hashed -the openid. Then wavatars could be used to get a unique avatar per openid -at least. --[[Joey]] - ----- - -The directive displays a small avatar image for a user. Pass it the -email address, openid, or wiki username of the user. +Idea is to add a directive that displays a small avatar image for a user. +Pass it a user's the email address, openid, username, or the md5 hash +of their email address: \[[!avatar user@example.com]] \[[!avatar http://joey.kitenet.net/]] \[[!avatar user]] + \[[!avatar hash]] -The avatars are provided by various sites. For email addresses, it uses a -[gravatar](http://gravatar.com/). For openid, -[openavatar](http://www.openvatar.com/) is used. For a wiki username, the -user's email address is looked up and the gravatar for that user is -displayed. (Of course, the user has to have filled in their email address -on their Preferences page for that to work.) +These directives can then be hand-inserted onto pages, or more likely, +included in eg, a comment post via a template. An optional second parameter can be included, containing additional options to pass in the @@ -45,3 +26,35 @@ not have a gravatar, uses a cute auto-generated "wavatar" avatar. The `gravitar_options` setting in the setup file can be used to specify additional options to pass. So for example if you want to use wavatars everywhere, set it to "default=wavatar". + +The avatars are provided by various sites. For email addresses, it uses a +[gravatar](http://gravatar.com/). For a wiki username, the +user's email address is looked up and the gravatar for that user is +displayed. (Of course, the user has to have filled in their email address +on their Preferences page for that to work. Also, when the user changes +their email address in Preferences, the gravatar won't change until the +wiki is rebuilt.) + +For openid, openavatar sucked and is now dead. So we need to use an email +address instead, I guess. Problem is that the email address of a given +openid is only known when that user is logged in and making a change. +And we don't want to leak an openid user's email into a page either. +Hmm. Suppose the gravatar hash could be calculated from the email address +and embedded instead of the openid? That would work for comments, +but not if the directive were used elsewhere. + +Or, for openid, could use <http://paulisageek.com/openidavatar>. Which +works fine, but users are not likely to figure out what they need to do to +get an avatar associated with their openid. + +--- + +Alternative, not overdesigned approach: + +Modify comments plugin to have an option to display avatars. + +When posting a comment, fill in the avatarhash field in the template. +The hash is calculated from the user's email address. If the user's email +is not known, skip it. + +End. :P diff --git a/doc/todo/beef_up_sidebar_to_allow_for_multiple_sidebars.mdwn b/doc/todo/beef_up_sidebar_to_allow_for_multiple_sidebars.mdwn index fb942a495..02b83244e 100644 --- a/doc/todo/beef_up_sidebar_to_allow_for_multiple_sidebars.mdwn +++ b/doc/todo/beef_up_sidebar_to_allow_for_multiple_sidebars.mdwn @@ -13,5 +13,57 @@ those contents instead. > In mine I just copied sidebar out and made some extra "sidebars", but they go elsewhere. Ugly hack, but it works. --[[simonraven]] +>> Here a simple [[patch]] for multiple sidebars. Not too fancy but better than having multiple copies of the sidebar plugin. --[[jeanprivat]] + +<pre> +--- /usr/share/perl5/IkiWiki/Plugin/sidebar.pm 2010-02-11 22:53:17.000000000 -0500 ++++ plugins/IkiWiki/Plugin/sidebar.pm 2010-02-27 09:54:12.524412391 -0500 +@@ -19,12 +19,20 @@ + safe => 1, + rebuild => 1, + }, ++ active_sidebars => { ++ type => "string", ++ example => qw(sidebar banner footer), ++ description => "Which sidebars must be activated and processed.", ++ safe => 1, ++ rebuild => 1 ++ }, + } + +-sub sidebar_content ($) { ++sub sidebar_content ($$) { + my $page=shift; ++ my $sidebar=shift; + +- my $sidebar_page=bestlink($page, "sidebar") || return; ++ my $sidebar_page=bestlink($page, $sidebar) || return; + my $sidebar_file=$pagesources{$sidebar_page} || return; + my $sidebar_type=pagetype($sidebar_file); + +@@ -49,11 +57,17 @@ + + my $page=$params{page}; + my $template=$params{template}; +- +- if ($template->query(name => "sidebar")) { +- my $content=sidebar_content($page); +- if (defined $content && length $content) { +- $template->param(sidebar => $content); ++ ++ my @sidebars; ++ if (defined $config{active_sidebars} && length $config{active_sidebars}) { @sidebars = @{$config{active_sidebars}}; } ++ else { @sidebars = qw(sidebar); } ++ ++ foreach my $sidebar (@sidebars) { ++ if ($template->query(name => $sidebar)) { ++ my $content=sidebar_content($page, $sidebar); ++ if (defined $content && length $content) { ++ $template->param($sidebar => $content); ++ } + } + } + } +</pre> [[!tag wishlist]] diff --git a/doc/todo/cdate_and_mdate_available_for_templates.mdwn b/doc/todo/cdate_and_mdate_available_for_templates.mdwn new file mode 100644 index 000000000..70d8fc8c9 --- /dev/null +++ b/doc/todo/cdate_and_mdate_available_for_templates.mdwn @@ -0,0 +1,15 @@ +[[!tag wishlist]] + +`CDATE_3339`, `CDATE_822`, `MDATE_3339` and `MDATE_822` template variables would be useful for evey page, at least for my templates with Dublin Core metadata. + +I tried to pick the relevant lines of the [[inline|plugins/inline]] plugin and hack it into a custom plugin, but it failed miserably because of my obvious lack of perl litteracy... + +Anyway, I'm sure this is almost nothing... + +* `sub date_822 ($) {}` +* `sub date_3339 ($) {}` +* and something like `$template->param('cdate_822' => date_822($IkiWiki::pagectime{$page}));` + +Anyone can fill the missing lines? + +-- [[nil]] diff --git a/doc/todo/conflict_free_comment_merges.mdwn b/doc/todo/conflict_free_comment_merges.mdwn index 2cef0ee8c..e84400c17 100644 --- a/doc/todo/conflict_free_comment_merges.mdwn +++ b/doc/todo/conflict_free_comment_merges.mdwn @@ -20,4 +20,4 @@ What do you think [[smcv]]? --[[Joey]] > are quite low since it modifies the input text and adds a date stamp to > it. > -> Anyway, I think it's good, [[[done]] --[[Joey]] +> Anyway, I think it's good, [[done]] --[[Joey]] diff --git a/doc/todo/double-click_protection_for_form_buttons.mdwn b/doc/todo/double-click_protection_for_form_buttons.mdwn new file mode 100644 index 000000000..501be4498 --- /dev/null +++ b/doc/todo/double-click_protection_for_form_buttons.mdwn @@ -0,0 +1,5 @@ +A small piece of JS to prevent double-submitting forms would be quite nice. I seem to have developed a habit of doing this and having to resolve a merge conflict for two initial commits. -- [[Jon]] + +> By the time you see that merge conflict, the first commit has +> already successfully happened, so you can just hit cancel +> and throw away the second submit. --[[Joey]] diff --git a/doc/todo/enable-htaccess-files.mdwn b/doc/todo/enable-htaccess-files.mdwn index 412cb5eba..3b9721d50 100644 --- a/doc/todo/enable-htaccess-files.mdwn +++ b/doc/todo/enable-htaccess-files.mdwn @@ -12,6 +12,13 @@ qr/(^|\/).svn\//, qr/.arch-ids\//, qr/{arch}\//], wiki_link_regexp => qr/\[\[(?:([^\]\|]+)\|)?([^\s\]#]+)(?:#([^\s\]]+))?\]\]/, +> Note that the above patch is **completely broken**. +> It removes the crucial excludes of all files starting with a dot. +> The negative regexps for htaccess have no effect, so the whole +> thing only "works" because it allows *any* file starting with a dot. +> If you applied this patch to your ikiwiki, you opened a huge security +> hole. --[[Joey]] + [[!tag patch patch/core]] This lets the site administrator have a `.htaccess` file in their underlay @@ -57,7 +64,17 @@ It should be off by default of course. --Max --- +1 I want `.htaccess` so I can rewrite some old Wordpress URLs to make feeds work again. --[[hendry]] +> Unless you cannot modify apache's configuration, you do not need htaccess +> to do that. Apache's documentation recommends against using htaccess +> unless you're a user who cannot modify the main server configuration. +> --[[Joey]] + --- +1 for various purposes (but sometimes the filename isn't `.htaccess`, so please make it configurable) --[[schmonz]] > I've described a workaround for one use case at the [[plugins/rsync]] [[plugins/rsync/discussion]] page. --[[schmonz]] + +--- + +[[done]], you can use the `include` setting to override the default +excludes now. Please use extreme caution when doing so. --[[Joey]] diff --git a/doc/todo/finer_control_over___60__object___47____62__s.mdwn b/doc/todo/finer_control_over___60__object___47____62__s.mdwn new file mode 100644 index 000000000..50c4d43bf --- /dev/null +++ b/doc/todo/finer_control_over___60__object___47____62__s.mdwn @@ -0,0 +1,98 @@ +IIUC, the current version of [HTML::Scrubber][] allows for the `object` tags to be either enabled or disabled entirely. However, while `object` can be used to add *code* (which is indeed a potential security hole) to a document, reading [Objects, Images, and Applets in HTML documents][objects-html] reveals that the “dangerous” are not all the `object`s, but rather those having the following attributes: + + classid %URI; #IMPLIED -- identifies an implementation -- + codebase %URI; #IMPLIED -- base URI for classid, data, archive-- + codetype %ContentType; #IMPLIED -- content type for code -- + archive CDATA #IMPLIED -- space-separated list of URIs -- + +It seems that the following attributes are, OTOH, safe: + + declare (declare) #IMPLIED -- declare but don't instantiate flag -- + data %URI; #IMPLIED -- reference to object's data -- + type %ContentType; #IMPLIED -- content type for data -- + standby %Text; #IMPLIED -- message to show while loading -- + height %Length; #IMPLIED -- override height -- + width %Length; #IMPLIED -- override width -- + usemap %URI; #IMPLIED -- use client-side image map -- + name CDATA #IMPLIED -- submit as part of form -- + tabindex NUMBER #IMPLIED -- position in tabbing order -- + +Should the former attributes be *scrubbed* while the latter left intact, the use of the `object` tag would seemingly become safe. + +Note also that allowing `object` (either restricted in such a way or not) automatically solves the [[/todo/svg]] issue. + +For Ikiwiki, it may be nice to be able to restrict [URI's][URI] (as required by the `data` and `usemap` attributes) to, say, relative and `data:` (as per [RFC 2397][]) ones as well, though it requires some more consideration. + +— [[Ivan_Shmakov]], 2010-03-12Z. + +[[wishlist]] + +> SVG can contain embedded javascript. + +>> Indeed. + +>> So, a more general tool (`XML::Scrubber`?) will be necessary to +>> refine both [XHTML][] and SVG. + +>> … And to leave [MathML][] as is (?.) + +>> — [[Ivan_Shmakov]], 2010-03-12Z. + +> The spec that you link to contains +> examples of objects that contain python scripts, Microsoft OLE +> objects, and Java. And then there's flash. I don't think ikiwiki can +> assume all the possibilities are handled securely, particularly WRT XSS +> attacks. +> --[[Joey]] + +>> I've scanned over all the `object` examples in the specification and +>> all of those that hold references to code (as opposed to data) have a +>> distinguishing `classid` attribute. + +>> While I won't assert that it's impossible to reference code with +>> `data` (and, thanks to `text/xhtml+xml` and `image/svg+xml`, it is +>> *not* impossible), throwing away any of the “insecure” +>> attributes listed above together with limiting the possible URI's +>> (i. e., only *local* and certain `data:` ones for `data` and +>> `usemap`) should make `object` almost as harmless as, say, `img`. + +>>> But with local data, one could not embed youtube videos, which surely +>>> is the most obvious use case? + +>>>> Allowing a “remote” object to render on one's page is a + security issue by itself. + Though, of course, having an explicit whitelist of URI's may make + this issue more tolerable. + — [[Ivan_Shmakov]], 2010-03-12Z. + +>>> Note that youtube embedding uses an +>>> object element with no classid. The swf file is provided via an +>>> enclosed param element. --[[Joey]] + +>>>> I've just checked a random video on YouTube and I see that the + `.swf` file is provided via an enclosed `embed` element. Whether + to allow those or not is a different issue. + — [[Ivan_Shmakov]], 2010-03-12Z. + +>> (Though it certainly won't solve the [[SVG_problem|/todo/SVG]] being +>> restricted in such a way.) + +>> Of the remaining issues I could only think of recursive +>> `object` — the one that references its container document. + +>> — [[Ivan_Shmakov]], 2010-03-12Z. + +## See also + +* [Objects, Images, and Applets in HTML documents][objects-html] +* [[plugins/htmlscrubber|/plugins/htmlscrubber]] +* [[todo/svg|/todo/svg]] +* [RFC 2397: The “data” URL scheme. L. Masinter. August 1998.][RFC 2397] +* [Uniform Resource Identifier — the free encyclopedia][URI] + +[HTML::Scrubber]: http://search.cpan.org/~podmaster/HTML-Scrubber-0.08/Scrubber.pm +[MathML]: http://en.wikipedia.org/wiki/MathML +[objects-html]: http://www.w3.org/TR/1999/REC-html401-19991224/struct/objects.html +[RFC 2397]: http://tools.ietf.org/html/rfc2397 +[URI]: http://en.wikipedia.org/wiki/Uniform_Resource_Identifier +[XHTML]: http://en.wikipedia.org/wiki/XHTML diff --git a/doc/todo/git_attribution/discussion.mdwn b/doc/todo/git_attribution/discussion.mdwn index dfb490bc2..6905d9b4b 100644 --- a/doc/todo/git_attribution/discussion.mdwn +++ b/doc/todo/git_attribution/discussion.mdwn @@ -72,7 +72,7 @@ no determination of uniqueness) > GIT_AUTHOR_EMAIL can also be set. > > There is one thing yet to be solved, and that is how to tell the -> difference between a web commit by 'Joey Hess <joey@kitenet.net>', +> difference between a web commit by 'Joey Hess <joey\@kitenet.net>', > and a git commit by the same. I think we do want to differentiate these, > and the best way to do it seems to be to add a line to the end of the > commit message. Something like: "\n\nWeb-commit: true" @@ -94,5 +94,5 @@ no determination of uniqueness) > * github pushes to twitter ;-) > > So while I tried that way at first, I'm now leaning toward encoding the -> username in the email address. Like "user <user@web>", or -> "joey <http://joey.kitenet.net/@web>". +> username in the email address. Like "user <user\@web>", or +> "joey <http://joey.kitenet.net/\@web>". diff --git a/doc/todo/http_bl_support.mdwn b/doc/todo/http_bl_support.mdwn new file mode 100644 index 000000000..f7a46ee6c --- /dev/null +++ b/doc/todo/http_bl_support.mdwn @@ -0,0 +1,67 @@ +[Project Honeypot](http://projecthoneypot.org/) has an HTTP:BL API available to subscribed (it's free, accept donations) people/orgs. There's a basic perl package someone wrote, I'm including a copy here. + +[from here](http://projecthoneypot.org/board/read.php?f=10&i=112&t=112) + +> The [[plugins/blogspam]] service already checks urls against +> the surbl, and has its own IP blacklist. The best way to +> support the HTTP:BL may be to add a plugin +> [there](http://blogspam.repository.steve.org.uk/file/cc858e497cae/server/plugins/). +> --[[Joey]] + +<pre> +package Honeypot; + +use Socket qw/inet_ntoa/; + +my $dns = 'dnsbl.httpbl.org'; +my %types = ( +0 => 'Search Engine', +1 => 'Suspicious', +2 => 'Harvester', +4 => 'Comment Spammer' +); +sub query { +my $key = shift || die 'You need a key for this, you get one at http://www.projecthoneypot.org'; +my $ip = shift || do { +warn 'no IP for request in Honeypot::query().'; +return; +}; + +my @parts = reverse split /\./, $ip; +my $lookup_name = join'.', $key, @parts, $dns; + +my $answer = gethostbyname ($lookup_name); +return unless $answer; +$answer = inet_ntoa($answer); +my(undef, $days, $threat, $type) = split /\./, $answer; +my @types; +while(my($bit, $typename) = each %types) { +push @types, $typename if $bit & $type; +} +return { +days => $days, +threat => $threat, +type => join ',', @types +}; + +} +1; +</pre> + +From the page: + +> The usage is simple: + +> use Honeypot; +> my $key = 'XXXXXXX'; # your key +> my $ip = '....'; the IP you want to check +> my $q = Honeypot::query($key, $ip); + +> use Data::Dumper; +> print Dumper $q; + +Any chance of having this as a plugin? + +I could give it a go, too. Would be fun to try my hand at Perl. --[[simonraven]] + +[[!tag wishlist]] diff --git a/doc/todo/link_plugin_perhaps_too_general__63__.mdwn b/doc/todo/link_plugin_perhaps_too_general__63__.mdwn new file mode 100644 index 000000000..8a5fd50eb --- /dev/null +++ b/doc/todo/link_plugin_perhaps_too_general__63__.mdwn @@ -0,0 +1,25 @@ +[[!tag wishlist blue-sky]] +(This isn't important to me - I don't use MediaWiki or Creole syntax myself - +but just thinking out loud...) + +The [[ikiwiki/wikilink]] syntax IkiWiki uses sometimes conflicts with page +languages' syntax (notably, [[plugins/contrib/MediaWiki]] and [[plugins/Creole]] +want their wikilinks the other way round, like +`\[[plugins/write|how to write a plugin]]`). It would be nice if there was +some way for page language plugins to opt in/out of the normal wiki link +processing - then MediaWiki and Creole could have their own `linkify` hook +that was only active for *their* page types, and used the appropriate +syntax. + +In [[todo/matching_different_kinds_of_links]] I wondered about adding a +`\[[!typedlink to="foo" type="bar"]]` directive. This made me wonder whether +a core `\[[!link]]` directive would be useful; this could be a fallback for +page types where a normal wikilink can't be done for whatever reason, and +could also provide extension points more easily than WikiLinks' special +syntax with extra punctuation, which doesn't really scale? + +Straw-man: + + \[[!link to="ikiwiki/wikilink" desc="WikiLinks"]] + +--[[smcv]] diff --git a/doc/todo/mark_edit_as_trivial__44___identify__47__filter_on_trivial_changes.mdwn b/doc/todo/mark_edit_as_trivial__44___identify__47__filter_on_trivial_changes.mdwn new file mode 100644 index 000000000..2b2b0242e --- /dev/null +++ b/doc/todo/mark_edit_as_trivial__44___identify__47__filter_on_trivial_changes.mdwn @@ -0,0 +1,11 @@ +One feature of mediawiki which I quite like is the ability to mark a change as 'minor', or 'trivial'. This can then be used to filter the 'recentchanges' page, to only show substantial edits. + +The utility of this depends entirely on whether the editors use it properly. + +I currently use an inline on the front page of my personal homepage to show the most recent pages (by creation date) within a subsection of my site (a blog). Blog posts are rarely modified much after they are 'created' (or published - I bodge the creation time via meta when I publish a post. It might sit in draft form indefinitely), so this effectively shows only non-trivial changes. + +I would like to have a short list of the most recent modifications to the site on the front page. I therefore want to sort by modified time rather than creation time, but exclude edits that I self-identify as minor. I also only want to take a short number of items, the top 5, and display only their titles (which may be derived from filename, or set via meta again). + +I'm still thinking through how this might be achieved in an ikiwiki-suitable fashion, but I think I need a scheme to identify certain edits as trivial. This would have to work via web edits (easier: could add a check box to the edit form) and plain changes in the VCS (harder: scan for keywords in a commit message? in a VCS-agnostic fashion?) + +[[!tag wishlist]] diff --git a/doc/todo/matching_different_kinds_of_links.mdwn b/doc/todo/matching_different_kinds_of_links.mdwn index 26c5a072b..da3ea49f6 100644 --- a/doc/todo/matching_different_kinds_of_links.mdwn +++ b/doc/todo/matching_different_kinds_of_links.mdwn @@ -36,6 +36,11 @@ Besides pagespecs, the `rel=` attribute could be used for styles. --Ivan Z. > normal links.) Might be better to go ahead and add the variable to > core though. --[[Joey]] +>> I've implemented this with the data structure you suggested, except that +>> I called it `%typedlinks` instead of `%linktype` (it seemed to make more +>> sense that way). I also ported `tag` to it, and added a `tagged_is_strict` +>> config option. See below! --[[smcv]] + I saw somewhere else here some suggestions for the wiki-syntax for specifying the relation name of a link. One more suggestion---[the syntax used in Semantic MediaWiki](http://en.wikipedia.org/wiki/Semantic_MediaWiki#Basic_usage), like this: <pre> @@ -45,3 +50,147 @@ I saw somewhere else here some suggestions for the wiki-syntax for specifying th So a part of the effect of [[`\[[!taglink TAG\]\]`|plugins/tag]] could be represented as something like `\[[tag::TAG]]` or (more understandable relation name in what concerns the direction) `\[[tagged::TAG]]`. I don't have any opinion on this syntax (whether it's good or not)...--Ivan Z. + +------- + +>> [[!template id=gitbranch author="[[Simon_McVittie|smcv]]" branch=smcv/ready/link-types]] +>> [[!tag patch]] + +## Documentation for smcv's branch + +### added to [[ikiwiki/pagespec]] + +* "`typedlink(type glob)`" - matches pages that link to a given page (or glob) + with a given link type. Plugins can create links with a specific type: + for instance, the tag plugin creates links of type `tag`. + +### added to [[plugins/tag]] + +If the `tagged_is_strict` config option is set, `tagged()` will only match +tags explicitly set with [[ikiwiki/directive/tag]] or +[[ikiwiki/directive/taglink]]; if not (the default), it will also match +any other [[WikiLinks|ikiwiki/WikiLink]] to the tag page. + +### added to [[plugins/write]] + +#### `%typedlinks` + +The `%typedlinks` hash records links of specific types. Do not modify this +hash directly; call `add_link()`. The keys are page names, and the values +are hash references. In each page's hash reference, the keys are link types +defined by plugins, and the values are hash references with link targets +as keys, and 1 as a dummy value, something like this: + + $typedlinks{"foo"} = { + tag => { short_word => 1, metasyntactic_variable => 1 }, + next_page => { bar => 1 }, + }; + +Ordinary [[WikiLinks|ikiwiki/WikiLink]] appear in `%links`, but not in +`%typedlinks`. + +#### `add_link($$;$)` + + This adds a link to `%links`, ensuring that duplicate links are not + added. Pass it the page that contains the link, and the link text. + +An optional third parameter sets the link type (`undef` produces an ordinary +[[ikiwiki/WikiLink]]). + +## Review + +Some code refers to `oldtypedlinks`, and other to `oldlinktypes`. --[[Joey]] + +> Oops, I'll fix that. That must mean missing test coverage, too :-( +> --s + +>> A test suite for the dependency resolver *would* be nice. --[[Joey]] + +>>> Bug fixed, I think. A test suite for the dependency resolver seems +>>> more ambitious than I want to get into right now, but I added a +>>> unit test for this part of it... --s + +I'm curious what your reasoning was for adding a new variable +rather than using `pagestate`. Was it only because you needed +the `old` version to detect change, or was there other complexity? +--J + +> You seemed to be more in favour of adding it to the core in +> your proposal above, so I assumed that'd be more likely to be +> accepted :-) I don't mind one way or the other - `%typedlinks` +> costs one core variable, but saves one level of hash nesting. If +> you're not sure either, then I think the decision should come down +> to which one is easier to document clearly - I'm still unhappy with +> my docs for `%typedlinks`, so I'll try to write docs for it as +> `pagestate` and see if they work any better. --s + +>> On reflection, I don't think it's any better as a pagestate, and +>> the contents of pagestates (so far) aren't documented for other +>> plugins' consumption, so I'm inclined to leave it as-is, unless +>> you want to veto that. Loose rationale: it needs special handling +>> in the core to be a dependency type (I re-used the existing link +>> type), it's API beyond a single plugin, and it's really part of +>> the core parallel to pagestate rather than being tied to a +>> specific plugin. Also, I'd need to special-case it to have +>> ikiwiki not delete it from the index, unless I introduced a +>> dummy typedlinks plugin (or just hook) that did nothing... --s + +I have not convinced myself this is a real problem, but.. +If a page has a typed link, there seems to be no way to tell +if it also has a separate, regular link. `add_link` will add +to `@links` when adding a typed, or untyped link. If only untyped +links were recorded there, one could tell the difference. But then +typed links would not show up at all in eg, a linkmap, +unless it was changed to check for typed links too. +(Or, regular links could be recorded in typedlinks too, +with a empty type. (Bloaty.)) --J + +> I think I like the semantics as-is - I can't think of any +> reason why you'd want to ask the question "does A link to B, +> not counting tags and other typed links?". A typed link is +> still a link, in my mind at least. --s + +>> Me neither, let's not worry about it. --[[Joey]] + +I suspect we could get away without having `tagged_is_strict` +without too much transitional trouble. --[[Joey]] + +> If you think so, I can delete about 5 LoC. I don't particularly +> care either way; [[Jon]] expressed concern about people relying +> on the current semantics, on one of the pages requesting this +> change. --s + +>> Removed in a newer version of the branch. --s + +I might have been wrong to introduce `typedlink(tag foo)`. It's not +very user-friendly, and is more useful as a backend for other plugins +that as a feature in its own right - any plugin introducing a link +type will probably also want to have its own preprocessor directive +to set that link type, and its own pagespec function to match it. +I wonder whether to make a `typedlink` plugin that has the typedlink +pagespec match function and a new `\[[!typedlink to="foo" type="bar"]]` +though... --[[smcv]] + +> I agree, per-type matchers are more friendly and I'm not enamored of the +> multi-parameter pagespec syntax. --[[Joey]] + +>> Removed in a newer version of the branch. I re-introduced it as a +>> plugin in `smcv/typedlink`, but I don't think we really need it. --s + +---- + +I am ready to merge this, but I noticed one problem -- since `match_tagged` +now only matches pages with the tag linktype, a wiki will need to be +rebuilt on upgrade in order to get the linktype of existing tags in it +recorded. So there needs to be a NEWS item about this and +the postinst modified to force the rebuild. + +> Done, although you'll need to plug in an appropriate version number when +> you release it. Is there a distinctive reminder string you grep for +> during releases? I've used `UNRELEASED` for now. --[[smcv]] + +Also, the ready branch adds `typedlink()` to [[ikiwiki/pagespec]], +but you removed that feature as documented above. +--[[Joey]] + +> [[Done]]. --s diff --git a/doc/todo/mercurial.mdwn b/doc/todo/mercurial.mdwn index e71c8106a..de1f148e5 100644 --- a/doc/todo/mercurial.mdwn +++ b/doc/todo/mercurial.mdwn @@ -119,3 +119,11 @@ I have a few notes on mercurial usage after trying it out for a while: >> I think the ideal solution would be to build `$destdir/recentchanges/*` directly from the output of `hg log`. --[[buo]] >>>> That would be 100 times as slow, so I chose not to do that. --[[Joey]] + +>>>> Since this is confusing people, allow me to clarify: Ikiwiki's +>>>> recentchanges generation pulls log information directly out of the VCS as +>>>> needed. It caches it in recentchanges/* in the `scrdir`. These cache +>>>> files need not be preserved, should never be checked into VCS, and if +>>>> you want to you can configure your VCSignore file to ignore them, +>>>> just as you can configure it to ignore the `.ikiwiki` directory in the +>>>> `scrdir`. --[[Joey]] diff --git a/doc/todo/more_flexible_inline_postform.mdwn b/doc/todo/more_flexible_inline_postform.mdwn index bc8bc0809..414476bd7 100644 --- a/doc/todo/more_flexible_inline_postform.mdwn +++ b/doc/todo/more_flexible_inline_postform.mdwn @@ -16,3 +16,8 @@ logical first step towards doing comment-like things with inlined pages). > Perhaps what we need is a `postform` plugin/directive that inline depends > on (automatically enables); its preprocess method could automatically be > invoked from preprocess_inline when needed. --[[smcv]] + +>> I've been looking at this stuff again. I think you are right, this would +>> be the right approach. The comments plugin could use it similarly, allowing +>> sites which desire it to have an inline comment submission form on all +>> pages with comments enabled. I'm going to take a look. -- [[Jon]] diff --git a/doc/todo/openid_user_filtering.mdwn b/doc/todo/openid_user_filtering.mdwn index 8b2d0082e..6a318c4c0 100644 --- a/doc/todo/openid_user_filtering.mdwn +++ b/doc/todo/openid_user_filtering.mdwn @@ -7,3 +7,7 @@ So I suggest an ikiwiki configuration like: users => ["*.webvm.net"], Would only allow edits from openIDs of that form. + +> This kind of thing can be [[done]] now: --[[Joey]] +> +> locked_pages => "* and !user(http://*.webvm.net/)" diff --git a/doc/todo/optional_underlaydir_prefix.mdwn b/doc/todo/optional_underlaydir_prefix.mdwn new file mode 100644 index 000000000..06900a904 --- /dev/null +++ b/doc/todo/optional_underlaydir_prefix.mdwn @@ -0,0 +1,46 @@ +For security reasons, symlinks are disabled in IkiWiki. That's fair enough, but that means that some problems, which one could otherwise solve by using a symlink, cannot be solved. The specfic problem in this case is that all underlays are placed at the root of the wiki, when it could be more convenient to place some underlays in specific sub-directories. + +Use-case 1 (to keep things tidy): + +Currently IkiWiki has some javascript files in `underlays/javascript`; that directory is given as one of the underlay directories. Thus, all the javascript files appear in the root of the generated site. But it would be tidier if one could say "put the contents of *this* underlaydir under the `js` directory". + +> Of course, this could be accomplished, if we wanted to, by moving the +> files to `underlays/javascript/js`. --[[Joey]] + +Use-case 2 (a read-only external dir): + +Suppose I want to include a subset of `/usr/local/share/docs` on my wiki, say the docs about `foo`. But I want them to be under the `docs/foo` sub-directory on the generated site. Currently I can't do that. If I give `/usr/local/share/docs/foo` as an underlaydir, then the contents of that will be in the root of the site, rather than under `docs/foo`. And if I give `/usr/local/share/docs` as an underlaydir, then the contents of the `foo` dir will be under `foo`, but it will also include every other thing in `/usr/local/share/docs`. + +Since we can't use symlinks in an underlay dir to link to these directories, then perhaps one could give a specific underlay dir a specific prefix, which defines the sub-directory that the underlay should appear in. + +I'm not sure how this would be implemented, but I guess it could be configured something like this: + + prefixed_underlay => { + 'js' => '/usr/local/share/ikiwiki/javascript', + 'docs/foo' => '/usr/local/share/docs/foo', + } + +> So, let me review why symlinks are an issue. For normal, non-underlay +> pages, users who do not have filesystem access to the server may have +> commit access, and so could commit eg, a symlink to `/etc/passwd` (or +> to `/` !). The guards are there to prevent ikiwiki either exposing the +> symlink target's contents, or potentially overwriting it. +> +> Is this a concern for underlays? Most of the time, certianly not; +> the underlay tends to be something only the site admin controls. +> Not all the security checks that are done on the srcdir are done +> on the underlays, either. Most checks done on files in the underlay +> are only done because the same code handles srcdir files. The one +> exception is the test that skips processing symlinks in the underlay dir. +> (But note that the underlay directory can be a symlinkt to elsewhere +> which the srcdir, by default, cannot.) +> +> So, one way to approach this is to make ikiwiki follow directory symlinks +> inside the underlay directory. Just a matter of passing `follow => 1` to +> find. (This would still not allow individual files to be symlinks, because +> `readfile` does not allow reading symlinks. But I don't see much need +> for that.) --[[Joey]] + +>> If you think that enabling symlinks in underlay directories wouldn't be a security issue, then I'm all for it! That would be much simpler to implement, I'm sure. --[[KathrynAndersen]] + +[[!taglink wishlist]] diff --git a/doc/todo/rewrite_ikiwiki_in_haskell.mdwn b/doc/todo/rewrite_ikiwiki_in_haskell.mdwn index 204c48cd7..48ed744b1 100644 --- a/doc/todo/rewrite_ikiwiki_in_haskell.mdwn +++ b/doc/todo/rewrite_ikiwiki_in_haskell.mdwn @@ -29,6 +29,7 @@ It's appealing for a lot of reasons, including: edit in html editors currently. - This would be a chance to make WikiLinks with link texts read "the right way round" (ie, vaguely wiki creole compatably). + *[See also [[todo/link_plugin_perhaps_too_general?]] --[[smcv]]]* - The data structures would probably be quite different. - I might want to drop a lot of the command-line flags, either requiring a setup file be used for those things, or leaving the diff --git a/doc/todo/salmon_protocol_for_comment_sharing.mdwn b/doc/todo/salmon_protocol_for_comment_sharing.mdwn new file mode 100644 index 000000000..1e56b0a8b --- /dev/null +++ b/doc/todo/salmon_protocol_for_comment_sharing.mdwn @@ -0,0 +1,21 @@ +The <a href="http://www.salmon-protocol.org/home">Salmon protocol</a> +provides for aggregating comments across sites. If a site that syndicates +a feed receives a comment on an item in that feed, it can re-post the +comment to the original source. + +> Ikiwiki does not allow comments to be posted on items it aggregates. +> So salmon protocol support would only need to handle the comment +> receiving side of the protocol. +> +> The current draft protocol document confuses me when it starts talking +> about using OAuth in the abuse prevention section, since their example +> does not show use of OAuth, and it's not at all clear to me where the +> OAuth relationship between aggregator and original source is supposed +> to come from. +> +> Their security model, which goes on to include Webfinger, +> thirdparty validation services, XRD, and Magic Signatures, looks sorta +> like they kept throwing technology, at it, hoping something will stick. :-P +> --[[Joey]] + +[[!tag wishlist]] diff --git a/doc/todo/smarter_sorting.mdwn b/doc/todo/smarter_sorting.mdwn new file mode 100644 index 000000000..901e143a7 --- /dev/null +++ b/doc/todo/smarter_sorting.mdwn @@ -0,0 +1,141 @@ +I benchmarked a build of a large wiki (my home wiki), and it was spending +quite a lot of time sorting; `CORE::sort` was called only 1138 times, but +still flagged as the #1 time sink. (I'm not sure I trust NYTProf fully +about that FWIW, since it also said 27238263 calls to `cmp_age` were +the #3 timesink, and I suspect it may not entirely accurately measure +the overhead of so many short function calls.) + +`pagespec_match_list` currently always sorts *all* pages first, and then +finds the top M that match the pagespec. That's innefficient when M is +small (as for example in a typical blog, where only 20 posts are shown, +out of maybe thousands). + +As [[smcv]] noted, It could be flipped, so the pagespec is applied first, +and then sort the smaller matching set. But, checking pagespecs is likely +more expensive than sorting. (Also, influence calculation complicates +doing that.) + +Another option, when there is a limit on M pages to return, might be to +cull the M top pages without sorting the rest. + +> The patch below implements this. +> +> But, I have not thought enough about influence calculation. +> I need to figure out which pagespec matches influences need to be +> accumulated for in order to determine all possible influences of a +> pagespec are known. +> +> The old code accumulates influences from matching all successful pages +> up to the num cutoff, as well as influences from an arbitrary (sometimes +> zero) number of failed matches. New code does not accumulate influences +> from all the top successful matches, only an arbitrary group of +> successes and some failures. +> +> Also, by the time I finished this, it was not measuarably faster than +> the old method. At least not with a few thousand pages; it +> might be worth revisiting this sometime for many more pages? [[done]] +> --[[Joey]] + +<pre> +diff --git a/IkiWiki.pm b/IkiWiki.pm +index 1730e47..bc8b23d 100644 +--- a/IkiWiki.pm ++++ b/IkiWiki.pm +@@ -2122,36 +2122,54 @@ sub pagespec_match_list ($$;@) { + my $num=$params{num}; + delete @params{qw{num deptype reverse sort filter list}}; + +- # when only the top matches will be returned, it's efficient to +- # sort before matching to pagespec, +- if (defined $num && defined $sort) { +- @candidates=IkiWiki::SortSpec::sort_pages( +- $sort, @candidates); +- } +- ++ # Find the first num matches (or all), before sorting. + my @matches; +- my $firstfail; + my $count=0; + my $accum=IkiWiki::SuccessReason->new(); +- foreach my $p (@candidates) { +- my $r=$sub->($p, %params, location => $page); ++ my $i; ++ for ($i=0; $i < @candidates; $i++) { ++ my $r=$sub->($candidates[$i], %params, location => $page); + error(sprintf(gettext("cannot match pages: %s"), $r)) + if $r->isa("IkiWiki::ErrorReason"); + $accum |= $r; + if ($r) { +- push @matches, $p; ++ push @matches, $candidates[$i]; + last if defined $num && ++$count == $num; + } + } + ++ # We have num natches, but they may not be the best. ++ # Efficiently find and add the rest, without sorting the full list of ++ # candidates. ++ if (defined $num && defined $sort) { ++ @matches=IkiWiki::SortSpec::sort_pages($sort, @matches); ++ ++ for ($i++; $i < @candidates; $i++) { ++ # Comparing candidate with lowest match is cheaper, ++ # so it's done before testing against pagespec. ++ if (IkiWiki::SortSpec::cmptwo($candidates[$i], $matches[-1], $sort) < 0 && ++ $sub->($candidates[$i], %params, location => $page) ++ ) { ++ # this could be done less expensively ++ # using a binary search ++ for (my $j=0; $j < @matches; $j++) { ++ if (IkiWiki::SortSpec::cmptwo($candidates[$i], $matches[$j], $sort) < 0) { ++ splice @matches, $j, $#matches-$j+1, $candidates[$i], ++ @matches[$j..$#matches-1]; ++ last; ++ } ++ } ++ } ++ } ++ } ++ + # Add simple dependencies for accumulated influences. +- my $i=$accum->influences; +- foreach my $k (keys %$i) { +- $depends_simple{$page}{lc $k} |= $i->{$k}; ++ my $inf=$accum->influences; ++ foreach my $k (keys %$inf) { ++ $depends_simple{$page}{lc $k} |= $inf->{$k}; + } + +- # when all matches will be returned, it's efficient to +- # sort after matching ++ # Sort if we didn't already. + if (! defined $num && defined $sort) { + return IkiWiki::SortSpec::sort_pages( + $sort, @matches); +@@ -2455,6 +2473,12 @@ sub sort_pages { + sort $f @_ + } + ++sub cmptwo { ++ $a=$_[0]; ++ $b=$_[1]; ++ $_[2]->(); ++} ++ + sub cmp_title { + IkiWiki::pagetitle(IkiWiki::basename($a)) + cmp +</pre> + +This would be bad when M is very large, and particularly, of course, when +there is no limit and all pages are being matched on. (For example, an +archive page shows all pages that match a pagespec specifying a creation +date range.) Well, in this case, it *does* make sense to flip it, limit by +pagespe first, and do a (quick)sort second. (No influence complications, +either.) + +> Flipping when there's no limit implemented, and it knocked 1/3 off +> the rebuild time of my blog's archive pages. --[[Joey]] + +Adding these special cases will be more complicated, but I think the best +of both worlds. --[[Joey]] diff --git a/doc/todo/structured_page_data.mdwn b/doc/todo/structured_page_data.mdwn index da9da9663..9f21fab7f 100644 --- a/doc/todo/structured_page_data.mdwn +++ b/doc/todo/structured_page_data.mdwn @@ -253,6 +253,9 @@ in a large number of other cases. > dependencies between bugs from arbitrary links. >> This issue (the need for distinguished kinds of links) has also been brought up in other discussions: [[tracking_bugs_with_dependencies#another_kind_of_links]] (deps vs. links) and [[tag_pagespec_function]] (tags vs. links). --Ivan Z. +>>> And multiple link types are now supported; plugins can set the link +>>> type when registering a link, and pagespec functions can match on them. --[[Joey]] + ---- #!/usr/bin/perl diff --git a/doc/todo/svg.mdwn b/doc/todo/svg.mdwn index 89b183db6..274ebf3e3 100644 --- a/doc/todo/svg.mdwn +++ b/doc/todo/svg.mdwn @@ -57,3 +57,21 @@ in the trunk if other people think it's useful. [htmlscrubber.pm]:http://xbeta.org/gitweb/?p=xbeta/ikiwiki.git;a=blob;f=IkiWiki/Plugin/htmlscrubber.pm;h=3c0ddc8f25bd8cb863634a9d54b40e299e60f7df;hb=fe333c8e5b4a5f374a059596ee698dacd755182d [diff]: http://xbeta.org/gitweb/?p=xbeta/ikiwiki.git;a=blobdiff;f=IkiWiki/Plugin/htmlscrubber.pm;h=3c0ddc8f25bd8cb863634a9d54b40e299e60f7df;hp=3bdaccea119ec0e1b289a0da2f6d90e2219b8d66;hb=fe333c8e5b4a5f374a059596ee698dacd755182d;hpb=be0b4f603f918444b906e42825908ddac78b7073 + +> Unfortuantly these links are broken. --[[Joey]] + +* * * + +Actually, there's a way to embed SVG into MarkDown sources using the [data: URI scheme][rfc2397], [like this](data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBzdGFuZGFsb25lPSJubyI/Pgo8c3ZnIHdpZHRoPSIxOTIiIGhlaWdodD0iMTkyIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KIDwhLS0gQ3JlYXRlZCB3aXRoIFNWRy1lZGl0IC0gaHR0cDovL3N2Zy1lZGl0Lmdvb2dsZWNvZGUuY29tLyAtLT4KIDx0aXRsZT5IZWxsbywgd29ybGQhPC90aXRsZT4KIDxnPgogIDx0aXRsZT5MYXllciAxPC90aXRsZT4KICA8ZyB0cmFuc2Zvcm09InJvdGF0ZSgtNDUsIDk3LjY3MTksIDk3LjY2OCkiIGlkPSJzdmdfNyI+CiAgIDxyZWN0IHN0cm9rZS13aWR0aD0iNSIgc3Ryb2tlPSIjMDAwMDAwIiBmaWxsPSIjRkYwMDAwIiBpZD0ic3ZnXzUiIGhlaWdodD0iNTYuMDAwMDAzIiB3aWR0aD0iMTc1IiB5PSI2OS42Njc5NjkiIHg9IjEwLjE3MTg3NSIvPgogICA8dGV4dCB4bWw6c3BhY2U9InByZXNlcnZlIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiBmb250LWZhbWlseT0ic2VyaWYiIGZvbnQtc2l6ZT0iMjQiIHN0cm9rZS13aWR0aD0iMCIgc3Ryb2tlPSIjMDAwMDAwIiBmaWxsPSIjZmZmZjAwIiBpZD0ic3ZnXzYiIHk9IjEwNS42NjgiIHg9Ijk5LjY3MTkiPkhlbGxvLCB3b3JsZCE8L3RleHQ+CiAgPC9nPgogPC9nPgo8L3N2Zz4=). +Of course, this way to display an image one needs to click a link, but it may be considered a feature. +— [[Ivan_Shmakov]], 2010-03-12Z. + +[rfc2397]: http://tools.ietf.org/html/rfc2397 + +> You can do the same with img src actually. +> +> If svg markup allows unsafe elements (ie, javascript), +> which it appears to, +> then this is a security hole, and the htmlscrubber +> needs to lock it down more. Darn, now I have to spend my afternoon making +> security releases! --[[Joey]] diff --git a/doc/todo/tracking_bugs_with_dependencies.mdwn b/doc/todo/tracking_bugs_with_dependencies.mdwn index 5f3ece290..456dadad0 100644 --- a/doc/todo/tracking_bugs_with_dependencies.mdwn +++ b/doc/todo/tracking_bugs_with_dependencies.mdwn @@ -81,6 +81,9 @@ I like the idea of [[tips/integrated_issue_tracking_with_ikiwiki]], and I do so >> I saw that this issue is targeted at by the work on [[structured page data#another_kind_of_links]]. --Ivan Z. +>>> It's fixed now; links can have a type, such as "tag", or "dependency", +>>> and pagespecs can match links of a given typo. --[[Joey]] + Okie - I've had a quick attempt at this. Initial patch attached. This one doesn't quite work. And there is still a lot of debugging stuff in there. diff --git a/doc/todo/user-defined_templates_outside_the_wiki.mdwn b/doc/todo/user-defined_templates_outside_the_wiki.mdwn new file mode 100644 index 000000000..1d72aa6a7 --- /dev/null +++ b/doc/todo/user-defined_templates_outside_the_wiki.mdwn @@ -0,0 +1,10 @@ +[[!tag wishlist]] + +The [[plugins/contrib/ftemplate]] plugin looks for templates inside the wiki +source, but also looks in the system templates directory (the one with +`page.tmpl`). This means the wiki admin can provide templates that can be +invoked via `\[[!template]]`, but don't have to "work" as wiki pages in their +own right. I think the normal [[plugins/template]] plugin could benefit from +this functionality. + +[[done]] --[[Joey]] diff --git a/doc/usage.mdwn b/doc/usage.mdwn index e4808d4c2..2e12517ea 100644 --- a/doc/usage.mdwn +++ b/doc/usage.mdwn @@ -50,6 +50,14 @@ These options control the mode that ikiwiki operates in. If used with --setup --refresh, this makes it also update any configured wrappers. +* --clean + + This makes ikiwiki clean up by removing any files it denerated in the + `destination` directory, as well as any configured wrappers, and the + `.ikiwiki` state directory. This is mostly useful if you're running + ikiwiki in a Makefile to build documentation and want a corresponding + `clean` target. + * --cgi Enable [[CGI]] mode. In cgi mode ikiwiki runs as a cgi script, and @@ -226,6 +234,12 @@ also be configured using a setup file. Specifies a rexexp of source files to exclude from processing. May be specified multiple times to add to exclude list. +* --include regexp + + Specifies a rexexp of source files, that would normally be excluded, + but that you wish to include in processing. + May be specified multiple times to add to include list. + * --adminuser name Specifies a username of a user (or, if openid is enabled, an openid) @@ -306,20 +320,22 @@ also be configured using a setup file. intercepted. If you enable this option then you must run at least the CGI portion of ikiwiki over SSL. -* --getctime +* --gettime, --no-gettime - Pull creation 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 building a wiki from a new - VCS checkout. It is unoptimised and quite slow. It is best used - with --rebuild, to force ikiwiki to get the ctime for all pages. + Extract creation and modification times for each new page from the + the revision control's log. This is done automatically when building a + wiki for the first time, so you normally do not need to use this option. * --set var=value This allows setting an arbitrary configuration variable, the same as if it - were set via a setup file. Since most options can be configured - using command-line switches, you will rarely need to use this, but it can be - useful for the odd option that lacks a command-line switch. + were set via a setup file. Since most options commonly used options can be + configured using command-line switches, you will rarely need to use this. + +* --set-yaml var=value + + This is like --set, but it allows setting configuration variables that + use complex data structures, by passing in a YAML document. # EXAMPLES diff --git a/doc/users/David_Riebenbauer.mdwn b/doc/users/David_Riebenbauer.mdwn index 372a28588..d7469696e 100644 --- a/doc/users/David_Riebenbauer.mdwn +++ b/doc/users/David_Riebenbauer.mdwn @@ -1,2 +1,8 @@ Runs ikiwiki on his [homepage](http://liegesta.at/) and can be reached through <davrieb@liegesta.at> + +## Branches in his [[git]] repository ## + +* `autotag` +([browse](http://git.liegesta.at/?p=ikiwiki.git;a=shortlog;h=refs/heads/autotag)) +See [[todo/auto-create_tag_pages_according_to_a_template]] diff --git a/doc/users/Edward_Betts.mdwn b/doc/users/Edward_Betts.mdwn index b32927a1c..61d6150ef 100644 --- a/doc/users/Edward_Betts.mdwn +++ b/doc/users/Edward_Betts.mdwn @@ -1,9 +1,4 @@ My watchlist: -[[!inline archive="yes" sort="mtime" atom="yes" pages=" -todo/allow_wiki_syntax_in_commit_messages* -todo/shortcut_with_different_link_text* -todo/structured_page_data* -tips/convert_mediawiki_to_ikiwiki* -"]] +[[!inline archive="yes" sort="mtime" atom="yes" pages="todo/allow_wiki_syntax_in_commit_messages* or todo/shortcut_with_different_link_text* or todo/structured_page_data* or tips/convert_mediawiki_to_ikiwiki*"]] diff --git a/doc/users/KathrynAndersen.mdwn b/doc/users/KathrynAndersen.mdwn index 16cb390c4..8e827b0da 100644 --- a/doc/users/KathrynAndersen.mdwn +++ b/doc/users/KathrynAndersen.mdwn @@ -1,8 +1,8 @@ * aka [[rubykat]] -* Currently an active [PmWiki](http://www.pmwiki.org) user, but investigating changing over to ikiwiki (if I can write the plugins I need). * <http://kerravonsen.dreamwidth.org> -* <http://www.katspace.org> +* <http://www.katspace.org> (uses IkiWiki!) * <http://github.com/rubykat> +* Also an active [PmWiki](http://www.pmwiki.org) user, interested in having the best of both worlds. Has written the following plugins: [[!map pages="!*/Discussion and ((link(users/KathrynAndersen) or link(users/rubykat)) and plugins/*) "]] diff --git a/doc/users/KathrynAndersen/discussion.mdwn b/doc/users/KathrynAndersen/discussion.mdwn new file mode 100644 index 000000000..4f2790c39 --- /dev/null +++ b/doc/users/KathrynAndersen/discussion.mdwn @@ -0,0 +1,20 @@ +Had a look at your site. Sprawling, individualistic, using ikiwiki in lots of +ways. Makes me happy. :) I see that I have let a lot of contrib plugins +pile up. I will try to get to these. I'm particularly interested in +your use of yaml+fields. Encourage you to go ahead with any others you +have not submitted here, like pmap. (Unless it makes more sense to submit +that as a patch to the existing map plugin.) --[[Joey]] + +> Thanks. I would have put more up, but I didn't want to until they were properly documented, and other things have taken a higher priority. + +> I think pmap is probably better as a separate plugin, because it has additional dependencies (HTML::LinkList) which people might not want to have to install. + +>> One approach commonly used in ikiwiki is to make such optional features +>> be enabled by a switch somewhere, and 'eval q{use Foo}` so the module +>> does not have to be loaded unless the feature is used. --[[Joey]] + +>>> Unfortunately, HTML::LinkList isn't an optional feature for pmap; that's what it uses to create the HTML for the map. --[[KathrynAndersen]] + +> The "includepage" plugin I'm not sure whether it is worth releasing or not; it's basically a cut-down version of "inline", because the inline plugin is so complicated and has so many options, I felt more at ease to have something simpler. + +> --[[KathrynAndersen]] diff --git a/doc/users/NicolasLimare.mdwn b/doc/users/NicolasLimare.mdwn index 003449d40..56a950f7e 100644 --- a/doc/users/NicolasLimare.mdwn +++ b/doc/users/NicolasLimare.mdwn @@ -1,9 +1 @@ -Nicolas (nil) uses ikiwiki on a site/wiki/blog/something... and feels this approach much more comfortable than the usual web-only ones. - -He didn't touch any perl code before using ikiwiki, ant that was the first opportunity to propose tiny patches. - -Actualy, he would have felt much more comfortable with a python ikiwiki... :) - -Can be reached at nicolas at limare.net - -By the way, I can make translations to french if needed. And maybe to japanese.
\ No newline at end of file +[[!meta redir="nil"]] diff --git a/doc/users/Will.mdwn b/doc/users/Will.mdwn index f5effdbe3..1956263e0 100644 --- a/doc/users/Will.mdwn +++ b/doc/users/Will.mdwn @@ -13,14 +13,16 @@ Unless otherwise specified, any code that I post to this wiki I release under th ------ +Disabling these as I'm not using them much any more... + ### Open Bugs: -[[!inline pages="link(users/Will) and bugs/* and !bugs/done and !bugs/discussion and !link(patch) and !link(bugs/done) and !bugs/*/*" archive="yes" feeds="no" ]] +\[[!inline pages="link(users/Will) and bugs/* and !bugs/done and !bugs/discussion and !link(patch) and !link(bugs/done) and !bugs/*/*" archive="yes" feeds="no" ]] ### Open ToDos: -[[!inline pages="link(users/Will) and todo/* and !todo/done and !todo/discussion and !link(patch) and !link(todo/done) and !bugs/*/*" archive="yes" feeds="no" ]] +\[[!inline pages="link(users/Will) and todo/* and !todo/done and !todo/discussion and !link(patch) and !link(todo/done) and !bugs/*/*" archive="yes" feeds="no" ]] ### Unapplied Patches: -[[!inline pages="link(users/Will) and (todo/* or bugs/*) and !bugs/done and !bugs/discussion and !todo/done and !todo/discussion and link(patch) and !link(bugs/done) and !link(todo/done) and !bugs/*/*" archive="yes" feeds="no" ]] +\[[!inline pages="link(users/Will) and (todo/* or bugs/*) and !bugs/done and !bugs/discussion and !todo/done and !todo/discussion and link(patch) and !link(bugs/done) and !link(todo/done) and !bugs/*/*" archive="yes" feeds="no" ]] diff --git a/doc/users/ivan_shmakov.mdwn b/doc/users/ivan_shmakov.mdwn new file mode 100644 index 000000000..4123e0fc6 --- /dev/null +++ b/doc/users/ivan_shmakov.mdwn @@ -0,0 +1,50 @@ +… To put it short: an Ikiwiki newbie. + +[Emacs]: http://www.gnu.org/software/emacs/ +[Lynx]: http://lynx.isc.org/ + +## Wikis + +Currently, I run a couple of Ikiwiki instances. Namely: + +* <http://lhc.am-1.org/lhc/> + — to hold random stuff written by me, my colleagues, + students, etc. + +* <http://rsdesne.am-1.org/rsdesne-2010/> + — for some of the materials related to the + “Remote Sensing in Education, Science and National + Economy” (2010-03-29 … 2010-04-10, Altai State + University) program I've recently participated in as + an instructor. + +## Preferences + +I prefer to use [Lynx][] along with [Emacs][] (via +`emacsclient`) to work with the wikis. (Note the “Local +variables” section below.) + +The things I dislike in the wiki engines are: + +* the use of home-brew specialized version control systems + — while there're a lot of much more developed general + purpose ones; + +* oversimplified syntax + — which (to some extent) precludes more sophisticated + forms of automated processing; in particular, this forces one + to reformat the material, once complete, to, say, prepare a + book, or an article, or slides. + +Out of all the wiki engines I'm familiar with, only Ikiwiki is +free of the first of these. I hope that it will support more +elaborate syntaxes eventually. + +---- + + Local variables: + mode: markdown + coding: utf-8 + fill-column: 64 + ispell-dictionary: "american" + End: diff --git a/doc/users/jeanprivat.mdwn b/doc/users/jeanprivat.mdwn new file mode 100644 index 000000000..4d75a9867 --- /dev/null +++ b/doc/users/jeanprivat.mdwn @@ -0,0 +1 @@ +Jean Privat is <jean@pryen.org>. diff --git a/doc/users/jogo.mdwn b/doc/users/jogo.mdwn index 6f87cbc45..e8068a10f 100644 --- a/doc/users/jogo.mdwn +++ b/doc/users/jogo.mdwn @@ -1,5 +1,5 @@ * An [economic game](http://sef.matabio.net/) in french, which [use](http://sef.matabio.net/wiki/) IkiWiki. - * Some [plugins](http://kimya.matabio.net/tcgi/hg/IkiPlugins/file/). - * An alternative [base wiki](http://kimya.matabio.net/tcgi/hg/FrIkiWiki/file/) in french. + * Some [plugins](http://www.matabio.net/tcgi/hg/IkiPlugins/file/). + * An alternative [base wiki](http://www.matabio.net/tcgi/hg/FrIkiWiki/file/) in french. email: `jogo matabio net`. diff --git a/doc/users/jon.mdwn b/doc/users/jon.mdwn index f08076c2a..d5593dcbf 100644 --- a/doc/users/jon.mdwn +++ b/doc/users/jon.mdwn @@ -45,9 +45,14 @@ The following I have been looking at, but are on the back-burner: bugs such as [[bugs/tagged() matching wikilinks]]. Code for this lives in my github `tag2` branch: <http://github.com/jmtd/ikiwiki> -Finally, the following are merely half-formed thoughts: +Penultimately, the following are merely half-formed thoughts: * adding and removing tags to pages via the edit form by ticking and unticking checkboxes next to a tag name (rather than entering the directive into the text of the page directly) * perhaps the same for meta + +Finally, backlinks (since I have issues with the current backlinks +implementation, see [[bugs/backlinks onhover thing can go weird]]): + +[[!inline pages="link(users/Jon)" archive="yes" feeds="no"]] diff --git a/doc/users/nil.mdwn b/doc/users/nil.mdwn new file mode 100644 index 000000000..e1826cec6 --- /dev/null +++ b/doc/users/nil.mdwn @@ -0,0 +1,8 @@ +nil first used ikiwiki on a site/wiki/blog/something... and felt this approach much more comfortable than the usual web-only ones. +Since then, ikiwiki is a kind of swiss army knife when it comes to build anything for the web. + +Can be reached at nicolas at limare.net + +The current big ikiwiki-powered project is <http://www.ipol.im> + +TODO: document "how to split public/edition interfaces" diff --git a/doc/users/schmonz.mdwn b/doc/users/schmonz.mdwn index 7ebd8311c..03c52b6aa 100644 --- a/doc/users/schmonz.mdwn +++ b/doc/users/schmonz.mdwn @@ -1,3 +1,3 @@ -[Amitai Schlair](http://www.columbia.edu/~ays2105/) recently discovered ikiwiki and finds himself using it for all sorts of things. His attempts at contributing: +[Amitai Schlair](http://www.netbsd.org/~schmonz/) recently discovered ikiwiki and finds himself using it for all sorts of things. His attempts at contributing: [[!map pages="!*/Discussion and ((link(users/schmonz) and plugins/*) or rcs/cvs)"]] diff --git a/doc/users/tschwinge.mdwn b/doc/users/tschwinge.mdwn index 20d8d16a8..414612aff 100644 --- a/doc/users/tschwinge.mdwn +++ b/doc/users/tschwinge.mdwn @@ -99,12 +99,6 @@ page that uses \[[!meta redir]]. ## [[bugs/Broken Parentlinks]] -## Discussion Pages of Discussion Pages of... - -Is it useful to have Discussion pages of Discussion pages (etc.)? -- On -<http://www.gnu.org/software/hurd/hurd/building/cross-compiling/discussion.html>, -this possibility is offered. - ## Modifying [[plugins/inline]] for showing only an *appetizer* Currently ikiwiki's inline plugin will either show the full page or nothing of diff --git a/doc/wikitemplates.mdwn b/doc/wikitemplates.mdwn index 6c0480cea..6e5a7261d 100644 --- a/doc/wikitemplates.mdwn +++ b/doc/wikitemplates.mdwn @@ -5,7 +5,8 @@ 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. +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 @@ -43,7 +44,8 @@ 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 stored in the wiki and inserted into pages. +[[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 |