diff options
Diffstat (limited to 'doc/todo/directive_docs.mdwn')
| -rw-r--r-- | doc/todo/directive_docs.mdwn | 79 |
1 files changed, 79 insertions, 0 deletions
diff --git a/doc/todo/directive_docs.mdwn b/doc/todo/directive_docs.mdwn new file mode 100644 index 000000000..2baa61b40 --- /dev/null +++ b/doc/todo/directive_docs.mdwn @@ -0,0 +1,79 @@ +The current basewiki is not [[self-documenting|todo/basewiki_should_be_self_documenting]]. In particular, if +[[plugins/listdirectives]] is used, it creates a list with a bunch of +broken links to directives/*, pages that do not currently exist in the +docwiki or basewiki. + +This could be fixed by adding a page for each directive under to +`ikiwiki/directives`, and put those into a new underlay, which the plugin +could enable. Rather a lot of work and maintenance to document all the +directives like that. + +I also considered having it link to the plugin that defined the +directive. Then all the plugins can be included in a new underlay, which +both [[plugins/listdirectives]] and [[plugins/websetup]] could enable. +(The latter could be improved by making the plugin names in the web setup +be links to docs about each plugin..) + +The problem I ran into doing that is that the existing plugin pages have a +lot of stuff on them you probably don't want an underlay doing. The biggest +issues were wikilinks to other pages in the docwiki (which would end up +broken if the plugins were used as an underlay), and plugin pages that +include examples of the plugin in use, which are sometimes rather expensive +(eg, brokenlinks). + +Either way requires a lot of reorganisation/doc work, and an onging +maintenance load. + +> Which has now been [[done]]. -- [[Will]] + +BTW, this patch would be needed for the second approach, to allow +listdirectives to map from preprocessor directives back to the plugin that +defined them: --[[Joey]] + + commit 0486b46a629cae19ce89492d5ac498bbf9b84f5f + Author: Joey Hess <joey@kodama.kitenet.net> + Date: Mon Aug 25 15:38:51 2008 -0400 + + record which plugins registered which hooks + + diff --git a/IkiWiki.pm b/IkiWiki.pm + index e476521..afe982a 100644 + --- a/IkiWiki.pm + +++ b/IkiWiki.pm + @@ -493,6 +493,7 @@ sub loadplugins () { + return 1; + } + + +my $loading_plugin; + sub loadplugin ($) { + my $plugin=shift; + + @@ -502,14 +503,18 @@ sub loadplugin ($) { + "$installdir/lib/ikiwiki") { + if (defined $dir && -x "$dir/plugins/$plugin") { + require IkiWiki::Plugin::external; + + $loading_plugin=$plugin; + import IkiWiki::Plugin::external "$dir/plugins/$plugin"; + + $loading_plugin=undef; + $loaded_plugins{$plugin}=1; + return 1; + } + } + + my $mod="IkiWiki::Plugin::".possibly_foolish_untaint($plugin); + + $loading_plugin=$plugin; + eval qq{use $mod}; + + $loading_plugin=undef; + if ($@) { + error("Failed to load plugin $mod: $@"); + } + @@ -1429,6 +1434,9 @@ sub hook (@) { + + return if $param{no_override} && exists $hooks{$param{type}}{$param{id}}; + + + # Record which plugin was being loaded when the hook was defined. + + $param{plugin}=$loading_plugin if defined $loading_plugin; + + + $hooks{$param{type}}{$param{id}}=\%param; + return 1; + } |