X-Git-Url: https://sipb.mit.edu/gitweb.cgi/ikiwiki.git/blobdiff_plain/2c0a45ba7a9867330ebcd4aa97d4ec946f0e4729..2e421c7610ee581a7344b93b48d27d8d34716b51:/doc/todo/Add_a_plugin_to_list_available_pre-processor_commands.mdwn
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 3ba0202a0..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
@@ -30,7 +30,10 @@ I've found myself wanting to know which [[plugins]] are switched on so I know wh
>> Adding a whole new hook for a usage example is more effort than I
>> wanted to go to. I was thinking of either:
->>
+
+>>> Just to clarify, I meant adding new parameters to the same hook call
+>>> that registers the plugin. --[[Joey]]
+
>> - 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
@@ -45,6 +48,24 @@ I've found myself wanting to know which [[plugins]] are switched on so I know wh
>>Hrm. After listing all of that, maybe your idea with the hooks is the better
>>solution. I'll think about it some more. -- [[Will]]
+>>> I've also run into this problem with the websetup plugin, and
+>>> considered those ideas too. I don't like the external url, because
+>>> ikiwiki.info may be out of sync with the version of ikiwiki being used.
+>>> (Or maybe it's gone! :-) The first idea is fine, except for the bloat
+>>> issue. If turning on listpreprocessors and/or websetup means adding
+>>> hundreds of pages (and of kilobytes) to your wiki, that could be an
+>>> incentive to not turn them on..
+>>>
+>>> Hmm.. maybe the thing to do is to use _internal pages for the plugins;
+>>> then the individual pages would not be rendered, and your inlines would
+>>> still work. Although I don't know how websetup would use it then, and
+>>> also they would have to be non-internal for ikiwiki's own docwiki. Hmm.
+>>> Maybe these are two different things; one is a set of pages describing
+>>> preprocessor directives, and the second a set of pages describing
+>>> plugins. They're so closely related though it seems a shame to keep
+>>> them separate..
+>>> --[[Joey]]
+
>>> I started implementing the hook based solution, and decided I didn't like
>>> it because there was no nice way to rebuild pages when the preprocessor
>>> descriptions changed. So instead I assumed that the the [[plugins]] pages
@@ -64,150 +85,57 @@ I've found myself wanting to know which [[plugins]] are switched on so I know wh
>>>
>>> -- [[Will]]
-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 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 () { #{{{
-
- 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;
- }
-
- if ($config{rcs}) {
- IkiWiki::disable_commit_hook();
- }
-
- while (($plugin,$page) = each %pluginpages) {
- gendescription($plugin,$page);
- }
-
- if ($config{rcs}) {
- 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`:
-
-
-
---------
-
-This is what I was using for `listpreprocessors-listonly.tmpl`:
-
-
-
---------
-
-This is what I was using for `preprocessor-description.tmpl`:
-
- The preprocessor command currently has no description.
-
- Maybe you should edit this page to add one.
+>>>> Just a quick note: pages are only created for pre-processor commands
+>>>> that exist when the `refresh` hook is called. This is before the [[shortcuts]] are
+>>>> processed. However, the list of available pre-processor commands will include
+>>>> shortcuts if they have description pages (the list is generated later, after the
+>>>> shortcuts have been added). While this was unplanned, it seems a reasonable
+>>>> tradeoff between including all the large number of shortcuts and including none. -- [[Will]]
+
+>>>>>> I think that using an inline is elegant! However, I don't understand
+>>>>>> why it has to create stub description pages? I doubt that, if a
+>>>>>> directive is missing a page, the stub will be filled out in many
+>>>>>> wikis. And it adds a lot of complexity, particularly committing a
+>>>>>> bunch of generated pages to revision control when the user just
+>>>>>> wants a plugin list seems undesirable.
+>>>>>>
+>>>>>> Seems to me it could use the inline for pages that exist, and append
+>>>>>> to the bottom a generated text for anything that is currently missing.
+>>>>>> The generated text could even have a page creation link in it if
+>>>>>> you wanted.
+>>>>>> --[[Joey]]
+
+>>>>>>> I kinda agree about the page generation. I don't like mixing an
+>>>>>>> inlined and a list though. Besides which, that ends
+>>>>>>> up keeping much of complexity of the page generation because
+>>>>>>> the code still has to detect which pages are missing. I've added
+>>>>>>> a patch that uses a list of wikilinks instead. This way available
+>>>>>>> pages get linked correctly, and missing pages get normal creation
+>>>>>>> links. The old patch is still here if you decide you prefer that. -- [[Will]]
+
+>>>>>>>> Can you explain the full/early list (why track both?) and generated parameter?
+
+>>>>>>>>> If you add in all the shortcuts you get quite a long list. My original idea
+>>>>>>>>> was to just track the plugin commands. This is the early list. But then
+>>>>>>>>> I thought that it might be nice for someone looking at wiki source and
+>>>>>>>>> seeing a shortcut to know where it came from. So I decided to make
+>>>>>>>>> displaying the full list an option, with the original concept as the default.
+
+>>>>>>>>> Another option here might be to generate the full list every time, but give
+>>>>>>>>> generated pre-processor commands (e.g. shortcuts) a different css class.
+>>>>>>>>> I'm not sure that is better than what I have though.
+
+>>>>>>>>> I keep track of both in the page state because if a command moves from
+>>>>>>>>> a shortcut to the early list (or vice versa) it changes what should be
+>>>>>>>>> displayed in the default use of the plugin. I thought about tracking just what
+>>>>>>>>> was actually used on the page, but I don't know in the needsbuild hook whether the `generated`
+>>>>>>>>> parameter has been supplied (or maybe the plugin is used twice on the page -
+>>>>>>>>> once in each form). It was just easier to track both.
+
+>>>>>>>> Only code change I'd suggest is using `htmllink` rather than
+>>>>>>>> generating a wikilink.
+
+>>>>>>>>> Yeah - that would make sense. done. -- [[Will]]
+
+Patch is applied (along with some changes..). [[done]] (But, see
+[[directive_docs]].