mark down, open new todo
authorJoey Hess <joey@kodama.kitenet.net>
Mon, 25 Aug 2008 20:15:31 +0000 (16:15 -0400)
committerJoey Hess <joey@kodama.kitenet.net>
Mon, 25 Aug 2008 20:15:31 +0000 (16:15 -0400)
doc/todo/Add_a_plugin_to_list_available_pre-processor_commands.mdwn
doc/todo/directive_docs.mdwn [new file with mode: 0644]

index b8ef2409de4e3a156995cb1c733b943c68fe0646..9ac400cd24d077b6809aa4319218689e45406dec 100644 (file)
@@ -137,280 +137,5 @@ I've found myself wanting to know which [[plugins]] are switched on so I know wh
 
 >>>>>>>>> Yeah - that would make sense.  done. -- [[Will]]
 
-    #!/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 => "checkconfig", id => "listpreprocessors", call => \&checkconfig);
-       hook(type => "needsbuild", id => "listpreprocessors", call => \&needsbuild);
-       hook(type => "preprocess", id => "listpreprocessors", call => \&preprocess);
-    } # }}}
-    
-    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,
-               },
-    } #}}}
-    
-    my @fullPluginList;
-    my @earlyPluginList;
-    my $pluginString;
-    
-    sub checkconfig () { #{{{
-        if (!defined $config{plugin_description_dir}) {
-            $config{plugin_description_dir} = "ikiwiki/plugin/";
-        }
-    
-        @earlyPluginList = sort( keys %{ $IkiWiki::hooks{preprocess} } );
-    } #}}}
-    
-    sub needsbuild (@) { #{{{
-       my $needsbuild=shift;
-    
-       @fullPluginList = sort( keys %{ $IkiWiki::hooks{preprocess} } );
-       $pluginString = join (' ', @earlyPluginList) . " : ". join (' ', @fullPluginList);
-    
-       foreach my $page (keys %pagestate) {
-               if (exists $pagestate{$page}{listpreprocessors}{shown}) {
-                       if ($pagestate{$page}{listpreprocessors}{shown} ne $pluginString) {
-                               push @$needsbuild, $pagesources{$page};
-                       }
-                       if (exists $pagesources{$page} &&
-                                       grep { $_ eq $pagesources{$page} } @$needsbuild) {
-                               # remove state, will be re-added if
-                               # the [[!listpreprocessors]] is still there during the
-                               # rebuild
-                               delete $pagestate{$page}{listpreprocessors}{shown};
-                       }
-               }
-       }
-    } # }}}
-    
-    sub preprocess (@) { #{{{
-       my %params=@_;
-       
-       $pagestate{$params{destpage}}{listpreprocessors}{shown}=$pluginString;
-       
-       my @pluginlist;
-       
-       if (defined $params{generated}) {
-               @pluginlist = @fullPluginList;
-       } else {
-               @pluginlist = @earlyPluginList;
-       }
-       
-       my $result = '<ul class="listpreprocessors">';
-       
-       foreach my $plugin (@pluginlist) {
-               $result .= '<li class="listpreprocessors">';
-               $result .= htmllink($params{page}, $params{destpage}, IkiWiki::linkpage($config{plugin_description_dir} . $plugin));
-               $result .= '</li>';
-       }
-       
-       $result .= "</ul>";
-    
-       return $result;
-    } # }}}
-    
-    1
-
-----
-
-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 Encode;
-    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 () { #{{{
-       eval q{use File::Find};
-       error($@) if $@;
-    
-       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;
-               }
-    
-               my %pages;
-               foreach my $dir ($config{srcdir}, @{$config{underlaydirs}}, $config{underlaydir}) {
-                       find({
-                               no_chdir => 1,
-                               wanted => sub {
-                                       $_=decode_utf8($_);
-                                       if (IkiWiki::file_pruned($_, $dir)) {
-                                               $File::Find::prune=1;
-                                       }
-                                       elsif (! -l $_) {
-                                               my ($f)=/$config{wiki_file_regexp}/; # untaint
-                                               return unless defined $f;
-                                               $f=~s/^\Q$dir\E\/?//;
-                                               return unless length $f;
-                                               return if $f =~ /\._([^.]+)$/; # skip internal page
-                                               if (! -d _) {
-                                                       $pages{pagename($f)}=$f;
-                                               }
-                                       }
-                               }
-                       }, $dir);
-               }
-    
-               if ($config{rcs}) {
-                       IkiWiki::disable_commit_hook();
-               }
-               
-               my $needcommit = 0;
-               
-               while (($plugin,$page) = each %pluginpages) {
-                       if (! exists $pages{$page}) {
-                               $needcommit = 1;
-                               gendescription($plugin,$page);
-                       }
-               }
-               
-               if ($config{rcs}) {
-                       if ($needcommit) {
-                               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`:
-
-    <div class="listpreprocessorsinline">
-    
-    <div class="inlineheader">
-    
-    <span class="header">
-    <a href="<TMPL_VAR PAGEURL>"><TMPL_VAR TITLE></a>
-    </span>
-    
-    </div><!--.inlineheader-->
-    
-    <div class="inlinecontent">
-    <TMPL_VAR CONTENT>
-    </div><!--.inlinecontent-->
-    
-    </div><!--.listpreprocessorsinline-->
-
---------
-
-This is what I was using for `listpreprocessors-listonly.tmpl`:
-
-    <p class="listpreprocessors"><a href="<TMPL_VAR PAGEURL>"><TMPL_VAR TITLE></a></p>
-
---------
-
-This is what I was using for `preprocessor-description.tmpl`:
-
-    The <TMPL_VAR plugin> preprocessor command currently has no description.
-    
-    Maybe you should edit this page to add one.
-
-[[tag done]]
+Patch is applied (along with some changes..). [[done]] (But, see
+[[directive_docs]].
diff --git a/doc/todo/directive_docs.mdwn b/doc/todo/directive_docs.mdwn
new file mode 100644 (file)
index 0000000..b130e3d
--- /dev/null
@@ -0,0 +1,77 @@
+The current basewiki is not self-documenting. In particular, if
+[[plugins/listdirectives]] is used, it creates a list with a bunch of
+broken links to directives/*, pages that do not currently exist in the
+docwiki or basewiki.
+
+This could be fixed by adding a page for each directive under to
+`ikiwiki/directives`, and put those into a new underlay, which the plugin
+could enable. Rather a lot of work and maintenance to document all the
+directives like that.
+
+I also considered having it link to the plugin that defined the
+directive. Then all the plugins can be included in a new underlay, which
+both [[plugins/listdirectives]] and [[plugins/websetup]] could enable.
+(The latter could be improved by making the plugin names in the web setup
+be links to docs about each plugin..) 
+
+The problem I ran into doing that is that the existing plugin pages have a
+lot of stuff on them you probably don't want an underlay doing. The biggest
+issues were wikilinks to other pages in the docwiki (which would end up
+broken if the plugins were used as an underlay), and plugin pages that
+include examples of the plugin in use, which are sometimes rather expensive
+(eg, brokenlinks).
+
+Either way requires a lot of reorganisation/doc work, and an onging
+maintenance load.
+
+BTW, this patch would be needed for the second approach, to allow
+listdirectives to map from preprocessor directives back to the plugin that
+defined them:  --[[Joey]]
+
+    commit 0486b46a629cae19ce89492d5ac498bbf9b84f5f
+    Author: Joey Hess <joey@kodama.kitenet.net>
+    Date:   Mon Aug 25 15:38:51 2008 -0400
+    
+        record which plugins registered which hooks
+    
+    diff --git a/IkiWiki.pm b/IkiWiki.pm
+    index e476521..afe982a 100644
+    --- a/IkiWiki.pm
+    +++ b/IkiWiki.pm
+    @@ -493,6 +493,7 @@ sub loadplugins () { #{{{
+       return 1;
+     } #}}}
+     
+    +my $loading_plugin;
+     sub loadplugin ($) { #{{{
+       my $plugin=shift;
+     
+    @@ -502,14 +503,18 @@ sub loadplugin ($) { #{{{
+                        "$installdir/lib/ikiwiki") {
+               if (defined $dir && -x "$dir/plugins/$plugin") {
+                       require IkiWiki::Plugin::external;
+    +                  $loading_plugin=$plugin;
+                       import IkiWiki::Plugin::external "$dir/plugins/$plugin";
+    +                  $loading_plugin=undef;
+                       $loaded_plugins{$plugin}=1;
+                       return 1;
+               }
+       }
+     
+       my $mod="IkiWiki::Plugin::".possibly_foolish_untaint($plugin);
+    +  $loading_plugin=$plugin;
+       eval qq{use $mod};
+    +  $loading_plugin=undef;
+       if ($@) {
+               error("Failed to load plugin $mod: $@");
+       }
+    @@ -1429,6 +1434,9 @@ sub hook (@) { # {{{
+     
+       return if $param{no_override} && exists $hooks{$param{type}}{$param{id}};
+       
+    +  # Record which plugin was being loaded when the hook was defined.
+    +  $param{plugin}=$loading_plugin if defined $loading_plugin;
+    +
+       $hooks{$param{type}}{$param{id}}=\%param;
+       return 1;
+     } # }}}