ikiwiki/doc/todo/Add_a_plugin_to_list_available_pre-processor_commands.mdwn

I've found myself wanting to know which [[plugins]] are switched on so I know which pre-processor commands I can use.  The attached [[patch]] adds a new plugin that generates the list of available plugins. -- [[Will]]

> Good idea, I do see a few problems:
> 
> - preprocessor directives do not necessarily have the same name as the
>   plugin that contains them (for example, the graphviz plugin adds a graph
>   directive). Won't keys `%{IkiWiki::hooks{preprocess}}` work?

>>> Er, yeah - that's a much better solution. :)

> - "listplugins" is a bit misnamed since it only does preprocessor directives.

>>> Yes.  Initially this was going to list all enabled plugins.  Then when searching
>>> for enabled plugins I changed my mind and decided that a list of pre-processor
>>> directives was more useful.  I'll fix that too.

> - comment was copied from version plugin and still mentions version :-)

>>> :-)

> - Seems like [[ikiwiki/formatting]] could benefit from including the
>   list.. however, just a list of preprocessor directive names is not
>   the most user-friendly thing that could be put on that page. It would
>   be nice if there were also a short description and maybe an example of
>   use. Seems like the place to include that info would be in the call
>   to `hook()`.
>   (Maybe adding that is more involved than you want to go though..)
> 
> --[[Joey]]

>> Adding a whole new hook for a usage example is more effort than I
>> wanted to go to.  I was thinking of either:
>>
>>    - Adding a configuration for a wiki directory.  If a matching page is in the
>>      specified wiki directory then the plugin name gets turned into a link to that
>>      page
>>    - Adding configuration for an external URL.  Each plugin name is added as
>>       a link to the plugin name appended to the URL.

>>The first option is easier to navigate and wouldn't produce broken links,
>>but requires all the plugin documentation to be local.  The second option
>>can link back to the main IkiWiki site, but if you have any non-standard
>>plugins then you'll get broken links.
>>
>>Hrm.  After listing all of that, maybe your idea with the hooks is the better
>>solution.  I'll think about it some more. -- [[Will]]

    #!/usr/bin/perl
    # Ikiwiki listplugins plugin.
    package IkiWiki::Plugin::listplugins;
    
    use warnings;
    use strict;
    use IkiWiki 2.00;
    
    sub import { #{{{
    	hook(type => "getsetup", id => "listplugins", call => \&getsetup);
    	hook(type => "needsbuild", id => "listplugins", call => \&needsbuild);
    	hook(type => "preprocess", id => "listplugins", call => \&preprocess);
    } # }}}
    
    sub getsetup () { #{{{
    	return
    		plugin => {
    			safe => 1,
    			rebuild => undef,
    		},
    } #}}}
    
    my @pluginlist;
    my $pluginString;
    
    sub needsbuild (@) { #{{{
    	my $needsbuild=shift;
    
    	my @rawpluginlist = sort(IkiWiki::listplugins());
    	@pluginlist = ();
    	
    	foreach my $plugin (@rawpluginlist) {
    		if ( exists $IkiWiki::hooks{preprocess}{$plugin} ) {
    			push(@pluginlist,$plugin);
    		}
    	}
    
    	$pluginString = join (' ', @pluginlist);
    
    	foreach my $page (keys %pagestate) {
    		if (exists $pagestate{$page}{listplugins}{shown}) {
    			if ($pagestate{$page}{listplugins}{shown} ne $pluginString) {
    				push @$needsbuild, $pagesources{$page};
    			}
    			if (exists $pagesources{$page} &&
    			    grep { $_ eq $pagesources{$page} } @$needsbuild) {
    				# remove state, will be re-added if
    				# the version is still shown during the
    				# rebuild
    				delete $pagestate{$page}{listplugins}{shown};
    			}
    		}
    	}
    } # }}}
    
    sub preprocess (@) { #{{{
    	my %params=@_;
    	
    	$pagestate{$params{destpage}}{listplugins}{shown}=$pluginString;
    	
    	my $result = "<ul class=\"pluginlist\">";
    	my $thisPlugin;
    	foreach $thisPlugin (@pluginlist) {
    		$result .= "<li class=\"pluginlist\">$thisPlugin</li>";
    	}
    	$result .= "</ul>";
    	
    	return $result;
    } # }}}
    
    1