doc/todo/firm_up_plugin_interface.mdwn

   1 Reopening this for 3.0, to consider adding new functions.
   2
   3 I don't want this interface to be too firm; it's ok for a plugin like
   4 `ddate` to redefine an internal function like IkiWiki::displaytime if it
   5 wants to.. But plugins that still access stuff through IkiWiki:: should be
   6 aware that that stuff can change at any time and break them. Possibly without
   7 perl's type checking catching the breakage, in some cases. Plugins that
   8 only use exported symbols should not be broken by future ikiwiki changes.
   9
  10 ## Most often used functions, by number of calls from plugin code
  11
  12      27 IkiWiki::possibly_foolish_untaint
  13
  14 Not very happy about exporting, it's not ikiwiki-specific,
  15 and plugins that need to untaint things should think about it, hard.
  16
  17      12 IkiWiki::userinfo_get
  18       5 IkiWiki::userinfo_set
  19
  20 Used by only 4 plugins, all of which are fairly core, so thinking
  21 don't export.
  22
  23      11 IkiWiki::preprocess
  24       8 IkiWiki::filter
  25       4 IkiWiki::linkify
  26       4 IkiWiki::htmlize
  27
  28 The page rendering chain. Note that it's very common to call `preprocess(filter(text))`,
  29 or `htmlize(linkify(preprocess(filter(text))))`, while `htmlize(linkify(preprocess(text))`
  30 is called less frequently, and it's also not unheard of to leave out a step and do
  31 `htmlize(preprocess(text))`. (I haven't checked if any of those cases are bugs.)
  32
  33 It would be nice if the api could avoid exposing the details of the render chain,
  34 by providing a way to say "I have filtered text, and would like html", or "I have raw
  35 text and would like to get it up to the preprocess stage".
  36
  37 Another problimatic thing is plugins often define functions named 'preprocess', etc.
  38
  39      12 IkiWiki::linkpage
  40      11 IkiWiki::pagetitle
  41       6 IkiWiki::titlepage
  42
  43 These go together; linkpage is needed by all link plugins, and the others are used widely.
  44 All should be exported.
  45
  46       7 IkiWiki::saveindex
  47       5 IkiWiki::loadindex
  48
  49 Still too internal to ever be exported?
  50
  51       7 IkiWiki::redirect
  52
  53 Only used by 4 plugins, and not in IkiWiki.pm itself, so probably not to be exported.
  54
  55       7 IkiWiki::dirname
  56       4 IkiWiki::basename
  57
  58 Not ikiwiki-specific, don't export.
  59
  60       6 IkiWiki::refresh
  61
  62 Very internal, not part of IkiWiki.pm, don't export.
  63
  64       5 IkiWiki::yesno
  65
  66 Not ikiwiki-specific, but worth exporting to get a consistent localised yes/no parser
  67 for directives.
  68
  69       5 IkiWiki::showform
  70       4 IkiWiki::decode_form_utf8
  71
  72 Only used by 3 fairly core plugins, not in IkiWiki.pm, don't export.
  73
  74       5 IkiWiki::rcs_update
  75       4 IkiWiki::rcs_prepedit
  76       5 IkiWiki::is_admin
  77       5 IkiWiki::cgi_savesession
  78       4 IkiWiki::cgiurl
  79
  80 Not enough use, I think, to export.
  81
  82       5 IkiWiki::enable_commit_hook
  83       5 IkiWiki::disable_commit_hook
  84
  85 Deep internal magic, if exported people will use it wrong, only used by core plugins.
  86
  87       4 IkiWiki::check_canedit
  88
  89 Probably needs to evolve more and be more widely used before being exported.
  90
  91 ## Variables used by plugins but not exported yet
  92
  93 * %IkiWiki::pagecase (aggregate)
  94 * %IkiWiki::backlinks (pagestats)