diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/todo/Add_a_plugin_to_list_available_pre-processor_commands.mdwn | 279 | ||||
| -rw-r--r-- | doc/todo/directive_docs.mdwn | 77 |
2 files changed, 79 insertions, 277 deletions
diff --git a/doc/todo/Add_a_plugin_to_list_available_pre-processor_commands.mdwn b/doc/todo/Add_a_plugin_to_list_available_pre-processor_commands.mdwn index b8ef2409d..9ac400cd2 100644 --- a/doc/todo/Add_a_plugin_to_list_available_pre-processor_commands.mdwn +++ b/doc/todo/Add_a_plugin_to_list_available_pre-processor_commands.mdwn @@ -137,280 +137,5 @@ I've found myself wanting to know which [[plugins]] are switched on so I know wh >>>>>>>>> Yeah - that would make sense. done. -- [[Will]] - #!/usr/bin/perl - # Ikiwiki listpreprocessors plugin. - package IkiWiki::Plugin::listpreprocessors; - - use warnings; - use strict; - use IkiWiki 2.00; - - sub import { #{{{ - hook(type => "getsetup", id => "listpreprocessors", call => \&getsetup); - hook(type => "checkconfig", id => "listpreprocessors", call => \&checkconfig); - hook(type => "needsbuild", id => "listpreprocessors", call => \&needsbuild); - hook(type => "preprocess", id => "listpreprocessors", call => \&preprocess); - } # }}} - - sub getsetup () { #{{{ - return - plugin => { - safe => 1, - rebuild => undef, - }, - preprocessor_description_dir => { - type => "string", - description => "The ikiwiki directory that contains plugin descriptions.", - safe => 1, - rebuild => 1, - }, - } #}}} - - my @fullPluginList; - my @earlyPluginList; - my $pluginString; - - sub checkconfig () { #{{{ - if (!defined $config{plugin_description_dir}) { - $config{plugin_description_dir} = "ikiwiki/plugin/"; - } - - @earlyPluginList = sort( keys %{ $IkiWiki::hooks{preprocess} } ); - } #}}} - - sub needsbuild (@) { #{{{ - my $needsbuild=shift; - - @fullPluginList = sort( keys %{ $IkiWiki::hooks{preprocess} } ); - $pluginString = join (' ', @earlyPluginList) . " : ". join (' ', @fullPluginList); - - foreach my $page (keys %pagestate) { - if (exists $pagestate{$page}{listpreprocessors}{shown}) { - if ($pagestate{$page}{listpreprocessors}{shown} ne $pluginString) { - push @$needsbuild, $pagesources{$page}; - } - if (exists $pagesources{$page} && - grep { $_ eq $pagesources{$page} } @$needsbuild) { - # remove state, will be re-added if - # the [[!listpreprocessors]] is still there during the - # rebuild - delete $pagestate{$page}{listpreprocessors}{shown}; - } - } - } - } # }}} - - sub preprocess (@) { #{{{ - my %params=@_; - - $pagestate{$params{destpage}}{listpreprocessors}{shown}=$pluginString; - - my @pluginlist; - - if (defined $params{generated}) { - @pluginlist = @fullPluginList; - } else { - @pluginlist = @earlyPluginList; - } - - my $result = '<ul class="listpreprocessors">'; - - foreach my $plugin (@pluginlist) { - $result .= '<li class="listpreprocessors">'; - $result .= htmllink($params{page}, $params{destpage}, IkiWiki::linkpage($config{plugin_description_dir} . $plugin)); - $result .= '</li>'; - } - - $result .= "</ul>"; - - return $result; - } # }}} - - 1 - ----- - -Here is the main listpreprocessors plugin. (Note, because this has double -square brackets in the source, it isn't quite displaying correctly - look -at the page source for details.) New template files follow: - - #!/usr/bin/perl - # Ikiwiki listpreprocessors plugin. - package IkiWiki::Plugin::listpreprocessors; - - use warnings; - use strict; - use Encode; - use IkiWiki 2.00; - - sub import { #{{{ - hook(type => "getsetup", id => "listpreprocessors", call => \&getsetup); - hook(type => "preprocess", id => "listpreprocessors", call => \&preprocess); - hook(type => "refresh", id => "listpreprocessors", call => \&refresh); - } # }}} - - sub getsetup () { #{{{ - return - plugin => { - safe => 1, - rebuild => undef, - }, - preprocessor_description_dir => { - type => "string", - description => "The ikiwiki directory that contains plugin descriptions.", - safe => 1, - rebuild => 1, - }, - preprocessor_description_autocreate => { - type => "boolean", - description => "Should pre-processor command descriptions be automatically created from a template.", - safe => 1, - rebuild => 1, - }, - } #}}} - - sub gendescription ($$) { #{{{ - my $plugin=shift; - my $page=shift; - my $file=$page.".".$config{default_pageext}; - my $template=template("preprocessor-description.tmpl"); - $template->param(page => $page, plugin => $plugin); - writefile($file, $config{srcdir}, $template->output); - if ($config{rcs}) { - IkiWiki::rcs_add($file); - } - } #}}} - - sub refresh () { #{{{ - eval q{use File::Find}; - error($@) if $@; - - if (defined $config{preprocessor_description_autocreate} && ! $config{preprocessor_description_autocreate}) { - return; # create pages unless they explicitly ask us not to - } - - if (!defined $config{preprocessor_description_dir}) { - $config{preprocessor_description_dir} = "ikiwiki/plugin/"; - } - - my @pluginlist = sort( keys %{ $IkiWiki::hooks{preprocess} } ); - my %pluginpages; - - if (@pluginlist) { - my ($plugin,$page); - - foreach $plugin (@pluginlist) { - $pluginpages{$plugin} = $config{preprocessor_description_dir} . $plugin; - } - - my %pages; - foreach my $dir ($config{srcdir}, @{$config{underlaydirs}}, $config{underlaydir}) { - find({ - no_chdir => 1, - wanted => sub { - $_=decode_utf8($_); - if (IkiWiki::file_pruned($_, $dir)) { - $File::Find::prune=1; - } - elsif (! -l $_) { - my ($f)=/$config{wiki_file_regexp}/; # untaint - return unless defined $f; - $f=~s/^\Q$dir\E\/?//; - return unless length $f; - return if $f =~ /\._([^.]+)$/; # skip internal page - if (! -d _) { - $pages{pagename($f)}=$f; - } - } - } - }, $dir); - } - - if ($config{rcs}) { - IkiWiki::disable_commit_hook(); - } - - my $needcommit = 0; - - while (($plugin,$page) = each %pluginpages) { - if (! exists $pages{$page}) { - $needcommit = 1; - gendescription($plugin,$page); - } - } - - if ($config{rcs}) { - if ($needcommit) { - IkiWiki::rcs_commit_staged( - gettext("automatic pre-processor description generation"), - undef, undef); - } - IkiWiki::enable_commit_hook(); - } - } - } #}}} - - sub preprocess (@) { #{{{ - my %params=@_; - - if (!defined $config{plugin_description_dir}) { - $config{plugin_description_dir} = "ikiwiki/plugin/"; - } - - my @pluginlist = sort( keys %{ $IkiWiki::hooks{preprocess} } ); - foreach my $plugin (@pluginlist) { - $plugin = $config{plugin_description_dir} . $plugin; - } - my $pluginString = join (' or ', @pluginlist); - - my $result = "[[!inline pages=\"$pluginString\" feeds=\"no\" show=0 sort=\"title\""; - - if (defined $params{inline}) { - $result .= ' template=\"listpreprocessors-listonly\" archive="yes"'; - } else { - $result .= ' template=\"listpreprocessors-inline\" archive="no"'; - } - - $result .= "]]"; - - return IkiWiki::preprocess($params{page}, $params{destpage}, - IkiWiki::filter($params{page}, $params{destpage}, $result)); - } # }}} - - 1 - --------- - -This is what I was using for `listpreprocessors-inline.tmpl`: - - <div class="listpreprocessorsinline"> - - <div class="inlineheader"> - - <span class="header"> - <a href="<TMPL_VAR PAGEURL>"><TMPL_VAR TITLE></a> - </span> - - </div><!--.inlineheader--> - - <div class="inlinecontent"> - <TMPL_VAR CONTENT> - </div><!--.inlinecontent--> - - </div><!--.listpreprocessorsinline--> - --------- - -This is what I was using for `listpreprocessors-listonly.tmpl`: - - <p class="listpreprocessors"><a href="<TMPL_VAR PAGEURL>"><TMPL_VAR TITLE></a></p> - --------- - -This is what I was using for `preprocessor-description.tmpl`: - - The <TMPL_VAR plugin> preprocessor command currently has no description. - - Maybe you should edit this page to add one. - -[[tag done]] +Patch is applied (along with some changes..). [[done]] (But, see +[[directive_docs]]. diff --git a/doc/todo/directive_docs.mdwn b/doc/todo/directive_docs.mdwn new file mode 100644 index 000000000..b130e3d37 --- /dev/null +++ b/doc/todo/directive_docs.mdwn @@ -0,0 +1,77 @@ +The current basewiki is not 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. + +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; + } # }}} |