use vars qw{%config %links %oldlinks %pagemtime %pagectime %pagecase
%pagestate %wikistate %renderedfiles %oldrenderedfiles
%pagesources %destsources %depends %depends_simple %hooks
- %forcerebuild %loaded_plugins};
+ %forcerebuild %loaded_plugins %typedlinks %oldtypedlinks};
use Exporter q{import};
our @EXPORT = qw(hook debug error template htmlpage deptype
add_underlay pagetitle titlepage linkpage newpagefile
inject add_link
%config %links %pagestate %wikistate %renderedfiles
- %pagesources %destsources);
+ %pagesources %destsources %typedlinks);
our $VERSION = 3.00; # plugin interface version, next is ikiwiki version
our $version='unknown'; # VERSION_AUTOREPLACE done by Makefile, DNE
our $installdir='/usr'; # INSTALLDIR_AUTOREPLACE done by Makefile, DNE
# Optimisation.
use Memoize;
memoize("abs2rel");
+memoize("sortspec_translate");
memoize("pagespec_translate");
memoize("template_file");
if (! $config{rebuild}) {
%pagesources=%pagemtime=%oldlinks=%links=%depends=
%destsources=%renderedfiles=%pagecase=%pagestate=
- %depends_simple=();
+ %depends_simple=%typedlinks=%oldtypedlinks=();
}
my $in;
if (! open ($in, "<", "$config{wikistatedir}/indexdb")) {
if (exists $d->{state}) {
$pagestate{$page}=$d->{state};
}
+ if (exists $d->{typedlinks}) {
+ $typedlinks{$page}=$d->{typedlinks};
+
+ while (my ($type, $links) = each %{$typedlinks{$page}}) {
+ next unless %$links;
+ $oldtypedlinks{$page}{$type} = {%$links};
+ }
+ }
}
$oldrenderedfiles{$page}=[@{$d->{dest}}];
}
$index{page}{$src}{depends_simple} = $depends_simple{$page};
}
+ if (exists $typedlinks{$page} && %{$typedlinks{$page}}) {
+ $index{page}{$src}{typedlinks} = $typedlinks{$page};
+ }
+
if (exists $pagestate{$page}) {
foreach my $id (@hookids) {
foreach my $key (keys %{$pagestate{$page}{$id}}) {
use warnings;
}
-sub add_link ($$) {
+sub add_link ($$;$) {
my $page=shift;
my $link=shift;
+ my $type=shift;
push @{$links{$page}}, $link
unless grep { $_ eq $link } @{$links{$page}};
+
+ if (defined $type) {
+ $typedlinks{$page}{$type}{$link} = 1;
+ }
+}
+
+sub sortspec_translate ($) {
+ my $spec = shift;
+
+ my $code = "";
+ my @data;
+ while ($spec =~ m{
+ \s*
+ (-?) # group 1: perhaps negated
+ \s*
+ ( # group 2: a word
+ \w+\([^\)]*\) # command(params)
+ |
+ [^\s]+ # or anything else
+ )
+ \s*
+ }gx) {
+ my $negated = $1;
+ my $word = $2;
+ my $params = undef;
+
+ if ($word =~ m/^(\w+)\((.*)\)$/) {
+ # command with parameters
+ $params = $2;
+ $word = $1;
+ }
+ elsif ($word !~ m/^\w+$/) {
+ error(sprintf(gettext("invalid sort type %s"), $word));
+ }
+
+ if (length $code) {
+ $code .= " || ";
+ }
+
+ if ($negated) {
+ $code .= "-";
+ }
+
+ if (exists $IkiWiki::SortSpec::{"cmp_$word"}) {
+ if (defined $params) {
+ push @data, $params;
+ $code .= "IkiWiki::SortSpec::cmp_$word(\$data[$#data])";
+ }
+ else {
+ $code .= "IkiWiki::SortSpec::cmp_$word(undef)";
+ }
+ }
+ else {
+ error(sprintf(gettext("unknown sort type %s"), $word));
+ }
+ }
+
+ if (! length $code) {
+ # undefined sorting method... sort arbitrarily
+ return sub { 0 };
+ }
+
+ no warnings;
+ return eval 'sub { '.$code.' }';
}
sub pagespec_translate ($) {
}
if (defined $params{sort}) {
- my $f;
- if ($params{sort} eq 'title') {
- $f=sub { pagetitle(basename($a)) cmp pagetitle(basename($b)) };
- }
- elsif ($params{sort} eq 'title_natural') {
- eval q{use Sort::Naturally};
- if ($@) {
- error(gettext("Sort::Naturally needed for title_natural sort"));
- }
- $f=sub { Sort::Naturally::ncmp(pagetitle(basename($a)), pagetitle(basename($b))) };
- }
- elsif ($params{sort} eq 'mtime') {
- $f=sub { $pagemtime{$b} <=> $pagemtime{$a} };
- }
- elsif ($params{sort} eq 'age') {
- $f=sub { $pagectime{$b} <=> $pagectime{$a} };
- }
- else {
- error sprintf(gettext("unknown sort type %s"), $params{sort});
- }
- @candidates = sort { &$f } @candidates;
+ @candidates = IkiWiki::SortSpec::sort_pages($params{sort},
+ @candidates);
}
@candidates=reverse(@candidates) if $params{reverse};
$link=derel($link, $params{location});
my $from=exists $params{location} ? $params{location} : '';
+ my $linktype=$params{linktype};
+ my $qualifier='';
+ if (defined $linktype) {
+ $qualifier=" with type $linktype";
+ }
my $links = $IkiWiki::links{$page};
return IkiWiki::FailReason->new("$page has no links", $page => $IkiWiki::DEPEND_LINKS, "" => 1)
my $bestlink = IkiWiki::bestlink($from, $link);
foreach my $p (@{$links}) {
if (length $bestlink) {
- return IkiWiki::SuccessReason->new("$page links to $link", $page => $IkiWiki::DEPEND_LINKS, "" => 1)
- if $bestlink eq IkiWiki::bestlink($page, $p);
+ if ((!defined $linktype || exists $IkiWiki::typedlinks{$page}{$linktype}{$p}) && $bestlink eq IkiWiki::bestlink($page, $p)) {
+ return IkiWiki::SuccessReason->new("$page links to $link$qualifier", $page => $IkiWiki::DEPEND_LINKS, "" => 1)
+ }
}
else {
- return IkiWiki::SuccessReason->new("$page links to page $p matching $link", $page => $IkiWiki::DEPEND_LINKS, "" => 1)
- if match_glob($p, $link, %params);
+ if ((!defined $linktype || exists $IkiWiki::typedlinks{$page}{$linktype}{$p}) && match_glob($p, $link, %params)) {
+ return IkiWiki::SuccessReason->new("$page links to page $p$qualifier, matching $link", $page => $IkiWiki::DEPEND_LINKS, "" => 1)
+ }
my ($p_rel)=$p=~/^\/?(.*)/;
$link=~s/^\///;
- return IkiWiki::SuccessReason->new("$page links to page $p_rel matching $link", $page => $IkiWiki::DEPEND_LINKS, "" => 1)
- if match_glob($p_rel, $link, %params);
+ if ((!defined $linktype || exists $IkiWiki::typedlinks{$page}{$linktype}{$p_rel}) && match_glob($p_rel, $link, %params)) {
+ return IkiWiki::SuccessReason->new("$page links to page $p_rel$qualifier, matching $link", $page => $IkiWiki::DEPEND_LINKS, "" => 1)
+ }
}
}
- return IkiWiki::FailReason->new("$page does not link to $link", $page => $IkiWiki::DEPEND_LINKS, "" => 1);
+ return IkiWiki::FailReason->new("$page does not link to $link$qualifier", $page => $IkiWiki::DEPEND_LINKS, "" => 1);
}
sub match_backlink ($$;@) {
}
}
+package IkiWiki::SortSpec;
+
+# This is in the SortSpec namespace so that the $a and $b that sort() uses
+# are easily available in this namespace, for cmp functions to use them.
+sub sort_pages {
+ my $f = IkiWiki::sortspec_translate(shift);
+
+ return sort $f @_;
+}
+
+sub cmp_title {
+ IkiWiki::pagetitle(IkiWiki::basename($a))
+ cmp
+ IkiWiki::pagetitle(IkiWiki::basename($b))
+}
+
+sub cmp_mtime { $IkiWiki::pagemtime{$b} <=> $IkiWiki::pagemtime{$a} }
+sub cmp_age { $IkiWiki::pagectime{$b} <=> $IkiWiki::pagectime{$a} }
+
1
# Metadata collection that needs to happen during the scan pass.
if ($key eq 'title') {
$pagestate{$page}{meta}{title}=$value;
+ if (exists $params{sortas}) {
+ $pagestate{$page}{meta}{titlesort}=$params{sortas};
+ }
+ else {
+ delete $pagestate{$page}{meta}{titlesort};
+ }
return "";
}
elsif ($key eq 'description') {
}
elsif ($key eq 'author') {
$pagestate{$page}{meta}{author}=$value;
+ if (exists $params{sortas}) {
+ $pagestate{$page}{meta}{authorsort}=$params{sortas};
+ }
+ else {
+ delete $pagestate{$page}{meta}{authorsort};
+ }
# fallthorough
}
elsif ($key eq 'authorurl') {
}
}
+sub get_sort_key {
+ my $page = shift;
+ my $meta = shift;
+
+ # e.g. titlesort (also makes sense for author)
+ my $key = $pagestate{$page}{meta}{$meta . "sort"};
+ return $key if defined $key;
+
+ # e.g. title
+ $key = $pagestate{$page}{meta}{$meta};
+ return $key if defined $key;
+
+ # fall back to closer-to-core things
+ if ($meta eq 'title') {
+ return pagetitle(IkiWiki::basename($page));
+ }
+ elsif ($meta eq 'date') {
+ return $IkiWiki::pagectime{$page};
+ }
+ elsif ($meta eq 'updated') {
+ return $IkiWiki::pagemtime{$page};
+ }
+ else {
+ return '';
+ }
+}
+
sub match {
my $field=shift;
my $page=shift;
IkiWiki::Plugin::meta::match("copyright", @_);
}
+package IkiWiki::SortSpec;
+
+sub cmp_meta {
+ my $meta = shift;
+ error(gettext("sort=meta requires a parameter")) unless defined $meta;
+
+ if ($meta eq 'updated' || $meta eq 'date') {
+ return IkiWiki::Plugin::meta::get_sort_key($a, $meta)
+ <=>
+ IkiWiki::Plugin::meta::get_sort_key($b, $meta);
+ }
+
+ return IkiWiki::Plugin::meta::get_sort_key($a, $meta)
+ cmp
+ IkiWiki::Plugin::meta::get_sort_key($b, $meta);
+}
+
+# A prototype of how sort=title could behave in 4.0 or something
+sub cmp_meta_title {
+ $_[0] = 'title';
+ return cmp_meta(@_);
+}
+
1
if ($config{po_master_language}{code} ne 'en') {
# Add underlay containing translated source files
# for the master language.
- add_underlay("locale/$config{po_master_language}{code}/$underlay");
+print STDERR "added underlay locale/$config{po_master_language}{code}/$underlay\n";
+ add_underlay("locale/$config{po_master_language}{code}/$underlay")
+ if -d "$config{underlaydirbase}/locale/$config{po_master_language}{code}/$underlay";
}
}
}
--- /dev/null
+#!/usr/bin/perl
+# Sort::Naturally-powered title_natural sort order for IkiWiki
+package IkiWiki::Plugin::sortnaturally;
+
+use IkiWiki 3.00;
+no warnings;
+
+sub import {
+ hook(type => "getsetup", id => "sortnaturally", call => \&getsetup);
+}
+
+sub getsetup {
+ return
+ plugin => {
+ safe => 1,
+ rebuild => undef,
+ },
+}
+
+sub checkconfig () {
+ eval q{use Sort::Naturally};
+ error $@ if $@;
+}
+
+package IkiWiki::SortSpec;
+
+sub cmp_title_natural {
+ Sort::Naturally::ncmp(IkiWiki::pagetitle(IkiWiki::basename($a)),
+ IkiWiki::pagetitle(IkiWiki::basename($b)))
+}
+
+1;
use strict;
use IkiWiki 3.00;
-my %tags;
-
sub import {
hook(type => "getopt", id => "tag", call => \&getopt);
hook(type => "getsetup", id => "tag", call => \&getsetup);
foreach my $tag (keys %params) {
$tag=linkpage($tag);
- $tags{$page}{$tag}=1;
# hidden WikiLink
- add_link($page, tagpage($tag));
+ add_link($page, tagpage($tag), 'tag');
}
return "";
return join(" ", map {
if (/(.*)\|(.*)/) {
my $tag=linkpage($2);
- $tags{$params{page}}{$tag}=1;
- add_link($params{page}, tagpage($tag));
+ add_link($params{page}, tagpage($tag), 'tag');
return taglink($params{page}, $params{destpage}, $tag,
linktext => pagetitle($1));
}
else {
my $tag=linkpage($_);
- $tags{$params{page}}{$tag}=1;
- add_link($params{page}, tagpage($tag));
+ add_link($params{page}, tagpage($tag), 'tag');
return taglink($params{page}, $params{destpage}, $tag);
}
}
my $destpage=$params{destpage};
my $template=$params{template};
+ my $tags = $typedlinks{$page}{tag};
+
$template->param(tags => [
map {
link => taglink($page, $destpage, $_, rel => "tag")
- }, sort keys %{$tags{$page}}
- ]) if exists $tags{$page} && %{$tags{$page}} && $template->query(name => "tags");
+ }, sort keys %$tags
+ ]) if defined $tags && %$tags && $template->query(name => "tags");
if ($template->query(name => "categories")) {
# It's an rss/atom template. Add any categories.
- if (exists $tags{$page} && %{$tags{$page}}) {
+ if (defined $tags && %$tags) {
$template->param(categories => [map { category => $_ },
- sort keys %{$tags{$page}}]);
+ sort keys %$tags]);
}
}
}
package IkiWiki::PageSpec;
sub match_tagged ($$;@) {
- my $page = shift;
- my $glob = shift;
- return match_link($page, IkiWiki::Plugin::tag::tagpage($glob));
+ return match_link($_[0], IkiWiki::Plugin::tag::tagpage($_[1]), linktype => 'tag');
}
1
else {
$links{$page}=[];
}
+ delete $typedlinks{$page};
run_hooks(scan => sub {
shift->(
push @del, $pagesources{$page};
}
$links{$page}=[];
+ delete $typedlinks{$page};
$renderedfiles{$page}=[];
$pagemtime{$page}=0;
}
}
}
+sub link_types_changed ($$) {
+ # each is of the form { type => { link => 1 } }
+ my $new = shift;
+ my $old = shift;
+
+ return 0 if !defined $new && !defined $old;
+ return 1 if !defined $new || !defined $old;
+
+ while (my ($type, $links) = each %$new) {
+ foreach my $link (keys %$links) {
+ return 1 unless exists $old->{$type}{$link};
+ }
+ }
+
+ while (my ($type, $links) = each %$old) {
+ foreach my $link (keys %$links) {
+ return 1 unless exists $new->{$type}{$link};
+ }
+ }
+
+ return 0;
+}
+
sub calculate_changed_links ($$$) {
my ($changed, $del, $oldlink_targets)=@_;
}
$linkchangers{lc($page)}=1;
}
+
+ # we currently assume that changing the type of a link doesn't
+ # change backlinks
+ if (!exists $linkchangers{lc($page)}) {
+ if (link_types_changed($typedlinks{$page}, $oldtypedlinks{$page})) {
+ $linkchangers{lc($page)}=1;
+ }
+ }
}
return \%backlinkchanged, \%linkchangers;
+ikiwiki (3.20100406) unstable; urgency=low
+
+ The title_natural sort method (as used by the inline directive, etc)
+ have been moved to the new sortnaturally plugin, which is not enabled
+ by default since it requires the Sort::Naturally perl module.
+
+ Starting from this version, the `tagged()` pagespec only matches tags,
+ not regular wikilinks. If your wiki accidentially relied on the old,
+ buggy behavior, you might need to change pagespecs to use `link()`.
+
+ To support the above change, all wikis need to be rebuilt on upgrade to
+ this version. If you listed your wiki in /etc/ikiwiki/wikilist this will
+ be done automatically when the Debian package is upgraded. Or use
+ ikiwiki-mass-rebuild to force a rebuild.
+
+ -- Simon McVittie <smcv@debian.org> Tue, 06 Apr 2010 20:53:07 +0100
+
ikiwiki (3.20091017) unstable; urgency=low
To take advantage of significant performance improvements, all
-ikiwiki (3.20100404) UNRELEASED; urgency=low
+ikiwiki (3.20100406) UNRELEASED; urgency=low
+ [ Joey Hess ]
* bzr: Fix bzr log parsing to work with bzr 2.0. (liw)
* comments: Fix missing entity encoding in title.
* txt: Add a special case for robots.txt.
+ [ Simon McVittie ]
+ * Add support for link types, and make the the tagged() pagespec only
+ match tags, not regular links (a bugfix).
+ * Rebuild wikis on upgrade to this version to get tag link types recorded
+ correctly.
+ * Revamp sorting system; allow new sort methods to be added by plugins,
+ and add a "sortspec" syntax that can combine, reverse, etc sort methods.
+ * meta: Add `meta(author)`, `meta(title)` etc sortspecs to allow sorting
+ by metadata.
+ * meta: Add optional sortas parameter to author and title meta directives.
+ This can be used to get names sorted by last name without displaying
+ them last name first.
+ * sortnaturally: New plugin; the title_natural sort method has moved here.
+
+ [ Joey Hess ]
+ * Update dependency for git-core to git transition.
+ * po: Check that translated underlay directories exist before using them
+ for master language.
+
-- Joey Hess <joeyh@debian.org> Sun, 04 Apr 2010 12:17:11 -0400
ikiwiki (3.20100403) unstable; urgency=low
libhtml-parser-perl, liburi-perl
Recommends: gcc | c-compiler,
libc6-dev | libc-dev,
- subversion | git-core (>= 1:1.5.0) | tla | bzr (>= 0.91) | mercurial | monotone (>= 0.38) | darcs,
+ subversion | git-core (>= 1:1.5.0) | git (>= 1:1.7) | tla | bzr (>= 0.91) | mercurial | monotone (>= 0.38) | darcs,
libxml-simple-perl, libnet-openid-consumer-perl,
liblwpx-paranoidagent-perl, libtimedate-perl,
libcgi-formbuilder-perl (>= 3.05), libcgi-session-perl (>= 4.14-1),
# Change this when some incompatible change is made that requires
# rebuilding all wikis.
-firstcompat=3.20091010
+firstcompat=3.20100406
if [ "$1" = configure ] && \
dpkg --compare-versions "$2" lt "$firstcompat"; then
Is it a bug? I haven't been noticing such problems usually on other sites. --Ivan Z.
This remains to be true now, with Epiphany 2.26.3 (Mozilla/5.0 (X11; U; Linux i686; en; rv:1.9.1.4pre) Gecko/20080528 Epiphany/2.22 Firefox/3.5). --Ivan Z.
+
+> In the most recent ikiwiki release, I added a Cache-Control hack
+> explicitly to work around firefox's broken over-caching.
+>
+> (When I tested epiphany and chromium, neither had firefox's problem.)
+>
+> [[!tag done]]
--- /dev/null
+[[!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.
>> 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.
> 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.
You are of course free to set up your own ikiwiki git repository with your
own [[patches|patch]]. If you list it here, the `gitremotes` script will
automatically add it to git remotes. Your repo will automatically be pulled
-into [[Joey]]'s working tree. This is recommended. :-)
+into [[Joey]]'s working repository where he can see your branches and
+think about merging them. This is recommended. :-)
<!-- Machine-parsed format: * wikilink <git:url> -->
* [[davrieb|David_Riebenbauer]] `git://git.liegesta.at/git/ikiwiki`
([browse](http://git.liegesta.at/?p=ikiwiki.git;a=summary))
* [[GustafThorslund]] `http://gustaf.thorslund.org/src/ikiwiki.git`
+* [[peteg]] `git://git.hcoop.net/git/peteg/ikiwiki.git`
## branches
be set to a true value in the template; this can be used to format things
differently in this case.
+ An optional `sortas` parameter will be used preferentially when
+ [[ikiwiki/pagespec/sorting]] by `meta(title)`:
+
+ \[[!meta title="The Beatles" sortas="Beatles, The"]]
+
+ \[[!meta title="David Bowie" sortas="Bowie, David"]]
+
* license
Specifies a license for the page, for example, "GPL". Can contain
Specifies the author of a page.
+ An optional `sortas` parameter will be used preferentially when
+ [[ikiwiki/pagespec/sorting]] by `meta(author)`:
+
+ \[[!meta author="Joey Hess" sortas="Hess, Joey"]]
+
* authorurl
Specifies an url for the author of a page.
* `age` - List pages from the most recently created to the oldest.
* `mtime` - List pages with the most recently modified first.
-* `title` - Order by title.
-* `title_natural` - Only available if [[!cpan Sort::Naturally]] is
- installed. Orders by title, but numbers in the title are treated
+* `title` - Order by title (page name).
+[[!if test="enabled(sortnaturally)" then="""
+* `title_natural` - Orders by title, but numbers in the title are treated
as such, ("1 2 9 10 20" instead of "1 10 2 20 9")
+"""]]
+[[!if test="enabled(meta)" then="""
+* `meta(title)` - Order according to the `\[[!meta title="foo" sortas="bar"]]`
+ or `\[[!meta title="foo"]]` [[ikiwiki/directive]], or the page name if no
+ full title was set. `meta(author)`, `meta(date)`, `meta(updated)`, etc.
+ also work.
+"""]]
+
+In addition, you can combine several sort orders and/or reverse the order of
+sorting, with a string like `age -title` (which would sort by age, then by
+title in reverse order if two pages have the same age).
[[!meta robots="noindex, follow"]]
>> (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`
error("sort=field requires a parameter");
}
- my $left = IkiWiki::Plugin::field::field_get_value($_[2], $_[0]);
- my $right = IkiWiki::Plugin::field::field_get_value($_[2], $_[1]);
+ 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;
1;
--------
+----
+
+Disclaimer: I've only looked at this plugin and ymlfront, not other related
+stuff yet. (I quite like ymlfront, so I looked at this as its dependency. :)
+I also don't want to annoy you with a lot of design discussion
+if your main goal was to write a plugin that did exactly what you wanted.
+
+My first question is: Why we need another plugin storing metadata
+about the page, when we already have the meta plugin? Much of the
+complication around the field plugin has to do with it accessing info
+belonging to the meta plugin, and generalizing that to be able to access
+info stored by other plugins too. (But I don't see any other plugins that
+currently store such info). Then too, it raises points of confusion like
+smcv's discuission of field author vs meta author above. --[[Joey]]
+
+> The point is exactly in the generalization, to provide a uniform interface for accessing structured data, no matter what the source of it, whether that be the meta plugin or some other plugin.
+
+> There were a few reasons for this:
+
+>1. In converting my site over from PmWiki, I needed something that was equivalent to PmWiki's Page-Text-Variables (which is how PmWiki implements structured data).
+>2. I also wanted an equivalent of PmWiki's Page-Variables, which, rather than being simple variables, are the return-value of a function. This gives one a lot of power, because one can do calculations, derive one thing from another. Heck, just being able to have a "basename" variable is useful.
+>3. I noticed that in the discussion about structured data, it was mired down in disagreements about what form the structured data should take; I wanted to overcome that hurdle by decoupling the form from the content.
+>4. I actually use this to solve (1), because, while I do use ymlfront, initially my pages were in PmWiki format (I wrote (another) unreleased plugin which parses PmWiki format) including PmWiki's Page-Text-Variables for structured data. So I needed something that could deal with multiple formats.
+
+> So, yes, it does cater to mostly my personal needs, but I think it is more generally useful, also.
+> --[[KathrynAndersen]]
+
+>> Is it fair to say, then, that `field`'s purpose is to take other
+>> plugins' arbitrary per-page data, and present it as a single
+>> merged/flattened string => string map per page? From the plugins
+>> here, things you then use that merged map for include:
+>>
+>> * sorting - stolen by [[todo/allow_plugins_to_add_sorting_methods]]
+>> * substitution into pages with Perl-like syntax - `getfield`
+>> * substitution into wiki-defined templates - the `pagetemplate`
+>> hook
+>> * substitution into user-defined templates - `ftemplate`
+>>
+>> As I mentioned above, the flattening can cause collisions (and in the
+>> `pagetemplate` case, even security problems).
+>>
+>> I wonder whether conflating Page Text Variables with Page Variables
+>> causes `field` to be more general than it needs to be?
+>> To define a Page Variable (function-like field), you need to write
+>> a plugin containing that Perl function; if we assume that `field`
+>> or something resembling it gets merged into ikiwiki, then it's
+>> reasonable to expect third-party plugins to integrate with whatever
+>> scaffolding there is for these (either in an enabled-by-default
+>> plugin that most people are expected to leave enabled, like `meta`
+>> now, or in the core), and it doesn't seem onerous to expect each
+>> plugin that wants to participate in this mechanism to have code to
+>> do so. While it's still contrib, `field` could just have a special case
+>> for the meta plugin, rather than the converse?
+>>
+>> If Page Text Variables are limited to being simple strings as you
+>> suggest over in [[forum/an_alternative_approach_to_structured_data]],
+>> then they're functionally similar to `meta` fields, so one way to
+>> get their functionality would be to extend `meta` so that
+>>
+>> \[[!meta badger="mushroom"]]
+>>
+>> (for an unrecognised keyword `badger`) would store
+>> `$pagestate{$page}{meta}{badger} = "mushroom"`? Getting this to
+>> appear in templates might be problematic, because a naive
+>> `pagetemplate` hook would have the same problem that `field` combined
+>> with `ymlfront` currently does.
+>>
+>> One disadvantage that would appear if the function-like and
+>> meta-like fields weren't in the same namespace would be that it
+>> wouldn't be possible to switch a field from being meta-like to being
+>> function-like without changing any wiki content that referenced it.
+>>
+>> Perhaps meta-like fields should just *be* `meta` (with the above
+>> enhancement), as a trivial case of function-like fields? That would
+>> turn `ymlfront` into an alternative syntax for `meta`, I think?
+>> That, in turn, would hopefully solve the special-fields problem,
+>> by just delegating it to meta. I've been glad of the ability to define
+>> new ad-hoc fields with this plugin without having to write an extra plugin
+>> to do so (listing books with a `bookauthor` and sorting them by
+>> `"field(bookauthor) title"`), but that'd be just as easy if `meta`
+>> accepted ad-hoc fields?
+>>
+>> --[[smcv]]
+
+>>> Your point above about cross-site scripting is a valid one, and something I
+>>> hadn't thought of (oops).
+
+>>> I still want to be able to populate pagetemplate templates with field, because I
+>>> use it for a number of things, such as setting which CSS files to use for a
+>>> given page, and, as I said, for titles. But apart from the titles, I
+>>> realize I've been setting them in places other than the page data itself.
+>>> (Another unreleased plugin, `concon`, uses Config::Context to be able to
+>>> set variables on a per-site, per-directory and a per-page basis).
+
+>>> The first possible solution is what you suggested above: for field to only
+>>> set values in pagetemplate which are prefixed with *field_*. I don't think
+>>> this is quite satisfactory, since that would still mean that people could
+>>> put un-scrubbed values into a pagetemplate, albeit they would be values
+>>> named field_foo, etc. --[[KathrynAndersen]]
+
+>>>> They can already do similar; `PERMALINK` is pre-sanitized to
+>>>> ensure that it's a "safe" URL, but if an extremely confused wiki admin was
+>>>> to put `COPYRIGHT` in their RSS/Atom feed's `<link>`, a malicious user
+>>>> could put an unsafe (e.g. Javascript) URL in there (`COPYRIGHT` *is*
+>>>> HTML-scrubbed, but "javascript:alert('pwned!')" is just text as far as a
+>>>> HTML sanitizer is concerned, so it passes straight through). The solution
+>>>> is to not use variables in situations where that variable would be
+>>>> inappropriate. Because `field` is so generic, the definition of what's
+>>>> appropriate is difficult. --[[smcv]]
+
+>>> An alternative solution would be to classify field registration as "secure"
+>>> and "insecure". Sources such as ymlfront would be insecure, sources such
+>>> as concon (or the $config hash) would be secure, since they can't be edited
+>>> as pages. Then, when doing pagetemplate substitution (but not ftemplate
+>>> substitution) the insecure sources could be HTML-escaped.
+>>> --[[KathrynAndersen]]
+
+>>>> Whether you trust the supplier of data seems orthogonal to whether its value
+>>>> is (meant to be) interpreted as plain text, HTML, a URL or what?
+>>>>
+>>>> Even in cases where you trust the supplier, you need to escape things
+>>>> suitably for the context, not for security but for correctness. The
+>>>> definition of the value, and the context it's being used in, changes the
+>>>> processing you need to do. An incomplete list:
+>>>>
+>>>> * HTML used as HTML needs to be html-scrubbed if and only if untrusted
+>>>> * URLs used as URLs need to be put through `safeurl()` if and only if
+>>>> untrusted
+>>>> * HTML used as plain text needs tags removed regardless
+>>>> * URLs used as plain text are safe
+>>>> * URLs or plain text used in HTML need HTML-escaping (and URLs also need
+>>>> `safeurl()` if untrusted)
+>>>> * HTML or plain text used in URLs need URL-escaping (and the resulting
+>>>> URL might need sanitizing too?)
+>>>>
+>>>> I can't immediately think of other data types we'd be interested in beyond
+>>>> text, HTML and URL, but I'm sure there are plenty.
+
+>>>>> But isn't this a problem with anything that uses pagetemplates? Or is
+>>>>> the point that, with plugins other than `field`, they all know,
+>>>>> beforehand, the names of all the fields that they are dealing with, and
+>>>>> thus the writer of the plugin knows which treatment each particular field
+>>>>> needs? For example, that `meta` knows that `title` needs to be
+>>>>> HTML-escaped, and that `baseurl` doesn't. In that case, yes, I see the problem.
+>>>>> It's a tricky one. It isn't as if there's only ever going to be a fixed set of fields that need different treatment, either. Because the site admin is free to add whatever fields they like to the page template (if they aren't using the default one, that is. I'm not using the default one myself).
+>>>>> Mind you, for trusted sources, since the person writing the page template and the person providing the variable are the same, they themselves would know whether the value will be treated as HTML, plain text, or a URL, and thus could do the needed escaping themselves when writing down the value.
+
+>>>>> Looking at the content of the default `page.tmpl` let's see what variables fall into which categories:
+
+>>>>> * **Used as URL:** BASEURL, EDITURL, PARENTLINKS->URL, RECENTCHANGESURL, HISTORYURL, GETSOURCEURL, PREFSURL, OTHERLANGUAGES->URL, ADDCOMMENTURL, BACKLINKS->URL, MORE_BACKLINKS->URL
+>>>>> * **Used as part of a URL:** FAVICON, LOCAL_CSS
+>>>>> * **Needs to be HTML-escaped:** TITLE
+>>>>> * **Used as-is (as HTML):** FEEDLINKS, RELVCS, META, PERCENTTRANSLATED, SEARCHFORM, COMMENTSLINK, DISCUSSIONLINK, OTHERLANGUAGES->PERCENT, SIDEBAR, CONTENT, COMMENTS, TAGS->LINK, COPYRIGHT, LICENSE, MTIME, EXTRAFOOTER
+
+>>>>> This looks as if only TITLE needs HTML-escaping all the time, and that the URLS all end with "URL" in their name. Unfortunately the FAVICON and LOCAL_CSS which are part of URLS don't have "URL" in their name, though that's fair enough, since they aren't full URLs.
+
+>>>>> --K.A.
+
+>>>> One reasonable option would be to declare that `field` takes text-valued
+>>>> fields, in which case either consumers need to escape
+>>>> it with `<TMPL_VAR FIELD_FOO ESCAPE=HTML>`, and not interpret it as a URL
+>>>> without first checking `safeurl`), or the pagetemplate hook needs to
+>>>> pre-escape.
+
+>>>>> Since HTML::Template does have the ability to do ESCAPE=HTML/URL/JS, why not take advantage of that? Some things, like TITLE, probably should have ESCAPE=HTML all the time; that would solve the "to escape or not to escape" problem that `meta` has with titles. After all, when one *sorts* by title, one doesn't really want HTML-escaping in it; only when one uses it in a template. -- K.A.
+
+>>>> Another reasonable option would be to declare that `field` takes raw HTML,
+>>>> in which case consumers need to only use it in contexts that will be
+>>>> HTML-scrubbed (but it becomes unsuitable for using as text - problematic
+>>>> for text-based things like sorting or URLs, and not ideal for searching).
+>>>>
+>>>> You could even let each consumer choose how it's going to use the field,
+>>>> by having the `foo` field generate `TEXT_FOO` and `HTML_FOO` variables?
+>>>> --[[smcv]]
+
+>>>>> Something similar is already done in `template` and `ftemplate` with the `raw_` prefix, which determines whether the variable should have `htmlize` run over it first before the value is applied to the template. Of course, that isn't scrubbing or escaping, because with those templates, the scrubbing is done afterwards as part of the normal processing.
+
+>>> Another problem, as you point out, is special-case fields, such as a number of
+>>> those defined by `meta`, which have side-effects associated with them, more
+>>> than just providing a value to pagetemplate. Perhaps `meta` should deal with
+>>> the side-effects, but use `field` as an interface to get the values of those special fields.
-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]]
+>>> --[[KathrynAndersen]]
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]]
<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]]
--- /dev/null
+[[!template id=plugin name=sortnaturally core=1 author="[[chrysn]], [[smcv]]"]]
+[[!tag type/meta]]
+
+This plugin provides the `title_natural` [[ikiwiki/pagespec/sorting]]
+order, which uses [[!cpan Sort::Naturally]] to sort numbered pages in a
+more natural order.
$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
* `filter` is a reference to a function, that is called and passed a page,
and returns true if the page should be filtered out of the list.
* `sort` specifies a sort order for the list. See
- [[ikiwiki/PageSpec/sorting]] for the avilable sort methods.
+ [[ikiwiki/PageSpec/sorting]] for the avilable sort methods. Note that
+ if a sort method is specified that depends on the
+ page content (such as 'meta(foo)'), the deptype needs to be set to
+ a content dependency.
* `reverse` if true, sorts in reverse.
* `num` if nonzero, specifies the maximum number of matching pages that
will be returned.
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
they match; "created_before(foo)" is influenced by the metadata of foo;
while "glob(*)" is not influenced by the contents of any page.
+### Sorting plugins
+
+Similarly, it's possible to write plugins that add new functions as
+[[ikiwiki/pagespec/sorting]] methods. To achieve this, add a function to
+the IkiWiki::SortSpec package named `cmp_foo`, which will be used when sorting
+by `foo` or `foo(...)` is requested.
+
+The names of pages to be compared are in the global variables `$a` and `$b`
+in the IkiWiki::SortSpec package. The function should return the same thing
+as Perl's `cmp` and `<=>` operators: negative if `$a` is less than `$b`,
+positive if `$a` is greater, or zero if they are considered equal. It may
+also raise an error using `error`, for instance if it needs a parameter but
+one isn't provided.
+
+The function will also be passed one or more parameters. The first is
+`undef` if invoked as `foo`, or the parameter `"bar"` if invoked as `foo(bar)`;
+it may also be passed additional, named parameters.
+
### Setup plugins
The ikiwiki setup file is loaded using a pluggable mechanism. If you look
whether it would be worth making sort=name an alias for the current sort=title,
and changing the meaning of sort=title in 4.0, though).
+> What compatability concerns, exactly, are there that prevent making that
+> change now? --[[Joey]]
+
*[sort-hooks branch now withdrawn in favour of sort-package --s]*
I briefly tried to turn *all* the current sort types into hook functions, and
>> 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:
>>>>>> `SortSpec` --[[Joey]]
->>>>>>> Done. --s
+>>>>>>> [[Done]]. --s
>>>> I would be inclined to drop the `check_` stuff. --[[Joey]]
> }
>
> 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
>> 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]]
+>> 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
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.
+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.
-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.
+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.
>>> For this to work with websetup and --dumpsetup, it needs to define the
>>> `meta_*` settings in the getsetup function.
+>>>>
+>>>> I think this will be problematic with the current implementation of this
+>>>> patch. The datatype here is an array of hash references, with each hash
+>>>> having a variable (and arbitrary) number of key/value pairs. I can't
+>>>> think of an intuitive way of implementing a way of editing such a
+>>>> datatype in the web interface, let alone registering the option in
+>>>> getsetup.
+>>>>
+>>>> Perhaps a limited set of defined meta values could be exposed via
+>>>> websetup (the obvious ones: author, copyright, license, etc.) -- [[Jon]]
>>>
>>> I also have some concerns about both these patches, since both throw
>>> a lot of redundant data at meta, which then stores it in a very redundant
>>> 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]]
+>>>>
+>>>> that should be easy enough to do. I will work on a patch. -- [[Jon]]
-------
->> [[!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
>> 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
--- /dev/null
+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]]
> 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]]
--- /dev/null
+#!/usr/bin/perl
+package IkiWiki;
+
+use warnings;
+use strict;
+use Test::More tests => 5;
+
+BEGIN { use_ok("IkiWiki"); }
+BEGIN { use_ok("IkiWiki::Render"); }
+%config=IkiWiki::defaultconfig();
+$config{srcdir}=$config{destdir}="/dev/null";
+
+%oldrenderedfiles=%pagectime=();
+%pagesources=%pagemtime=%oldlinks=%links=%depends=%typedlinks=%oldtypedlinks=
+%destsources=%renderedfiles=%pagecase=%pagestate=();
+
+IkiWiki::checkconfig();
+
+foreach my $page (qw(tags/a tags/b Reorder Add Remove TypeAdd TypeRemove)) {
+ $pagesources{$page} = "$page.mdwn";
+ $pagemtime{$page} = $pagectime{$page} = 1000000;
+}
+
+$oldlinks{Reorder} = [qw{tags/a tags/b}];
+$links{Reorder} = [qw{tags/b tags/a}];
+
+$oldlinks{Add} = [qw{tags/b}];
+$links{Add} = [qw{tags/a tags/b}];
+
+$oldlinks{Remove} = [qw{tags/a}];
+$links{Remove} = [];
+
+$oldlinks{TypeAdd} = [qw{tags/a tags/b}];
+$links{TypeAdd} = [qw{tags/a tags/b}];
+# This causes TypeAdd to be rebuilt, but isn't a backlink change, so it doesn't
+# cause tags/b to be rebuilt.
+$oldtypedlinks{TypeAdd}{tag} = { "tags/a" => 1 };
+$typedlinks{TypeAdd}{tag} = { "tags/a" => 1, "tags/b" => 1 };
+
+$oldlinks{TypeRemove} = [qw{tags/a tags/b}];
+$links{TypeRemove} = [qw{tags/a tags/b}];
+# This causes TypeRemove to be rebuilt, but isn't a backlink change, so it
+# doesn't cause tags/b to be rebuilt.
+$oldtypedlinks{TypeRemove}{tag} = { "tags/a" => 1 };
+$typedlinks{TypeRemove}{tag} = { "tags/a" => 1, "tags/b" => 1 };
+
+my $oldlink_targets = calculate_old_links([keys %pagesources], []);
+is_deeply($oldlink_targets, {
+ Reorder => { "tags/a" => "tags/a", "tags/b" => "tags/b" },
+ Add => { "tags/b" => "tags/b" },
+ Remove => { "tags/a" => "tags/a" },
+ TypeAdd => { "tags/a" => "tags/a", "tags/b" => "tags/b" },
+ TypeRemove => { "tags/a" => "tags/a", "tags/b" => "tags/b" },
+ });
+my ($backlinkchanged, $linkchangers) = calculate_changed_links([keys %pagesources], [], $oldlink_targets);
+
+is_deeply($backlinkchanged, { "tags/a" => 1 });
+is_deeply($linkchangers, { add => 1, remove => 1, typeadd => 1, typeremove => 1 });
use IkiWiki;
package IkiWiki; # use internal variables
-use Test::More tests => 27;
+use Test::More tests => 31;
$config{wikistatedir}="/tmp/ikiwiki-test.$$";
system "rm -rf $config{wikistatedir}";
$renderedfiles{"bar.png"}=["bar.png"];
$links{"Foo"}=["bar.png"];
$links{"bar"}=["Foo", "new-page"];
+$typedlinks{"bar"}={tag => {"Foo" => 1}};
$links{"bar.png"}=[];
$depends{"Foo"}={};
$depends{"bar"}={"foo*" => 1};
# Clear state.
%oldrenderedfiles=%pagectime=();
-%pagesources=%pagemtime=%oldlinks=%links=%depends=
+%pagesources=%pagemtime=%oldlinks=%links=%depends=%typedlinks=%oldtypedlinks=
%destsources=%renderedfiles=%pagecase=%pagestate=();
ok(loadindex(), "load index");
"sparkline-foo.gif" => "bar",
"bar.png" => "bar.png",
}, "%destsources generated correctly");
+is_deeply(\%typedlinks, {
+ bar => {tag => {"Foo" => 1}},
+}, "%typedlinks loaded correctly");
+is_deeply(\%oldtypedlinks, {
+ bar => {tag => {"Foo" => 1}},
+}, "%oldtypedlinks loaded correctly");
# Clear state.
%oldrenderedfiles=%pagectime=();
-%pagesources=%pagemtime=%oldlinks=%links=%depends=
+%pagesources=%pagemtime=%oldlinks=%links=%depends=%typedlinks=%oldtypedlinks=
%destsources=%renderedfiles=%pagecase=%pagestate=();
# When state is loaded for a wiki rebuild, only ctime and oldrenderedfiles
}, "%pagecase generated correctly");
is_deeply(\%destsources, {
}, "%destsources generated correctly");
+is_deeply(\%typedlinks, {
+}, "%typedlinks cleared correctly");
+is_deeply(\%oldtypedlinks, {
+}, "%oldtypedlinks cleared correctly");
system "rm -rf $config{wikistatedir}";
#!/usr/bin/perl
use warnings;
use strict;
-use Test::More tests => 88;
+use Test::More tests => 90;
BEGIN { use_ok("IkiWiki"); }
$config{srcdir}=$config{destdir}="/dev/null";
IkiWiki::checkconfig();
+{
+ package IkiWiki::SortSpec;
+
+ sub cmp_path { $a cmp $b }
+}
+
%pagesources=(
foo => "foo.mdwn",
foo2 => "foo2.mdwn",
"post/2" => "post/2.mdwn",
"post/3" => "post/3.mdwn",
);
+$IkiWiki::pagectime{foo} = 2;
+$IkiWiki::pagectime{foo2} = 2;
+$IkiWiki::pagectime{foo3} = 1;
+$IkiWiki::pagectime{bar} = 3;
+$IkiWiki::pagectime{"post/1"} = 6;
+$IkiWiki::pagectime{"post/2"} = 6;
+$IkiWiki::pagectime{"post/3"} = 6;
$links{foo}=[qw{post/1 post/2}];
$links{foo2}=[qw{bar}];
$links{foo3}=[qw{bar}];
is_deeply([pagespec_match_list("foo", "post/*", sort => "title",
filter => sub { $_[0] =~ /3/}) ],
["post/1", "post/2"]);
+is_deeply([pagespec_match_list("foo", "*", sort => "path", num => 2)],
+ ["bar", "foo"]);
+is_deeply([pagespec_match_list("foo", "foo* or bar*",
+ sort => "-age title")], # oldest first, break ties by title
+ ["foo3", "foo", "foo2", "bar"]);
my $r=eval { pagespec_match_list("foo", "beep") };
ok(eval { pagespec_match_list("foo", "beep") } == 0);
ok(! $@, "does not fail with error when unable to match anything");
--- /dev/null
+#!/usr/bin/perl
+package IkiWiki;
+
+use warnings;
+use strict;
+use Test::More tests => 10;
+
+BEGIN { use_ok("IkiWiki"); }
+BEGIN { use_ok("IkiWiki::Plugin::tag"); }
+
+ok(! system("rm -rf t/tmp; mkdir t/tmp"));
+
+$config{userdir} = "users";
+$config{tagbase} = "tags";
+
+%oldrenderedfiles=%pagectime=();
+%pagesources=%pagemtime=%oldlinks=%links=%depends=%typedlinks=%oldtypedlinks=
+%destsources=%renderedfiles=%pagecase=%pagestate=();
+
+foreach my $page (qw(tags/numbers tags/letters one two alpha beta)) {
+ $pagesources{$page} = "$page.mdwn";
+ $pagemtime{$page} = $pagectime{$page} = 1000000;
+}
+
+$links{one}=[qw(tags/numbers alpha tags/letters)];
+$links{two}=[qw(tags/numbers)];
+$links{alpha}=[qw(tags/letters one)];
+$links{beta}=[qw(tags/letters)];
+$typedlinks{one}={tag => {"tags/numbers" => 1 }};
+$typedlinks{two}={tag => {"tags/numbers" => 1 }};
+$typedlinks{alpha}={tag => {"tags/letters" => 1 }};
+$typedlinks{beta}={tag => {"tags/letters" => 1 }};
+
+ok(pagespec_match("one", "tagged(numbers)"));
+ok(!pagespec_match("two", "tagged(alpha)"));
+ok(pagespec_match("one", "link(tags/numbers)"));
+ok(pagespec_match("one", "link(alpha)"));
+
+ok(pagespec_match("one", "typedlink(tag tags/numbers)"));
+ok(!pagespec_match("one", "typedlink(tag tags/letters)"));
+# invalid syntax
+ok(pagespec_match("one", "typedlink(tag)")->isa("IkiWiki::ErrorReason"));
+
+1;
sipb-www / ikiwiki.git / commitdiff
