doc/todo/directive_docs.mdwn

   1 The current basewiki is not self-documenting. In particular, if
   2 [[plugins/listdirectives]] is used, it creates a list with a bunch of
   3 broken links to directives/*, pages that do not currently exist in the
   4 docwiki or basewiki.
   5
   6 This could be fixed by adding a page for each directive under to
   7 `ikiwiki/directives`, and put those into a new underlay, which the plugin
   8 could enable. Rather a lot of work and maintenance to document all the
   9 directives like that.
  10
  11 I also considered having it link to the plugin that defined the
  12 directive. Then all the plugins can be included in a new underlay, which
  13 both [[plugins/listdirectives]] and [[plugins/websetup]] could enable.
  14 (The latter could be improved by making the plugin names in the web setup
  15 be links to docs about each plugin..)
  16
  17 The problem I ran into doing that is that the existing plugin pages have a
  18 lot of stuff on them you probably don't want an underlay doing. The biggest
  19 issues were wikilinks to other pages in the docwiki (which would end up
  20 broken if the plugins were used as an underlay), and plugin pages that
  21 include examples of the plugin in use, which are sometimes rather expensive
  22 (eg, brokenlinks).
  23
  24 Either way requires a lot of reorganisation/doc work, and an onging
  25 maintenance load.
  26
  27 BTW, this patch would be needed for the second approach, to allow
  28 listdirectives to map from preprocessor directives back to the plugin that
  29 defined them:  --[[Joey]]
  30
  31     commit 0486b46a629cae19ce89492d5ac498bbf9b84f5f
  32     Author: Joey Hess <joey@kodama.kitenet.net>
  33     Date:   Mon Aug 25 15:38:51 2008 -0400
  34
  35         record which plugins registered which hooks
  36
  37     diff --git a/IkiWiki.pm b/IkiWiki.pm
  38     index e476521..afe982a 100644
  39     --- a/IkiWiki.pm
  40     +++ b/IkiWiki.pm
  41     @@ -493,6 +493,7 @@ sub loadplugins () { #{{{
  42         return 1;
  43      } #}}}
  44
  45     +my $loading_plugin;
  46      sub loadplugin ($) { #{{{
  47         my $plugin=shift;
  48
  49     @@ -502,14 +503,18 @@ sub loadplugin ($) { #{{{
  50                          "$installdir/lib/ikiwiki") {
  51                 if (defined $dir && -x "$dir/plugins/$plugin") {
  52                         require IkiWiki::Plugin::external;
  53     +                   $loading_plugin=$plugin;
  54                         import IkiWiki::Plugin::external "$dir/plugins/$plugin";
  55     +                   $loading_plugin=undef;
  56                         $loaded_plugins{$plugin}=1;
  57                         return 1;
  58                 }
  59         }
  60
  61         my $mod="IkiWiki::Plugin::".possibly_foolish_untaint($plugin);
  62     +   $loading_plugin=$plugin;
  63         eval qq{use $mod};
  64     +   $loading_plugin=undef;
  65         if ($@) {
  66                 error("Failed to load plugin $mod: $@");
  67         }
  68     @@ -1429,6 +1434,9 @@ sub hook (@) { # {{{
  69
  70         return if $param{no_override} && exists $hooks{$param{type}}{$param{id}};
  71
  72     +   # Record which plugin was being loaded when the hook was defined.
  73     +   $param{plugin}=$loading_plugin if defined $loading_plugin;
  74     +
  75         $hooks{$param{type}}{$param{id}}=\%param;
  76         return 1;
  77      } # }}}