diff options
Diffstat (limited to 'doc')
54 files changed, 1506 insertions, 60 deletions
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/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/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/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 de178d415..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 @@ -16,3 +16,5 @@ The [[ikiwiki/directive/map]] directive sort by pagename. That looks kind of odd >> 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/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..8e1ca42e0 --- /dev/null +++ b/doc/bugs/some_but_not_all_meta_fields_are_stored_escaped.mdwn @@ -0,0 +1,39 @@ +[[!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... + +* 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. 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/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/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/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/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/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/git.mdwn b/doc/git.mdwn index 289937121..379285a49 100644 --- a/doc/git.mdwn +++ b/doc/git.mdwn @@ -59,6 +59,7 @@ into [[Joey]]'s working tree. This is recommended. :-) * [[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` ## branches 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/ikiwikiusers.mdwn b/doc/ikiwikiusers.mdwn index b40fd461d..4a3e41e83 100644 --- a/doc/ikiwikiusers.mdwn +++ b/doc/ikiwikiusers.mdwn @@ -53,6 +53,7 @@ Projects & Organizations * [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 ======================== @@ -138,10 +139,10 @@ Personal sites and blogs * [Cosmic Cookout](http://www.cosmiccookout.com/) * [Backyard Deer](http://www.backyarddeer.com/) * [Alex Ghitza homepage and blog](http://aghitza.org/) -* [Mukund's homepage](http://www.mukund.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.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.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/contrib/field/discussion.mdwn b/doc/plugins/contrib/field/discussion.mdwn new file mode 100644 index 000000000..2ea195e5b --- /dev/null +++ b/doc/plugins/contrib/field/discussion.mdwn @@ -0,0 +1,226 @@ +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]] 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/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/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/moderatedcomments.mdwn b/doc/plugins/moderatedcomments.mdwn index c29b0b052..f9466e833 100644 --- a/doc/plugins/moderatedcomments.mdwn +++ b/doc/plugins/moderatedcomments.mdwn @@ -8,5 +8,5 @@ By default, all comments made by anyone who is not an admin will be held 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(*)". +`moderate_pagespec` to "`!user(*)`". Or to moderate everyone except for +admins, set it to "`!admin(*)`". 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/write.mdwn b/doc/plugins/write.mdwn index f42cc86ae..05ddf2215 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -633,6 +633,22 @@ 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 }, + }; + +Ordinary [[WikiLinks|ikiwiki/WikiLink]] appear in `%links`, but not in +`%typedlinks`. + ### `%pagesources` The `%pagesources` has can be used to look up the source filename @@ -939,11 +955,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 diff --git a/doc/rcs.mdwn b/doc/rcs.mdwn index f66b85495..4e7a8d2a6 100644 --- a/doc/rcs.mdwn +++ b/doc/rcs.mdwn @@ -7,10 +7,27 @@ 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]]. 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 +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/sandbox.mdwn b/doc/sandbox.mdwn index 8cba8973f..c323153c8 100644 --- a/doc/sandbox.mdwn +++ b/doc/sandbox.mdwn @@ -1,6 +1,6 @@ This is the [[SandBox]], a page anyone can edit to try out ikiwiki (version [[!version ]]). - +[[Testing 1 2 3| test]] # Header ## Subheader2 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/spam_and_softwaresites.mdwn b/doc/tips/spam_and_softwaresites.mdwn index fe73518ef..507858c0c 100644 --- a/doc/tips/spam_and_softwaresites.mdwn +++ b/doc/tips/spam_and_softwaresites.mdwn @@ -82,5 +82,6 @@ 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 tackle spam with reverts until you have at least one -commit you want merged back into the main history. +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/todo/allow_plugins_to_add_sorting_methods.mdwn b/doc/todo/allow_plugins_to_add_sorting_methods.mdwn new file mode 100644 index 000000000..d4da13feb --- /dev/null +++ b/doc/todo/allow_plugins_to_add_sorting_methods.mdwn @@ -0,0 +1,301 @@ +[[!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). + +*[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..7129a44ac 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,27 @@ 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 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]] + +>>>> Thanks for the review - these are all valid points. I'll get working +>>>> on a revised 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 a0e76fd48..07b570b1b 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 @@ -164,8 +164,12 @@ wrong direction. > 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]] -> -> * In the refactoring in f3abeac919c4736429bd3362af6edf51ede8e7fe, + +>> 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)` @@ -177,18 +181,39 @@ wrong direction. > 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. +> * 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.) -> -> * Commit f58f3e1bec41ccf9316f37b014ce0b373c8e49e1 adds a line + +>> 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. -> -> * Commit f58f3e1bec41ccf9316f37b014ce0b373c8e49e1 says that auto-added + +>> 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]] + +[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/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/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/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/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/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 f735170f0..db1e36a10 100644 --- a/doc/usage.mdwn +++ b/doc/usage.mdwn @@ -331,9 +331,13 @@ also be configured using a setup file. * --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/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/ivan_shmakov.mdwn b/doc/users/ivan_shmakov.mdwn index 41bf9b09a..de58cb207 100644 --- a/doc/users/ivan_shmakov.mdwn +++ b/doc/users/ivan_shmakov.mdwn @@ -1,3 +1,4 @@ … To put it short: an Ikiwiki newbie. -I run an Ikiwiki instance at <http://gray.am-1.org/~ivan/lhc/> (though the DNS servers seem to be temporarily out of smoke as of 2010-03-12Z.) +I run an Ikiwiki instance at <http://gray.siamics.net/~ivan/lhc/> +(though the DNS servers may be flacky due to transition to Dyn Inc.) 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/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 |