diff options
Diffstat (limited to 'doc/todo/firm_up_plugin_interface.mdwn')
-rw-r--r-- | doc/todo/firm_up_plugin_interface.mdwn | 96 |
1 files changed, 96 insertions, 0 deletions
diff --git a/doc/todo/firm_up_plugin_interface.mdwn b/doc/todo/firm_up_plugin_interface.mdwn new file mode 100644 index 000000000..c7553f7dd --- /dev/null +++ b/doc/todo/firm_up_plugin_interface.mdwn @@ -0,0 +1,96 @@ +Reopening this for 3.0, to consider adding new functions. + +I don't want this interface to be too firm; it's ok for a plugin like +`ddate` to redefine an internal function like IkiWiki::displaytime if it +wants to.. But plugins that still access stuff through IkiWiki:: should be +aware that that stuff can change at any time and break them. Possibly without +perl's type checking catching the breakage, in some cases. Plugins that +only use exported symbols should not be broken by future ikiwiki changes. + +## Most often used functions, by number of calls from plugin code + + 27 IkiWiki::possibly_foolish_untaint + +Not very happy about exporting, it's not ikiwiki-specific, +and plugins that need to untaint things should think about it, hard. + + 12 IkiWiki::userinfo_get + 5 IkiWiki::userinfo_set + +Used by only 4 plugins, all of which are fairly core, so thinking +don't export. + + 11 IkiWiki::preprocess + 8 IkiWiki::filter + 4 IkiWiki::linkify + 4 IkiWiki::htmlize + +The page rendering chain. Note that it's very common to call `preprocess(filter(text))`, +or `htmlize(linkify(preprocess(filter(text))))`, while `htmlize(linkify(preprocess(text))` +is called less frequently, and it's also not unheard of to leave out a step and do +`htmlize(preprocess(text))`. (I haven't checked if any of those cases are bugs.) + +It would be nice if the api could avoid exposing the details of the render chain, +by providing a way to say "I have filtered text, and would like html", or "I have raw +text and would like to get it up to the preprocess stage". + +Another problimatic thing is plugins often define functions named 'preprocess', etc. + + 12 IkiWiki::linkpage + 11 IkiWiki::pagetitle + 6 IkiWiki::titlepage + +These go together; linkpage is needed by all link plugins, and the others are used widely. +All should be exported. (Done) + + 7 IkiWiki::saveindex + 5 IkiWiki::loadindex + +Still too internal to ever be exported? + + 7 IkiWiki::redirect + +Only used by 4 plugins, and not in IkiWiki.pm itself, so probably not to be exported. + + 7 IkiWiki::dirname + 4 IkiWiki::basename + +Not ikiwiki-specific, don't export. + + 6 IkiWiki::refresh + +Very internal, not part of IkiWiki.pm, don't export. + + 5 IkiWiki::yesno + +Not ikiwiki-specific, but worth exporting to get a consistent localised yes/no parser +for directives. + + 5 IkiWiki::showform + 4 IkiWiki::decode_form_utf8 + +Only used by 3 fairly core plugins, not in IkiWiki.pm, don't export. + + 5 IkiWiki::rcs_update + 4 IkiWiki::rcs_prepedit + 5 IkiWiki::is_admin + 5 IkiWiki::cgi_savesession + 4 IkiWiki::cgiurl + +Not enough use, I think, to export. + + 5 IkiWiki::enable_commit_hook + 5 IkiWiki::disable_commit_hook + +Deep internal magic, if exported people will use it wrong, only used by core plugins. + + 4 IkiWiki::check_canedit + +Probably needs to evolve more and be more widely used before being exported. + +## Variables used by plugins but not exported yet + +* %IkiWiki::pagecase (aggregate) +* %IkiWiki::backlinks (pagestats) + +[[done]] (until 4.0).. |