From eea52bccc967890c89cc9f87b16844a0a87ce5dc Mon Sep 17 00:00:00 2001 From: intrigeri Date: Mon, 20 Oct 2008 18:54:04 -0400 Subject: initial plugin public apparition --- doc/plugins/contrib/po.mdwn | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 doc/plugins/contrib/po.mdwn (limited to 'doc/plugins/contrib/po.mdwn') diff --git a/doc/plugins/contrib/po.mdwn b/doc/plugins/contrib/po.mdwn new file mode 100644 index 000000000..06d491d01 --- /dev/null +++ b/doc/plugins/contrib/po.mdwn @@ -0,0 +1,16 @@ +I've been working on a plugin called "po", that adds support for multi-lingual wikis, +translated with gettext, using [po4a](http://po4a.alioth.debian.org/). + +More information: + +* It can be found in my "po" branch on http://repo.or.cz/w/ikiwiki/intrigeri.git +* It involves adding three hooks to ikiwiki core. +* It is documented (including TODO and plans for next work steps) in `doc/plugins/po.mdwn`, which can be found in the same branch. +* No public demo site is available so far, I'm working on this. + +My plan is to get this plugin clean enough to be included in ikiwiki. + +The current version is a proof-of-concept, mature enough for me to dare submitting it here, +but I'm prepared to hear various helpful remarks, and to rewrite parts of it as needed. + +Any thoughts on this? -- cgit v1.2.3 From 93959d45db207690da03f1da216894821bfd78da Mon Sep 17 00:00:00 2001 From: intrigeri Date: Mon, 20 Oct 2008 18:56:21 -0400 Subject: formatting, added git clone information --- doc/plugins/contrib/po.mdwn | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/plugins/contrib/po.mdwn') diff --git a/doc/plugins/contrib/po.mdwn b/doc/plugins/contrib/po.mdwn index 06d491d01..b22b8c179 100644 --- a/doc/plugins/contrib/po.mdwn +++ b/doc/plugins/contrib/po.mdwn @@ -3,7 +3,7 @@ translated with gettext, using [po4a](http://po4a.alioth.debian.org/). More information: -* It can be found in my "po" branch on http://repo.or.cz/w/ikiwiki/intrigeri.git +* It can be found in [my "po" branch](http://repo.or.cz/w/ikiwiki/intrigeri.git?a=shortlog;h=refs/heads/po): `git clone git://repo.or.cz/ikiwiki/intrigeri.git` * It involves adding three hooks to ikiwiki core. * It is documented (including TODO and plans for next work steps) in `doc/plugins/po.mdwn`, which can be found in the same branch. * No public demo site is available so far, I'm working on this. -- cgit v1.2.3 From 2c89dacde45d257207067cdeeb84dc7923f6cdad Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Mon, 20 Oct 2008 19:18:49 -0400 Subject: wow --- doc/plugins/contrib/po.mdwn | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'doc/plugins/contrib/po.mdwn') diff --git a/doc/plugins/contrib/po.mdwn b/doc/plugins/contrib/po.mdwn index 06d491d01..83fc6c57c 100644 --- a/doc/plugins/contrib/po.mdwn +++ b/doc/plugins/contrib/po.mdwn @@ -14,3 +14,17 @@ The current version is a proof-of-concept, mature enough for me to dare submitti but I'm prepared to hear various helpful remarks, and to rewrite parts of it as needed. Any thoughts on this? + +> Well, I think it's pretty stunning what you've done here. Seems very +> complete and well thought out. I have not read the code in great detail +> yet. +> +> Just using po files is an approach I've never seen tried with a wiki. I +> suspect it will work better for some wikis than others. For wikis that +> just want translations that match the master language as closely as +> possible and don't wander off and diverge, it seems perfect. (But what happens +> if someone edits the Discussion page of a translated page?) +> +> Please keep me posted, when you get closer to having all issues solved +> and ready for merging I can do a review and hopefully help with the +> security items you listed. --[[Joey]] -- cgit v1.2.3 From 94797b66c4d7f807245aa4bf09dd645468079142 Mon Sep 17 00:00:00 2001 From: intrigeri Date: Mon, 20 Oct 2008 19:45:49 -0400 Subject: answering joey --- doc/plugins/contrib/po.mdwn | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'doc/plugins/contrib/po.mdwn') diff --git a/doc/plugins/contrib/po.mdwn b/doc/plugins/contrib/po.mdwn index ad06e8570..cbc046d98 100644 --- a/doc/plugins/contrib/po.mdwn +++ b/doc/plugins/contrib/po.mdwn @@ -28,3 +28,19 @@ Any thoughts on this? > Please keep me posted, when you get closer to having all issues solved > and ready for merging I can do a review and hopefully help with the > security items you listed. --[[Joey]] + +>> Thanks a lot for your quick review, it's reassuring to hear such nice words +>> from you. I did not want to design and write a full translation system, when +>> tools such as gettext/po4a already have all the needed functionality, for cases +>> where the master/slave languages paradigm fits. +>> Integrating these tools into ikiwiki plugin system was a pleasure. +>> +>> I'll tell you when I'm ready for merging, but in the meantime, +>> I'd like you to review the changes I did to the core (3 added hooks). +>> Can you please do this? If not, I'll go on and hope I'm not going to far in +>> the wrong direction. +>> +>> The Discussion pages issue is something I am not sure about yet. But I will +>> probably decide that "slave" pages, being only translations, don't deserve +>> a discussion page: the discussion should happen in the language in which the +>> pages are written for real, which is the "master" one. --[[intrigeri]] -- cgit v1.2.3 From ec566c02fdf4e1f76e6559afbb8c01ec772412f8 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Mon, 20 Oct 2008 20:57:42 -0400 Subject: response --- doc/plugins/contrib/po.mdwn | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'doc/plugins/contrib/po.mdwn') diff --git a/doc/plugins/contrib/po.mdwn b/doc/plugins/contrib/po.mdwn index cbc046d98..30ede95a6 100644 --- a/doc/plugins/contrib/po.mdwn +++ b/doc/plugins/contrib/po.mdwn @@ -40,6 +40,14 @@ Any thoughts on this? >> Can you please do this? If not, I'll go on and hope I'm not going to far in >> the wrong direction. >> +>>> Sure.. I'm not completly happy with any of the hooks since they're very +>>> special purpose, and also since `run_hooks` is not the best interface +>>> for a hook that modifies a variable, where only the last hook run will +>>> actually do anything. It might be better to just wrap +>>> `targetpage`, `bestlink`, and `beautify_urlpath`. But, I noticed +>>> the other day that such wrappers around exported functions are only visible by +>>> plugins loaded after the plugin that defines them. +>> >> The Discussion pages issue is something I am not sure about yet. But I will >> probably decide that "slave" pages, being only translations, don't deserve >> a discussion page: the discussion should happen in the language in which the -- cgit v1.2.3 From e75818572fff5256d16221a2b065b214d8cb9f5d Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Tue, 21 Oct 2008 17:57:19 -0400 Subject: function injection overhaul Add an inject function, that can be used by plugins that want to replace one of ikiwiki's functions with their own version. (This is a scary thing that grubs through the symbol table, and replaces all exported occurances of a function with the injected version.) external: RPC functions can be injected to replace exported functions. Removed the stupid displaytime hook, and use injection instead. --- IkiWiki.pm | 46 +++++++++++++++++++++++++------------- IkiWiki/Plugin/external.pm | 8 ++++++- IkiWiki/Plugin/relativedate.pm | 4 ++-- debian/changelog | 5 +++++ doc/plugins/contrib/po.mdwn | 5 +++++ doc/plugins/write.mdwn | 50 ++++++++++++++++++++++++++++++++++++++++++ plugins/externaldemo | 10 ++++----- po/ikiwiki.pot | 14 ++++++------ 8 files changed, 111 insertions(+), 31 deletions(-) (limited to 'doc/plugins/contrib/po.mdwn') diff --git a/IkiWiki.pm b/IkiWiki.pm index 207ca87fb..e0454963d 100644 --- a/IkiWiki.pm +++ b/IkiWiki.pm @@ -21,6 +21,7 @@ our @EXPORT = qw(hook debug error template htmlpage add_depends pagespec_match bestlink htmllink readfile writefile pagetype srcfile pagename displaytime will_render gettext urlto targetpage add_underlay pagetitle titlepage linkpage newpagefile + inject %config %links %pagestate %wikistate %renderedfiles %pagesources %destsources); our $VERSION = 2.00; # plugin interface version, next is ikiwiki version @@ -898,23 +899,13 @@ sub abs2rel ($$) { #{{{ } #}}} sub displaytime ($;$) { #{{{ - my $time=shift; - my $format=shift; - if (exists $hooks{displaytime}) { - my $ret; - run_hooks(displaytime => sub { - $ret=shift->($time, $format) - }); - return $ret; - } - else { - return formattime($time, $format); - } + # Plugins can override this function to mark up the time to + # display. + return ''.formattime(@_).''; } #}}} sub formattime ($;$) { #{{{ - # Plugins can override this function to mark up the time for - # display. + # Plugins can override this function to format the time. my $time=shift; my $format=shift; if (! defined $format) { @@ -1676,6 +1667,31 @@ sub yesno ($) { #{{{ return (defined $val && lc($val) eq gettext("yes")); } #}}} +sub inject { #{{{ + # Injects a new function into the symbol table to replace an + # exported function. + my %params=@_; + + # This is deep ugly perl foo, beware. + no strict; + no warnings; + if (! defined $params{parent}) { + $params{parent}='::'; + $params{old}=\&{$params{name}}; + $params{name}=~s/.*:://; + } + my $parent=$params{parent}; + foreach my $ns (grep /^\w+::/, keys %{$parent}) { + $ns = $params{parent} . $ns; + inject(%params, parent => $ns) unless $ns eq '::main::'; + *{$ns . $params{name}} = $params{call} + if exists ${$ns}{$params{name}} && + \&{${$ns}{$params{name}}} == $params{old}; + } + use strict; + use warnings; +} #}}} + sub pagespec_merge ($$) { #{{{ my $a=shift; my $b=shift; @@ -1770,7 +1786,7 @@ sub pagespec_valid ($) { #{{{ my $sub=pagespec_translate($spec); return ! $@; } #}}} - + sub glob2re ($) { #{{{ my $re=quotemeta(shift); $re=~s/\\\*/.*/g; diff --git a/IkiWiki/Plugin/external.pm b/IkiWiki/Plugin/external.pm index 287e118f1..4ce9c8bab 100644 --- a/IkiWiki/Plugin/external.pm +++ b/IkiWiki/Plugin/external.pm @@ -202,10 +202,16 @@ sub inject ($@) { #{{{ my $sub = sub { IkiWiki::Plugin::external::rpc_call($plugin, $params{call}, @_) }; + $sub=memoize($sub) if $params{memoize}; + + # This will add it to the symbol table even if not present. no warnings; eval qq{*$params{name}=\$sub}; use warnings; - memoize($params{name}) if $params{memoize}; + + # This will ensure that everywhere it was exported to sees + # the injected version. + IkiWiki::inject(name => $params{name}, call => $sub); return 1; } #}}} diff --git a/IkiWiki/Plugin/relativedate.pm b/IkiWiki/Plugin/relativedate.pm index f4dba61a4..dc8f7d538 100644 --- a/IkiWiki/Plugin/relativedate.pm +++ b/IkiWiki/Plugin/relativedate.pm @@ -12,7 +12,7 @@ sub import { #{{{ add_underlay("javascript"); hook(type => "getsetup", id => "relativedate", call => \&getsetup); hook(type => "format", id => "relativedate", call => \&format); - hook(type => "displaytime", id => "relativedate", call => \&display); + inject(name => "IkiWiki::displaytime", call => \&mydisplaytime); } # }}} sub getsetup () { #{{{ @@ -43,7 +43,7 @@ sub include_javascript ($;$) { #{{{ '" type="text/javascript" charset="utf-8">'; } #}}} -sub display ($;$) { #{{{ +sub mydisplaytime ($;$) { #{{{ my $time=shift; my $format=shift; diff --git a/debian/changelog b/debian/changelog index 928cd8666..e1baea8ce 100644 --- a/debian/changelog +++ b/debian/changelog @@ -24,6 +24,11 @@ ikiwiki (2.68) UNRELEASED; urgency=low the toplevel tagpage, and not closer subpages. The html links already went there, but internally the links were not recorded as absolute, which could cause confusing backlinks etc. + * Add an inject function, that can be used by plugins that want to + replace one of ikiwiki's functions with their own version. + (This is a scary thing that grubs through the symbol table, and replaces + all exported occurances of a function with the injected version.) + * external: RPC functions can be injected to replace exported functions. -- Joey Hess Fri, 17 Oct 2008 20:11:02 -0400 diff --git a/doc/plugins/contrib/po.mdwn b/doc/plugins/contrib/po.mdwn index 30ede95a6..c4b7f9ee9 100644 --- a/doc/plugins/contrib/po.mdwn +++ b/doc/plugins/contrib/po.mdwn @@ -47,6 +47,11 @@ Any thoughts on this? >>> `targetpage`, `bestlink`, and `beautify_urlpath`. But, I noticed >>> the other day that such wrappers around exported functions are only visible by >>> plugins loaded after the plugin that defines them. +>>> +>>> Update: Take a look at the new "Function overriding" section of +>>> [[plugins/write]]. I think you can just inject wrappers about a few ikiwiki +>>> functions, rather than adding hooks. The `inject` function is pretty +>>> insane^Wlow level, but seems to work great. --[[Joey]] >> >> The Discussion pages issue is something I am not sure about yet. But I will >> probably decide that "slave" pages, being only translations, don't deserve diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index 856b34ba1..2e11e6234 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -854,6 +854,56 @@ By the way, to parse a ikiwiki setup file and populate `%config`, a program just needs to do something like: `use IkiWiki::Setup; IkiWiki::Setup::load($filename)` +### Function overriding + +Sometimes using ikiwiki's pre-defined hooks is not enough. Your plugin +may need to replace one of ikiwiki's own functions with a modified version, +or wrap one of the functions. + +For example, your plugin might want to override `displaytime`, to change +the html markup used when displaying a date. Or it might want to override +`IkiWiki::formattime`, to change how a date is formatted. Or perhaps you +want to override `bestlink` and change how ikiwiki deals with WikiLinks. + +By venturing into this territory, your plugin is becoming tightly tied to +ikiwiki's internals. And it might break if those internals change. But +don't let that stop you, if you're brave. + +Ikiwiki provides an `inject()` function, that is a powerful way to replace +any function with one of your own. This even allows you to inject a +replacement for an exported function, like `bestlink`. Everything that +imports that function will get your version instead. Pass it the name of +the function to replace, and a new function to call. + +For example, here's how to replace `displaytime` with a version using HTML 5 +markup: + + inject(name => 'IkiWiki::displaytime', call => sub { + return ""; + }); + +Here's how to wrap `bestlink` with a version that tries to handle +plural words: + + my $origbestlink=\&bestlink; + inject(name => 'IkiWiki::bestlink', call => \&mybestlink); + + sub deplural ($) { + my $word=shift; + $word =~ s/e?s$//; # just an example :-) + return $word; + } + + sub mybestlink ($$) { + my $page=shift; + my $link=shift; + my $ret=$origbestlink->($page, $link); + if (! length $ret) { + $ret=$origbestlink->($page, deplural($link)); + } + return $ret; + } + ### Javascript Some plugins use javascript to make ikiwiki look a bit more web-2.0-ish. diff --git a/plugins/externaldemo b/plugins/externaldemo index 4d13f2444..be7aba8b9 100755 --- a/plugins/externaldemo +++ b/plugins/externaldemo @@ -106,9 +106,8 @@ sub import { rpc_call("getvar", "config", "url")."\n"; # Here's an example of how to inject an arbitrary function into - # ikiwiki, replacing a core function. - # Note use of automatic memoization. - rpc_call("inject", name => "IkiWiki::formattime", + # ikiwiki. Note use of automatic memoization. + rpc_call("inject", name => "IkiWiki::bob", call => "formattime", memoize => 1); print STDERR "externaldemo plugin successfully imported\n"; @@ -126,9 +125,8 @@ sub preprocess { return "externaldemo plugin preprocessing on $title!"; } -sub formattime { - print STDERR "externaldemo plugin's formattime called via RPC"; - return scalar "formatted time: ".localtime(shift); +sub bob { + print STDERR "externaldemo plugin's bob called via RPC"; } # Now all that's left to do is loop and handle each incoming RPC request. diff --git a/po/ikiwiki.pot b/po/ikiwiki.pot index 335575f02..4452ea8dc 100644 --- a/po/ikiwiki.pot +++ b/po/ikiwiki.pot @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2008-10-19 20:06-0400\n" +"POT-Creation-Date: 2008-10-21 17:51-0400\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" @@ -48,7 +48,7 @@ msgstr "" msgid "You are banned." msgstr "" -#: ../IkiWiki/CGI.pm:385 ../IkiWiki/CGI.pm:386 ../IkiWiki.pm:1182 +#: ../IkiWiki/CGI.pm:385 ../IkiWiki/CGI.pm:386 ../IkiWiki.pm:1175 msgid "Error" msgstr "" @@ -913,25 +913,25 @@ msgstr "" msgid "refreshing wiki.." msgstr "" -#: ../IkiWiki.pm:458 +#: ../IkiWiki.pm:459 msgid "Must specify url to wiki with --url when using --cgi" msgstr "" -#: ../IkiWiki.pm:504 +#: ../IkiWiki.pm:505 msgid "cannot use multiple rcs plugins" msgstr "" -#: ../IkiWiki.pm:533 +#: ../IkiWiki.pm:534 #, perl-format msgid "failed to load external plugin needed for %s plugin: %s" msgstr "" -#: ../IkiWiki.pm:1165 +#: ../IkiWiki.pm:1158 #, perl-format msgid "preprocessing loop detected on %s at depth %i" msgstr "" -#: ../IkiWiki.pm:1674 +#: ../IkiWiki.pm:1667 msgid "yes" msgstr "" -- cgit v1.2.3 From b33ce3139cd5be5e5d903c62ce1e281af2645d6f Mon Sep 17 00:00:00 2001 From: intrigeri Date: Tue, 21 Oct 2008 19:17:49 -0400 Subject: thanks! --- doc/plugins/contrib/po.mdwn | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'doc/plugins/contrib/po.mdwn') diff --git a/doc/plugins/contrib/po.mdwn b/doc/plugins/contrib/po.mdwn index c4b7f9ee9..f60b8fbea 100644 --- a/doc/plugins/contrib/po.mdwn +++ b/doc/plugins/contrib/po.mdwn @@ -53,6 +53,10 @@ Any thoughts on this? >>> functions, rather than adding hooks. The `inject` function is pretty >>> insane^Wlow level, but seems to work great. --[[Joey]] >> +>>>> Thanks a lot, it seems to be a nice interface for what I was trying to achieve. +>>>> I may be forced to wait two long weeks before I have a chance to confirm +>>>> this. Stay tuned. --[[intrigeri]] +>> >> The Discussion pages issue is something I am not sure about yet. But I will >> probably decide that "slave" pages, being only translations, don't deserve >> a discussion page: the discussion should happen in the language in which the -- cgit v1.2.3