aboutsummaryrefslogtreecommitdiff
path: root/doc/todo
diff options
context:
space:
mode:
authorjoey <joey@0fa5a96a-9a0e-0410-b3b2-a0fd24251071>2006-09-09 22:50:27 +0000
committerjoey <joey@0fa5a96a-9a0e-0410-b3b2-a0fd24251071>2006-09-09 22:50:27 +0000
commitdae0f48e91304afcb6ebe0936360e51b22a56548 (patch)
tree930090e4343087dac7ae6693d420d80b826c57f2 /doc/todo
parentd92142d09eaec9018c0cdc96f9ad3bd4a0c876a7 (diff)
downloadikiwiki-dae0f48e91304afcb6ebe0936360e51b22a56548.tar
ikiwiki-dae0f48e91304afcb6ebe0936360e51b22a56548.tar.gz
* Work on firming up the plugin interface:
- Plugins should not need to load IkiWiki::Render to get commonly used functions, so moved some functions from there to IkiWiki. - Picked out the set of functions and variables that most plugins use, documented them, and made IkiWiki export them by default, like a proper perl module should. - Use the other functions at your own risk. - This is not quite complete, I still have to decide whether to export some other things. * Changed all plugins included in ikiwiki to not use "IkiWiki::" when referring to stuff now exported by the IkiWiki module. * Anyone with a third-party ikiwiki plugin is strongly enrouraged to make like changes to it and avoid use of non-exported symboles from "IkiWiki::". * Link debian/changelog and debian/news to NEWS and CHANGELOG. * Support hyperestradier version 1.4.2, which adds a new required phraseform setting.
Diffstat (limited to 'doc/todo')
-rw-r--r--doc/todo/firm_up_plugin_interface.mdwn72
1 files changed, 72 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..e23f2f3d6
--- /dev/null
+++ b/doc/todo/firm_up_plugin_interface.mdwn
@@ -0,0 +1,72 @@
+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)
+
+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.