pages, as well as doing syntax highlighting as a preprocessor directive
(which is either passed the text, or reads it from a file).
-The big list of possibilities:
+## The big list of possibilities
-* [[plugins/contrib/highlightcode]] uses [[cpan Syntax::Highlight::Engine::Kate]],
+* [[plugins/contrib/highlightcode]] uses [[!cpan Syntax::Highlight::Engine::Kate]],
operates on whole source files only, has a few bugs (see
[here](http://u32.net/Highlight_Code_Plugin/), and needs to be updated to
support [[bugs/multiple_pages_with_same_name]].
-* [[cpan IkiWiki-Plugin-syntax]] only operates as a directive.
+* [[!cpan IkiWiki-Plugin-syntax]] only operates as a directive.
Interestingly, it supports multiple highlighting backends, including Kate
and Vim.
* [[plugins/contrib/syntax]] only operates as a directive
([[not_on_source_code_files|automatic_use_of_syntax_plugin_on_source_code_files]]),
- and uses [[cpan Text::VimColor]].
+ and uses [[!cpan Text::VimColor]].
* [[plugins/contrib/sourcehighlight]] uses src-highlight, and operates on
whole source files only. Needs to be updated to
support [[bugs/multiple_pages_with_same_name]].
* [[sourcecode|todo/automatic_use_of_syntax_plugin_on_source_code_files/discussion]]
also uses src-highlight, and operates on whole source files.
- Has problems with [[bugs/multiple_pages_with_same_name]].
+ Updated to work with the fix for [[bugs/multiple_pages_with_same_name]]. Untested with files with no extension, e.g. `Makefile`.
+* [[users/jasonblevins]]'s code plugin uses src-highlight, and supports both
+ while file and directive use.
-General problems:
+## General problems
* Using non-perl syntax highlighting backends is slow. I'd prefer either
using a perl module, or a multiple-backend solution that can use a perl
- module as one option.
+ module as one option. (Or, if there's a great highlighter python module,
+ we could use an external plugin..)
* Currently no single plugin supports both modes of operation (directive
and whole source file to page).
+
+ > This is now fixed by the [[ikiwiki/directive/format]] directive for all
+ > whole-source-file plugins, right?
+
* Nothing seems to support
[[wiki-formatted_comments|wiki-formatted_comments_with_syntax_plugin]]
inside source files. Doing this probably means post-processing the
results of the highlighting engine, to find places where it's highlighted
comments, and then running them through the ikiwiki rendering pipeline.
- This seems fairly doable with [[cpan Syntax::Highlight::Engine::Kate]],
+ This seems fairly doable with [[!cpan Syntax::Highlight::Engine::Kate]],
at least.
* The whole-file plugins tend to have a problem that things that look like
wikilinks in the source code get munged into links by ikiwiki, which can
have confusing results. Similar problem with preprocessor directives.
+ One approach that's also been requested for eg,
+ [[plugins/contrib/mediawiki]] is to allow controlling which linkification
+ types a page type can have on it.
+
+ > The previous two points seem to be related. One thought: instead of
+ > getting the source from the `content` parameter, the plugin could
+ > re-load the page source. That would stop directives/links from
+ > being processed in the source. As noted above, comments
+ > could then be parsed for directives/links later.
+ >
+ > Would it be worth adding a `nodirectives` option when registering
+ > an htmlize hook that switches off directive and link processing before
+ > generating the html for a page?
+
* The whole-file plugins all get confused if there is a `foo.c` and a `foo.h`.
This is trivially fixable now by passing the keepextension option when
registering the htmlize hooks, though.
about it is that, when creating a new page, you can then pick "c" or
"h" or "pl" etc from the dropdown that normally has "mdwn" etc in it.
Is this a bug, or a feature? (Even if a feature, plugins with many
- extensions make the dropdown unusable..)
-* The per page highlighters can't handle "Makefile", or other files
- without a significant extension.
-*
+ extensions make the dropdown unusable.. One way to deal with that is have
+ a config setting that lists what extensions to offer highlighting for.
+ Most people won't need/want the dozens some engines support.)
+* The per page highlighters can't handle creating wiki pages from
+ "Makefile", or other files without a significant extension.
+ Not clear how to fix this, as ikiwiki is very oriented toward file
+ extensions. The workaround is to use a directive on a wiki page, pulling
+ in the Makefile.
+
+ > I wonder how hard it would be to make a patch whereby a file with
+ > no `.` in the name, and a name that matches a filetype, and where
+ > that filetype was registered `keepextension`, then the file is just
+ > chosen as the appropriate type. This would allow `Makefile` to
+ > work.
+
+like this:
+
+ diff --git a/IkiWiki.pm b/IkiWiki.pm
+ index 8d728c9..1bd46a9 100644
+ --- a/IkiWiki.pm
+ +++ b/IkiWiki.pm
+ @@ -618,6 +618,8 @@ sub pagetype ($) {
+
+ if ($page =~ /\.([^.]+)$/) {
+ return $1 if exists $hooks{htmlize}{$1};
+ + } elsif ($hooks{htmlize}{$page}{keepextension}) {
+ + return $page;
+ }
+ return;
+ }
+
+## format directive
+
+Rather than making syntax highlight plugins have to provide a preprocessor
+directive as well as handling whole source files, perhaps a generic format
+directive could be used:
+
+ \[[!format pl """..."""]]
+
+That would run the text through the pl htmlizer, from the syntax hightligh
+plugin. OTOH, if "rst" were given, it would run the text through the rst
+htmlizer. So, more generic, allows mixing different types of markup on one
+page, as well as syntax highlighting. Does require specifying the type of
+format, instead of allowing it to be guessed (which some syntax highlighters
+can do). (This directive is now implemented..)
+
+Hmm, this would also allow comments inside source files to have mdwn
+embedded in them, without making the use of mdwn a special case, or needing
+to postprocess the syntax highlighter output to find comments.
+
+ /* \[[!format mdwn """
+
+ This is a comment in my C file. You can use mdwn in here.
+
+ """]] */
+
+Note that this assumes that directives are expanded in source files.