765f2c622d0a54ee2bade1787056eab8b9e5d0ac
[ikiwiki.git] / 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 >>> Just to clarify, I meant adding new parameters to the same hook call
35 >>> that registers the plugin. --[[Joey]]
36
37 >>    - Adding a configuration for a wiki directory.  If a matching page is in the
38 >>      specified wiki directory then the plugin name gets turned into a link to that
39 >>      page
40 >>    - Adding configuration for an external URL.  Each plugin name is added as
41 >>       a link to the plugin name appended to the URL.
42
43 >>The first option is easier to navigate and wouldn't produce broken links,
44 >>but requires all the plugin documentation to be local.  The second option
45 >>can link back to the main IkiWiki site, but if you have any non-standard
46 >>plugins then you'll get broken links.
47 >>
48 >>Hrm.  After listing all of that, maybe your idea with the hooks is the better
49 >>solution.  I'll think about it some more. -- [[Will]]
50
51 >>> I've also run into this problem with the websetup plugin, and
52 >>> considered those ideas too. I don't like the external url, because
53 >>> ikiwiki.info may be out of sync with the version of ikiwiki being used.
54 >>> (Or maybe it's gone! :-) The first idea is fine, except for the bloat
55 >>> issue. If turning on listpreprocessors and/or websetup means adding
56 >>> hundreds of pages (and of kilobytes) to your wiki, that could be an
57 >>> incentive to not turn them on..
58 >>>
59 >>> Hmm.. maybe the thing to do is to use _internal pages for the plugins;
60 >>> then the individual pages would not be rendered, and your inlines would
61 >>> still work. Although I don't know how websetup would use it then, and
62 >>> also they would have to be non-internal for ikiwiki's own docwiki. Hmm.
63 >>> Maybe these are two different things; one is a set of pages describing
64 >>> preprocessor directives, and the second a set of pages describing
65 >>> plugins. They're so closely related though it seems a shame to keep
66 >>> them separate..
67 >>> --[[Joey]]
68
69 >>> I started implementing the hook based solution, and decided I didn't like
70 >>> it because there was no nice way to rebuild pages when the preprocessor
71 >>> descriptions changed.  So instead I assumed that the the [[plugins]] pages
72 >>> would be moved into the underlay directory.  This plugin then uses an
73 >>> `inline` directive to include those pages.  You can use the `inline`
74 >>> parameter to decide if you want to include all the descriptions or
75 >>> just the titles.  There is also an option to auto-create default/blank
76 >>> description pages if they are missing (from a template).  As preprocessor
77 >>> commands don't list unless they have a description page, auto-creation
78 >>> is enabled by default.
79 >>>
80 >>>  There are three new templates that are needed.  These are for:
81 >>>
82 >>>  - The auto-created description pages are generated from `preprocessor-description.tmpl`.
83 >>>  - When only pre-processor names are listed, the `listpreprocessors-listonly.tmpl` template is used.
84 >>>  - When pre-processor descriptions are included inline, the `listpreprocessors-inline.tmpl` template is used.
85 >>>
86 >>> -- [[Will]]
87
88 >>>> Just a quick note: pages are only created for pre-processor commands
89 >>>> that exist when the `refresh` hook is called.  This is before the [[shortcuts]] are
90 >>>> processed.  However, the list of available pre-processor commands will include
91 >>>> shortcuts if they have description pages (the list is generated later, after the
92 >>>> shortcuts have been added).  While this was unplanned, it seems a reasonable
93 >>>> tradeoff between including all the large number of shortcuts and including none. -- [[Will]]
94
95 >>>>>> I think that using an inline is elegant! However, I don't understand
96 >>>>>> why it has to create stub description pages? I doubt that, if a
97 >>>>>> directive is missing a page, the stub will be filled out in many
98 >>>>>> wikis. And it adds a lot of complexity, particularly committing a
99 >>>>>> bunch of generated pages to revision control when the user just
100 >>>>>> wants a plugin list seems undesirable.
101 >>>>>>
102 >>>>>> Seems to me it could use the inline for pages that exist, and append
103 >>>>>> to the bottom a generated text for anything that is currently missing.
104 >>>>>> The generated text could even have a page creation link in it if
105 >>>>>> you wanted.
106 >>>>>> --[[Joey]]
107
108 >>>>>>> I kinda agree about the page generation.  I don't like mixing an
109 >>>>>>> inlined and a list though.  Besides which, that ends
110 >>>>>>> up keeping much of complexity of the page generation because
111 >>>>>>> the code still has to detect which pages are missing.  I've added
112 >>>>>>> a patch that uses a list of wikilinks instead.  This way available
113 >>>>>>> pages get linked correctly, and missing pages get normal creation
114 >>>>>>> links.  The old patch is still here if you decide you prefer that. -- [[Will]]
115
116     #!/usr/bin/perl
117     # Ikiwiki listpreprocessors plugin.
118     package IkiWiki::Plugin::listpreprocessors;
119     
120     use warnings;
121     use strict;
122     use IkiWiki 2.00;
123     
124     sub import { #{{{
125         hook(type => "getsetup", id => "listpreprocessors", call => \&getsetup);
126         hook(type => "checkconfig", id => "listpreprocessors", call => \&checkconfig);
127         hook(type => "needsbuild", id => "listpreprocessors", call => \&needsbuild);
128         hook(type => "preprocess", id => "listpreprocessors", call => \&preprocess);
129     } # }}}
130     
131     sub getsetup () { #{{{
132         return
133                 plugin => {
134                         safe => 1,
135                         rebuild => undef,
136                 },
137                 preprocessor_description_dir => {
138                         type => "string",
139                         description => "The ikiwiki directory that contains plugin descriptions.",
140                         safe => 1,
141                         rebuild => 1,
142                 },
143     } #}}}
144     
145     my @fullPluginList;
146     my @earlyPluginList;
147     my $pluginString;
148     
149     sub checkconfig () { #{{{
150         if (!defined $config{plugin_description_dir}) {
151             $config{plugin_description_dir} = "ikiwiki/plugin/";
152         }
153     
154         @earlyPluginList = sort( keys %{ $IkiWiki::hooks{preprocess} } );
155     } #}}}
156     
157     sub needsbuild (@) { #{{{
158         my $needsbuild=shift;
159     
160         @fullPluginList = sort( keys %{ $IkiWiki::hooks{preprocess} } );
161         $pluginString = join (' ', @earlyPluginList) . " : ". join (' ', @fullPluginList);
162     
163         foreach my $page (keys %pagestate) {
164                 if (exists $pagestate{$page}{listpreprocessors}{shown}) {
165                         if ($pagestate{$page}{listpreprocessors}{shown} ne $pluginString) {
166                                 push @$needsbuild, $pagesources{$page};
167                         }
168                         if (exists $pagesources{$page} &&
169                                         grep { $_ eq $pagesources{$page} } @$needsbuild) {
170                                 # remove state, will be re-added if
171                                 # the [[!listpreprocessors]] is still there during the
172                                 # rebuild
173                                 delete $pagestate{$page}{listpreprocessors}{shown};
174                         }
175                 }
176         }
177     } # }}}
178     
179     sub preprocess (@) { #{{{
180         my %params=@_;
181         
182         $pagestate{$params{destpage}}{listpreprocessors}{shown}=$pluginString;
183         
184         my @pluginlist;
185         
186         if (! defined $params{generated}) {
187                 @pluginlist = @fullPluginList;
188         } else {
189                 @pluginlist = @earlyPluginList;
190         }
191         
192         my $result = '<ul class="listpreprocessors">';
193         
194         foreach my $plugin (@pluginlist) {
195                 $result .= '<li class="listpreprocessors">[[' . $config{plugin_description_dir} . $plugin . ']]</li>';
196         }
197         
198         $result .= "</ul>";
199         
200         return IkiWiki::preprocess($params{page}, $params{destpage}, 
201                 IkiWiki::filter($params{page}, $params{destpage}, $result));
202     } # }}}
203     
204     1
205
206 ----
207
208 Here is the main listpreprocessors plugin. (Note, because this has double
209 square brackets in the source, it isn't quite displaying correctly - look
210 at the page source for details.)  New template files follow:
211
212     #!/usr/bin/perl
213     # Ikiwiki listpreprocessors plugin.
214     package IkiWiki::Plugin::listpreprocessors;
215     
216     use warnings;
217     use strict;
218     use Encode;
219     use IkiWiki 2.00;
220     
221     sub import { #{{{
222         hook(type => "getsetup", id => "listpreprocessors", call => \&getsetup);
223         hook(type => "preprocess", id => "listpreprocessors", call => \&preprocess);
224         hook(type => "refresh", id => "listpreprocessors", call => \&refresh);
225     } # }}}
226     
227     sub getsetup () { #{{{
228         return
229                 plugin => {
230                         safe => 1,
231                         rebuild => undef,
232                 },
233                 preprocessor_description_dir => {
234                         type => "string",
235                         description => "The ikiwiki directory that contains plugin descriptions.",
236                         safe => 1,
237                         rebuild => 1,
238                 },
239                 preprocessor_description_autocreate => {
240                         type => "boolean",
241                         description => "Should pre-processor command descriptions be automatically created from a template.",
242                         safe => 1,
243                         rebuild => 1,
244                 },
245     } #}}}
246     
247     sub gendescription ($$) { #{{{
248         my $plugin=shift;
249         my $page=shift;
250         my $file=$page.".".$config{default_pageext};
251         my $template=template("preprocessor-description.tmpl");
252         $template->param(page => $page, plugin => $plugin);
253         writefile($file, $config{srcdir}, $template->output);
254         if ($config{rcs}) {
255                 IkiWiki::rcs_add($file);
256         }
257     } #}}}
258     
259     sub refresh () { #{{{
260         eval q{use File::Find};
261         error($@) if $@;
262     
263         if (defined $config{preprocessor_description_autocreate} && ! $config{preprocessor_description_autocreate}) {
264                 return; # create pages unless they explicitly ask us not to
265         }
266     
267         if (!defined $config{preprocessor_description_dir}) {
268                 $config{preprocessor_description_dir} = "ikiwiki/plugin/";
269         }
270         
271         my @pluginlist = sort( keys %{ $IkiWiki::hooks{preprocess} } );
272         my %pluginpages;
273     
274         if (@pluginlist) {
275                 my ($plugin,$page);
276                 
277                 foreach $plugin (@pluginlist) {
278                         $pluginpages{$plugin} = $config{preprocessor_description_dir} . $plugin;
279                 }
280     
281                 my %pages;
282                 foreach my $dir ($config{srcdir}, @{$config{underlaydirs}}, $config{underlaydir}) {
283                         find({
284                                 no_chdir => 1,
285                                 wanted => sub {
286                                         $_=decode_utf8($_);
287                                         if (IkiWiki::file_pruned($_, $dir)) {
288                                                 $File::Find::prune=1;
289                                         }
290                                         elsif (! -l $_) {
291                                                 my ($f)=/$config{wiki_file_regexp}/; # untaint
292                                                 return unless defined $f;
293                                                 $f=~s/^\Q$dir\E\/?//;
294                                                 return unless length $f;
295                                                 return if $f =~ /\._([^.]+)$/; # skip internal page
296                                                 if (! -d _) {
297                                                         $pages{pagename($f)}=$f;
298                                                 }
299                                         }
300                                 }
301                         }, $dir);
302                 }
303     
304                 if ($config{rcs}) {
305                         IkiWiki::disable_commit_hook();
306                 }
307                 
308                 my $needcommit = 0;
309                 
310                 while (($plugin,$page) = each %pluginpages) {
311                         if (! exists $pages{$page}) {
312                                 $needcommit = 1;
313                                 gendescription($plugin,$page);
314                         }
315                 }
316                 
317                 if ($config{rcs}) {
318                         if ($needcommit) {
319                                 IkiWiki::rcs_commit_staged(
320                                         gettext("automatic pre-processor description generation"),
321                                         undef, undef);
322                         }
323                         IkiWiki::enable_commit_hook();
324                 }
325         }
326     } #}}}
327     
328     sub preprocess (@) { #{{{
329         my %params=@_;
330         
331         if (!defined $config{plugin_description_dir}) {
332                 $config{plugin_description_dir} = "ikiwiki/plugin/";
333         }
334         
335         my @pluginlist = sort( keys %{ $IkiWiki::hooks{preprocess} } );
336         foreach my $plugin (@pluginlist) {
337                 $plugin = $config{plugin_description_dir} . $plugin;
338         }
339         my $pluginString = join (' or ', @pluginlist);
340         
341         my $result = "[[!inline pages=\"$pluginString\" feeds=\"no\" show=0 sort=\"title\"";
342         
343         if (defined $params{inline}) {
344                 $result .= ' template=\"listpreprocessors-listonly\" archive="yes"';
345         } else {
346                 $result .= ' template=\"listpreprocessors-inline\" archive="no"';
347         }
348         
349         $result .= "]]";
350         
351         return IkiWiki::preprocess($params{page}, $params{destpage}, 
352                 IkiWiki::filter($params{page}, $params{destpage}, $result));
353     } # }}}
354     
355     1
356
357 --------
358
359 This is what I was using for `listpreprocessors-inline.tmpl`:
360
361     <div class="listpreprocessorsinline">
362     
363     <div class="inlineheader">
364     
365     <span class="header">
366     <a href="<TMPL_VAR PAGEURL>"><TMPL_VAR TITLE></a>
367     </span>
368     
369     </div><!--.inlineheader-->
370     
371     <div class="inlinecontent">
372     <TMPL_VAR CONTENT>
373     </div><!--.inlinecontent-->
374     
375     </div><!--.listpreprocessorsinline-->
376
377 --------
378
379 This is what I was using for `listpreprocessors-listonly.tmpl`:
380
381     <p class="listpreprocessors"><a href="<TMPL_VAR PAGEURL>"><TMPL_VAR TITLE></a></p>
382
383 --------
384
385 This is what I was using for `preprocessor-description.tmpl`:
386
387     The <TMPL_VAR plugin> preprocessor command currently has no description.
388     
389     Maybe you should edit this page to add one.