Add an underlay for javascript, and add ikiwiki.js containing some utility code.

[git.ikiwiki.info.git] / doc / todo / firm_up_plugin_interface.mdwn

diff --git a/doc/todo/firm_up_plugin_interface.mdwn b/doc/todo/firm_up_plugin_interface.mdwn
index e23f2f3d6ea6dafc44ca636a29ffa7f59987de05..b0e92e65c475ab688424f94603fb5c151b804575 100644 (file)
--- a/doc/todo/firm_up_plugin_interface.mdwn
+++ b/doc/todo/firm_up_plugin_interface.mdwn
@@ -1,72 +1,94 @@
-The plugin interface is currently that they can register hooks, and can
-call any other ikiwiki internal function they desire, generally through
-Ikiwiki::function calls. Also, some Ikiwiki::config etc variables can be
-used.
-
-This is a very weak interface, and should be firmed up to something more
-like a proper perl library. I've been waiting to get some idea of what bits
-of ikiwiki are most useful to plugins before doing it; there are plenty of
-plugins to know that now.
-
-IkiWiki will now  export some function calls and variables when loaded.
-
-Functions used by many plugins, which I'm sure should be exported:
-
-* hook
-* debug
-* error
-* template
-* htmlpage
-* add_depends
-* pagespec_match
-* bestlink
-* htmllink
-* readfile
-* writefile
-* pagetype
-* srcfile
-* pagename
-* displaytime
-
-Functions used by only some plugins, undecided:
-
-* lockwiki, unlockwiki (aggregate)
-       Too internal to ever be exported.
-* loadindex (aggregate)
-       Too internal to ever be exported.
-* titlepage (aggregate)
-       Not until more than one thing uses it.
-* basename (polygen, inline, search, polygen)
-* dirname (linkmap, inline)
-       For basename and dirname, they could just use standard perl library
-       stuff. Howevever, ikiwiki's versions are slightly different and I'd
-       need to check if the standard versions work for the uses made in
-       these plugins. Inclined not to export.
-* abs2rel (linkmap, inline)
-       This *is* the library version, just optimised to work around a bug.
-       Don't export this.
-* possibly_foolish_untaint (aggregate, polygen)
-       Probably better to implement yourself.
-* htmlize
-* linkify
-* preprocess
-* filter
-       Used by several, but problimatic since plugins typically define
-       functions with these names..
-
-Variables used by plugins:
-
-* %IkiWiki::config (various values; probably not worth locking down any
-  more, export it)
-* %IkiWiki::links (many, seems clearcut to export)
-* %IkiWiki::renderedfiles (orphans, inline, search)
-* %IkiWiki::pagesources (pagecount, sidebar, template, inline)
-* %IkiWiki::pagecase (aggregate.. will not export yet)
-* %IkiWIki::backlinks (pagestats.. will not export yet)
+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
 
 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 break by future ikiwiki changes.
+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.
+
+      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)