b130e3d371ee0845c863ccfd02f3710b156ab89c
[ikiwiki.git] / 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      } # }}}