doc/todo/Add_a_plugin_to_list_available_pre-processor_commands.mdwn

   1 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]]
   2
   3 > Good idea, I do see a few problems:
   4 >
   5 > - preprocessor directives do not necessarily have the same name as the
   6 >   plugin that contains them (for example, the graphviz plugin adds a graph
   7 >   directive). Won't keys `%{IkiWiki::hooks{preprocess}}` work?
   8
   9 >>> Er, yeah - that's a much better solution. :) -- and done
  10
  11 > - "listplugins" is a bit misnamed since it only does preprocessor directives.
  12
  13 >>> Yes.  Initially this was going to list all enabled plugins.  Then when searching
  14 >>> for enabled plugins I changed my mind and decided that a list of pre-processor
  15 >>> directives was more useful.  I'll fix that too. -- changed to `listpreprocessors`
  16
  17 > - comment was copied from version plugin and still mentions version :-)
  18
  19 >>> :-) -- fixed
  20
  21 > - Seems like [[ikiwiki/formatting]] could benefit from including the
  22 >   list.. however, just a list of preprocessor directive names is not
  23 >   the most user-friendly thing that could be put on that page. It would
  24 >   be nice if there were also a short description and maybe an example of
  25 >   use. Seems like the place to include that info would be in the call
  26 >   to `hook()`.
  27 >   (Maybe adding that is more involved than you want to go though..)
  28 >
  29 > --[[Joey]]
  30
  31 >> Adding a whole new hook for a usage example is more effort than I
  32 >> wanted to go to.  I was thinking of either:
  33 >>
  34 >>    - Adding a configuration for a wiki directory.  If a matching page is in the
  35 >>      specified wiki directory then the plugin name gets turned into a link to that
  36 >>      page
  37 >>    - Adding configuration for an external URL.  Each plugin name is added as
  38 >>       a link to the plugin name appended to the URL.
  39
  40 >>The first option is easier to navigate and wouldn't produce broken links,
  41 >>but requires all the plugin documentation to be local.  The second option
  42 >>can link back to the main IkiWiki site, but if you have any non-standard
  43 >>plugins then you'll get broken links.
  44 >>
  45 >>Hrm.  After listing all of that, maybe your idea with the hooks is the better
  46 >>solution.  I'll think about it some more. -- [[Will]]
  47
  48 >>> I started implementing the hook based solution, and decided I didn't like
  49 >>> it because there was no nice way to rebuild pages when the preprocessor
  50 >>> descriptions changed.  So instead I assumed that the the [[plugins]] pages
  51 >>> would be moved into the underlay directory.  This plugin then uses an
  52 >>> `inline` directive to include those pages.  You can use the `inline`
  53 >>> parameter to decide if you want to include all the descriptions or
  54 >>> just the titles.  There is also an option to auto-create default/blank
  55 >>> description pages if they are missing (from a template).  As preprocessor
  56 >>> commands don't list unless they have a description page, auto-creation
  57 >>> is enabled by default.
  58 >>>
  59 >>>  There are three new templates that are needed.  These are for:
  60 >>>
  61 >>>  - The auto-created description pages are generated from `preprocessor-description.tmpl`.
  62 >>>  - When only pre-processor names are listed, the `listpreprocessors-listonly.tmpl` template is used.
  63 >>>  - When pre-processor descriptions are included inline, the `listpreprocessors-inline.tmpl` template is used.
  64 >>>
  65 >>> -- [[Will]]
  66
  67 >>>> Just a quick note: pages are only created for pre-processor commands
  68 >>>> that exist when the `refresh` hook is called.  This is before the [[shortcuts]] are
  69 >>>> processed.  However, the list of available pre-processor commands will include
  70 >>>> shortcuts if they have description pages (the list is generated later, after the
  71 >>>> shortcuts have been added).  While this was unplanned, it seems a reasonable
  72 >>>> tradeoff between including all the large number of shortcuts and including none. -- [[Will]]
  73
  74 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:
  75
  76     #!/usr/bin/perl
  77     # Ikiwiki listpreprocessors plugin.
  78     package IkiWiki::Plugin::listpreprocessors;
  79
  80     use warnings;
  81     use strict;
  82     use Encode;
  83     use IkiWiki 2.00;
  84
  85     sub import { #{{{
  86         hook(type => "getsetup", id => "listpreprocessors", call => \&getsetup);
  87         hook(type => "preprocess", id => "listpreprocessors", call => \&preprocess);
  88         hook(type => "refresh", id => "listpreprocessors", call => \&refresh);
  89     } # }}}
  90
  91     sub getsetup () { #{{{
  92         return
  93                 plugin => {
  94                         safe => 1,
  95                         rebuild => undef,
  96                 },
  97                 preprocessor_description_dir => {
  98                         type => "string",
  99                         description => "The ikiwiki directory that contains plugin descriptions.",
 100                         safe => 1,
 101                         rebuild => 1,
 102                 },
 103                 preprocessor_description_autocreate => {
 104                         type => "boolean",
 105                         description => "Should pre-processor command descriptions be automatically created from a template.",
 106                         safe => 1,
 107                         rebuild => 1,
 108                 },
 109     } #}}}
 110
 111     sub gendescription ($$) { #{{{
 112         my $plugin=shift;
 113         my $page=shift;
 114         my $file=$page.".".$config{default_pageext};
 115         my $template=template("preprocessor-description.tmpl");
 116         $template->param(page => $page, plugin => $plugin);
 117         writefile($file, $config{srcdir}, $template->output);
 118         if ($config{rcs}) {
 119                 IkiWiki::rcs_add($file);
 120         }
 121     } #}}}
 122
 123     sub refresh () { #{{{
 124         eval q{use File::Find};
 125         error($@) if $@;
 126
 127         if (defined $config{preprocessor_description_autocreate} && ! $config{preprocessor_description_autocreate}) {
 128                 return; # create pages unless they explicitly ask us not to
 129         }
 130
 131         if (!defined $config{preprocessor_description_dir}) {
 132                 $config{preprocessor_description_dir} = "ikiwiki/plugin/";
 133         }
 134
 135         my @pluginlist = sort( keys %{ $IkiWiki::hooks{preprocess} } );
 136         my %pluginpages;
 137
 138         if (@pluginlist) {
 139                 my ($plugin,$page);
 140
 141                 foreach $plugin (@pluginlist) {
 142                         $pluginpages{$plugin} = $config{preprocessor_description_dir} . $plugin;
 143                 }
 144
 145                 my %pages;
 146                 foreach my $dir ($config{srcdir}, @{$config{underlaydirs}}, $config{underlaydir}) {
 147                         find({
 148                                 no_chdir => 1,
 149                                 wanted => sub {
 150                                         $_=decode_utf8($_);
 151                                         if (IkiWiki::file_pruned($_, $dir)) {
 152                                                 $File::Find::prune=1;
 153                                         }
 154                                         elsif (! -l $_) {
 155                                                 my ($f)=/$config{wiki_file_regexp}/; # untaint
 156                                                 return unless defined $f;
 157                                                 $f=~s/^\Q$dir\E\/?//;
 158                                                 return unless length $f;
 159                                                 return if $f =~ /\._([^.]+)$/; # skip internal page
 160                                                 if (! -d _) {
 161                                                         $pages{pagename($f)}=$f;
 162                                                 }
 163                                         }
 164                                 }
 165                         }, $dir);
 166                 }
 167
 168                 if ($config{rcs}) {
 169                         IkiWiki::disable_commit_hook();
 170                 }
 171
 172                 my $needcommit = 0;
 173
 174                 while (($plugin,$page) = each %pluginpages) {
 175                         if (! exists $pages{$page}) {
 176                                 $needcommit = 1;
 177                                 gendescription($plugin,$page);
 178                         }
 179                 }
 180
 181                 if ($config{rcs}) {
 182                         if ($needcommit) {
 183                                 IkiWiki::rcs_commit_staged(
 184                                         gettext("automatic pre-processor description generation"),
 185                                         undef, undef);
 186                         }
 187                         IkiWiki::enable_commit_hook();
 188                 }
 189         }
 190     } #}}}
 191
 192     sub preprocess (@) { #{{{
 193         my %params=@_;
 194
 195         if (!defined $config{plugin_description_dir}) {
 196                 $config{plugin_description_dir} = "ikiwiki/plugin/";
 197         }
 198
 199         my @pluginlist = sort( keys %{ $IkiWiki::hooks{preprocess} } );
 200         foreach my $plugin (@pluginlist) {
 201                 $plugin = $config{plugin_description_dir} . $plugin;
 202         }
 203         my $pluginString = join (' or ', @pluginlist);
 204
 205         my $result = "[[!inline pages=\"$pluginString\" feeds=\"no\" show=0 sort=\"title\"";
 206
 207         if (defined $params{inline}) {
 208                 $result .= ' template=\"listpreprocessors-listonly\" archive="yes"';
 209         } else {
 210                 $result .= ' template=\"listpreprocessors-inline\" archive="no"';
 211         }
 212
 213         $result .= "]]";
 214
 215         return IkiWiki::preprocess($params{page}, $params{destpage},
 216                 IkiWiki::filter($params{page}, $params{destpage}, $result));
 217     } # }}}
 218
 219     1
 220
 221 --------
 222
 223 This is what I was using for `listpreprocessors-inline.tmpl`:
 224
 225     <div class="listpreprocessorsinline">
 226
 227     <div class="inlineheader">
 228
 229     <span class="header">
 230     <a href="<TMPL_VAR PAGEURL>"><TMPL_VAR TITLE></a>
 231     </span>
 232
 233     </div><!--.inlineheader-->
 234
 235     <div class="inlinecontent">
 236     <TMPL_VAR CONTENT>
 237     </div><!--.inlinecontent-->
 238
 239     </div><!--.listpreprocessorsinline-->
 240
 241 --------
 242
 243 This is what I was using for `listpreprocessors-listonly.tmpl`:
 244
 245     <p class="listpreprocessors"><a href="<TMPL_VAR PAGEURL>"><TMPL_VAR TITLE></a></p>
 246
 247 --------
 248
 249 This is what I was using for `preprocessor-description.tmpl`:
 250
 251     The <TMPL_VAR plugin> preprocessor command currently has no description.
 252
 253     Maybe you should edit this page to add one.