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]]
3 > Good idea, I do see a few problems:
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?
9 >>> Er, yeah - that's a much better solution. :) -- and done
11 > - "listplugins" is a bit misnamed since it only does preprocessor directives.
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`
17 > - comment was copied from version plugin and still mentions version :-)
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
27 > (Maybe adding that is more involved than you want to go though..)
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:
34 >>> Just to clarify, I meant adding new parameters to the same hook call
35 >>> that registers the plugin. --[[Joey]]
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
40 >> - Adding configuration for an external URL. Each plugin name is added as
41 >> a link to the plugin name appended to the URL.
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.
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]]
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..
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
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.
80 >>> There are three new templates that are needed. These are for:
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.
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]]
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.
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
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]]
116 >>>>>>>> Can you explain the full/early list (why track both?) and generated parameter?
118 >>>>>>>>> If you add in all the shortcuts you get quite a long list. My original idea
119 >>>>>>>>> was to just track the plugin commands. This is the early list. But then
120 >>>>>>>>> I thought that it might be nice for someone looking at wiki source and
121 >>>>>>>>> seeing a shortcut to know where it came from. So I decided to make
122 >>>>>>>>> displaying the full list an option, with the original concept as the default.
124 >>>>>>>>> Another option here might be to generate the full list every time, but give
125 >>>>>>>>> generated pre-processor commands (e.g. shortcuts) a different css class.
126 >>>>>>>>> I'm not sure that is better than what I have though.
128 >>>>>>>>> I keep track of both in the page state because if a command moves from
129 >>>>>>>>> a shortcut to the early list (or vice versa) it changes what should be
130 >>>>>>>>> displayed in the default use of the plugin. I thought about tracking just what
131 >>>>>>>>> was actually used on the page, but I don't know in the needsbuild hook whether the `generated`
132 >>>>>>>>> parameter has been supplied (or maybe the plugin is used twice on the page -
133 >>>>>>>>> once in each form). It was just easier to track both.
135 >>>>>>>> Only code change I'd suggest is using `htmllink` rather than
136 >>>>>>>> generating a wikilink.
138 >>>>>>>>> Yeah - that would make sense. Will do. -- [[Will]]
141 # Ikiwiki listpreprocessors plugin.
142 package IkiWiki::Plugin::listpreprocessors;
149 hook(type => "getsetup", id => "listpreprocessors", call => \&getsetup);
150 hook(type => "checkconfig", id => "listpreprocessors", call => \&checkconfig);
151 hook(type => "needsbuild", id => "listpreprocessors", call => \&needsbuild);
152 hook(type => "preprocess", id => "listpreprocessors", call => \&preprocess);
155 sub getsetup () { #{{{
161 preprocessor_description_dir => {
163 description => "The ikiwiki directory that contains plugin descriptions.",
173 sub checkconfig () { #{{{
174 if (!defined $config{plugin_description_dir}) {
175 $config{plugin_description_dir} = "ikiwiki/plugin/";
178 @earlyPluginList = sort( keys %{ $IkiWiki::hooks{preprocess} } );
181 sub needsbuild (@) { #{{{
182 my $needsbuild=shift;
184 @fullPluginList = sort( keys %{ $IkiWiki::hooks{preprocess} } );
185 $pluginString = join (' ', @earlyPluginList) . " : ". join (' ', @fullPluginList);
187 foreach my $page (keys %pagestate) {
188 if (exists $pagestate{$page}{listpreprocessors}{shown}) {
189 if ($pagestate{$page}{listpreprocessors}{shown} ne $pluginString) {
190 push @$needsbuild, $pagesources{$page};
192 if (exists $pagesources{$page} &&
193 grep { $_ eq $pagesources{$page} } @$needsbuild) {
194 # remove state, will be re-added if
195 # the [[!listpreprocessors]] is still there during the
197 delete $pagestate{$page}{listpreprocessors}{shown};
203 sub preprocess (@) { #{{{
206 $pagestate{$params{destpage}}{listpreprocessors}{shown}=$pluginString;
210 if (! defined $params{generated}) {
211 @pluginlist = @fullPluginList;
213 @pluginlist = @earlyPluginList;
216 my $result = '<ul class="listpreprocessors">';
218 foreach my $plugin (@pluginlist) {
219 $result .= '<li class="listpreprocessors">[[' . $config{plugin_description_dir} . $plugin . ']]</li>';
224 return IkiWiki::preprocess($params{page}, $params{destpage},
225 IkiWiki::filter($params{page}, $params{destpage}, $result));
232 Here is the main listpreprocessors plugin. (Note, because this has double
233 square brackets in the source, it isn't quite displaying correctly - look
234 at the page source for details.) New template files follow:
237 # Ikiwiki listpreprocessors plugin.
238 package IkiWiki::Plugin::listpreprocessors;
246 hook(type => "getsetup", id => "listpreprocessors", call => \&getsetup);
247 hook(type => "preprocess", id => "listpreprocessors", call => \&preprocess);
248 hook(type => "refresh", id => "listpreprocessors", call => \&refresh);
251 sub getsetup () { #{{{
257 preprocessor_description_dir => {
259 description => "The ikiwiki directory that contains plugin descriptions.",
263 preprocessor_description_autocreate => {
265 description => "Should pre-processor command descriptions be automatically created from a template.",
271 sub gendescription ($$) { #{{{
274 my $file=$page.".".$config{default_pageext};
275 my $template=template("preprocessor-description.tmpl");
276 $template->param(page => $page, plugin => $plugin);
277 writefile($file, $config{srcdir}, $template->output);
279 IkiWiki::rcs_add($file);
283 sub refresh () { #{{{
284 eval q{use File::Find};
287 if (defined $config{preprocessor_description_autocreate} && ! $config{preprocessor_description_autocreate}) {
288 return; # create pages unless they explicitly ask us not to
291 if (!defined $config{preprocessor_description_dir}) {
292 $config{preprocessor_description_dir} = "ikiwiki/plugin/";
295 my @pluginlist = sort( keys %{ $IkiWiki::hooks{preprocess} } );
301 foreach $plugin (@pluginlist) {
302 $pluginpages{$plugin} = $config{preprocessor_description_dir} . $plugin;
306 foreach my $dir ($config{srcdir}, @{$config{underlaydirs}}, $config{underlaydir}) {
311 if (IkiWiki::file_pruned($_, $dir)) {
312 $File::Find::prune=1;
315 my ($f)=/$config{wiki_file_regexp}/; # untaint
316 return unless defined $f;
317 $f=~s/^\Q$dir\E\/?//;
318 return unless length $f;
319 return if $f =~ /\._([^.]+)$/; # skip internal page
321 $pages{pagename($f)}=$f;
329 IkiWiki::disable_commit_hook();
334 while (($plugin,$page) = each %pluginpages) {
335 if (! exists $pages{$page}) {
337 gendescription($plugin,$page);
343 IkiWiki::rcs_commit_staged(
344 gettext("automatic pre-processor description generation"),
347 IkiWiki::enable_commit_hook();
352 sub preprocess (@) { #{{{
355 if (!defined $config{plugin_description_dir}) {
356 $config{plugin_description_dir} = "ikiwiki/plugin/";
359 my @pluginlist = sort( keys %{ $IkiWiki::hooks{preprocess} } );
360 foreach my $plugin (@pluginlist) {
361 $plugin = $config{plugin_description_dir} . $plugin;
363 my $pluginString = join (' or ', @pluginlist);
365 my $result = "[[!inline pages=\"$pluginString\" feeds=\"no\" show=0 sort=\"title\"";
367 if (defined $params{inline}) {
368 $result .= ' template=\"listpreprocessors-listonly\" archive="yes"';
370 $result .= ' template=\"listpreprocessors-inline\" archive="no"';
375 return IkiWiki::preprocess($params{page}, $params{destpage},
376 IkiWiki::filter($params{page}, $params{destpage}, $result));
383 This is what I was using for `listpreprocessors-inline.tmpl`:
385 <div class="listpreprocessorsinline">
387 <div class="inlineheader">
389 <span class="header">
390 <a href="<TMPL_VAR PAGEURL>"><TMPL_VAR TITLE></a>
393 </div><!--.inlineheader-->
395 <div class="inlinecontent">
397 </div><!--.inlinecontent-->
399 </div><!--.listpreprocessorsinline-->
403 This is what I was using for `listpreprocessors-listonly.tmpl`:
405 <p class="listpreprocessors"><a href="<TMPL_VAR PAGEURL>"><TMPL_VAR TITLE></a></p>
409 This is what I was using for `preprocessor-description.tmpl`:
411 The <TMPL_VAR plugin> preprocessor command currently has no description.
413 Maybe you should edit this page to add one.