diff options
Diffstat (limited to 'doc')
27 files changed, 698 insertions, 135 deletions
diff --git a/doc/bugs/Comments_dissapeared.mdwn b/doc/bugs/Comments_dissapeared.mdwn index ac297028c..7ff1a012f 100644 --- a/doc/bugs/Comments_dissapeared.mdwn +++ b/doc/bugs/Comments_dissapeared.mdwn @@ -28,3 +28,8 @@ It worked just fine with this configuration. I swear I have not modified it. :) > 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/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/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/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/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 045bfd7aa..06c82337a 100644 --- a/doc/forum/an_alternative_approach_to_structured_data.mdwn +++ b/doc/forum/an_alternative_approach_to_structured_data.mdwn @@ -18,6 +18,10 @@ 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]] + ## Second Pass I have written additional plugins which integrate with the [[plugins/contrib/field]] plugin to both set and get structured page data. 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/ikiwikiusers.mdwn b/doc/ikiwikiusers.mdwn index 633400f21..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,7 +139,6 @@ 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. 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 index 7e94a4029..646a5f3f4 100644 --- a/doc/plugins/contrib/field/discussion.mdwn +++ b/doc/plugins/contrib/field/discussion.mdwn @@ -68,15 +68,13 @@ I think it should just be part of `field` rather than a separate plugin. }, } - package IkiWiki::PageSpec; + package IkiWiki::SortSpec; - sub check_cmp_field { + sub cmp_field { if (!length $_[0]) { error("sort=field requires a parameter"); } - } - sub cmp_field { my $left = IkiWiki::Plugin::field::field_get_value($_[2], $_[0]); my $right = IkiWiki::Plugin::field::field_get_value($_[2], $_[1]); @@ -86,3 +84,28 @@ I think it should just be part of `field` rather than a separate plugin. } 1; + +------- + +Bug report: `field` has an unnecessary `use YAML::Any`, presumably from before +you separated out `ymlfront`. Trivial patch available from +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>) +--[[smcv]] + +> Can do for the field plugin (delete one line? Easy.) Will push when I get to a better connection. --[[KathrynAndersen]] + +---- + +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]] diff --git a/doc/plugins/contrib/ftemplate/discussion.mdwn b/doc/plugins/contrib/ftemplate/discussion.mdwn index eb84dd09b..1e0bca5d8 100644 --- a/doc/plugins/contrib/ftemplate/discussion.mdwn +++ b/doc/plugins/contrib/ftemplate/discussion.mdwn @@ -29,6 +29,5 @@ seems orthogonal (and might be a good enhancement to `template` anyway). > Yes, I added that because I wanted the option of not having to make all my templates work as wiki pages also. --[[KathrynAndersen]] ->> Yeah, that's something that annoys me about `template` too. I've ->> opened a todo: [[todo/user-defined_templates_outside_the_wiki]]. ->> --s +>> 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 index 76e858680..9187b1350 100644 --- a/doc/plugins/contrib/pod/discussion.mdwn +++ b/doc/plugins/contrib/pod/discussion.mdwn @@ -8,3 +8,7 @@ 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/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/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/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/todo/allow_plugins_to_add_sorting_methods.mdwn b/doc/todo/allow_plugins_to_add_sorting_methods.mdwn index f37a0758e..d4da13feb 100644 --- a/doc/todo/allow_plugins_to_add_sorting_methods.mdwn +++ b/doc/todo/allow_plugins_to_add_sorting_methods.mdwn @@ -1,4 +1,3 @@ -[[!template id=gitbranch branch=smcv/sort-hooks author="[[Simon_McVittie|smcv]]"]] [[!tag patch]] The available [[ikiwiki/pagespec/sorting]] methods are currently hard-coded in @@ -11,83 +10,253 @@ 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). -Gitweb: -<http://git.pseudorandom.co.uk/smcv/ikiwiki.git?a=shortlog;h=refs/heads/sort-hooks> +*[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: -<http://git.pseudorandom.co.uk/smcv/ikiwiki.git?a=shortlog;h=refs/heads/sort-hooks-excessive> - -(The older version is untested, and probably doesn't really work as-is - I -misunderstood the details of how the built-in function `sort` works when using -`$a` and `$b`. The newer version has been tested, and has a regression test for -its core functionality.) - -This hook *isn't* (yet) sufficient to implement [[plugins/contrib/report]]'s -NIH'd sorting mechanisms: - -* `report` can sort by any [[plugins/contrib/field]], whereas this one has a - finite number of hooks: if the `field` plugin's functionality is desirable, - perhaps parameterized sort mechanisms similar to pagespec match functions - would be useful? Then the `field` plugin could register - `hook(type => "sort", id => "field")` and you could have - `\[[!inline ... sort="field(Mood)"]]` or something? - -* `report` can sort by multiple criteria, with independent direction-changing: - if this is desirable, perhaps `pagespec_match_list` could be enhanced to - interpret `sort="x -y z(w)"` as sorting by (pseudocode) - `{ $cmp_x->($a, $b) || (-$cmp_y->($a, $b)) || $cmp_z->($a, $b, "w") }`? - -> I've now added both of these features to the sort-hooks branch. --[[smcv]] +*[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/sort-package author="[[Simon_McVittie|smcv]]"]] +>>> [[!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> -## Documentation from sort-hooks branch - -### sort hook (added to [[plugins/write]]) - - hook(type => "sort", id => "foo", call => \&sort_by_foo); - -This hook adds an additional [[ikiwiki/pagespec/sorting]] order or overrides -an existing one. - -The callback is given two page names followed by the parameter as arguments, and -returns negative, zero or positive if the first page should come before, -close to (i.e. undefined order), or after the second page. - -For instance, the built-in `title` sort order could be reimplemented as - - sub sort_by_title { - pagetitle(basename($_[0])) cmp pagetitle(basename($_[1])); - } - -and to sort by an arbitrary `meta` value, you could use: - - # usage: sort="meta(description)" - sub sort_by_meta { - my $param = $_[2]; - error "sort=meta requires a parameter" unless defined $param; - my $left = $pagestate{$_[0]}{meta}{$param}; - $left = "" unless defined $left; - my $right = $pagestate{$_[1]}{meta}{$param}; - $right = "" unless defined $right; - return $left cmp $right; - } - - -### meta_title sort order (conditionally added to [[ikiwiki/pagespec/sorting]]) - -* `meta_title` - Order according to the `\[[!meta title="foo" sort="bar"]]` +>>>> 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. + full title was set. `meta(author)`, `meta(date)`, `meta(updated)`, etc. + also work. ### Multiple sort orders (added to [[ikiwiki/pagespec/sorting]]) @@ -95,39 +264,38 @@ 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 title sort parameter (added to [[ikiwiki/directive/meta]]) +### 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`: +[[ikiwiki/pagespec/sorting]] by `meta(title)`: \[[!meta title="The Beatles" sort="Beatles, The"]] \[[!meta title="David Bowie" sort="Bowie, David"]] -## Documentation from sort-hooks branch +[in author] -The changes to [[ikiwiki/pagespec/sorting]] are the same. -The changes to [[plugins/write]] are replaced by: + An optional `sortas` parameter will be used preferentially when + [[ikiwiki/pagespec/sorting]] by `meta(author)`: -### Sorting plugins + \[[!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::PageSpec package named `cmp_foo`, which will be used when sorting +the IkiWiki::SortSpec package named `cmp_foo`, which will be used when sorting by `foo` or `foo(...)` is requested. -The function will be passed three or more parameters. The first two are -page names, and the third is `undef` if invoked as `foo`, or the parameter -`"bar"` if invoked as `foo(bar)`. It may also be passed additional, named -parameters. - -It should return the same thing as Perl's `cmp` and `<=>` operators: negative -if the first argument is less than the second, positive if the first argument -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. - -You can also define a function called `check_cmp_foo` in the same package. -If you do, it will be called while preparing to sort by `foo` or `foo(bar)`, -with argument `undef` or `"bar"` respectively; it may raise an error using -`error`, if sorting like that isn't going to work. +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/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 0049281fe..8e81860a1 100644 --- a/doc/todo/matching_different_kinds_of_links.mdwn +++ b/doc/todo/matching_different_kinds_of_links.mdwn @@ -53,7 +53,7 @@ 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/link-types]] +>> [[!template id=gitbranch author="[[Simon_McVittie|smcv]]" branch=smcv/ready/link-types]] >> [[!tag patch]] ## Documentation for smcv's branch @@ -96,3 +96,101 @@ Ordinary [[WikiLinks|ikiwiki/WikiLink]] appear in `%links`, but not in 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/optional_underlaydir_prefix.mdwn b/doc/todo/optional_underlaydir_prefix.mdwn new file mode 100644 index 000000000..dd11d062d --- /dev/null +++ b/doc/todo/optional_underlaydir_prefix.mdwn @@ -0,0 +1,44 @@ +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]] + +[[!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 index 880ad6493..1d72aa6a7 100644 --- a/doc/todo/user-defined_templates_outside_the_wiki.mdwn +++ b/doc/todo/user-defined_templates_outside_the_wiki.mdwn @@ -6,3 +6,5 @@ source, but also looks in the system templates directory (the one with 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/users/KathrynAndersen/discussion.mdwn b/doc/users/KathrynAndersen/discussion.mdwn index 288ea8c51..35340b22f 100644 --- a/doc/users/KathrynAndersen/discussion.mdwn +++ b/doc/users/KathrynAndersen/discussion.mdwn @@ -9,6 +9,10 @@ that as a patch to the existing map plugin.) --[[Joey]] > 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]] + > 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/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 |