X-Git-Url: https://sipb.mit.edu/gitweb.cgi/ikiwiki.git/blobdiff_plain/65bf71d387ba406d4fcf697d76151b6953176cf8..3a1ff1d0dc4b09d211e075b653c5a3767d05b74e:/doc/todo/syntax_highlighting.mdwn?ds=sidebyside diff --git a/doc/todo/syntax_highlighting.mdwn b/doc/todo/syntax_highlighting.mdwn index e992cc514..576d456f3 100644 --- a/doc/todo/syntax_highlighting.mdwn +++ b/doc/todo/syntax_highlighting.mdwn @@ -1,54 +1,98 @@ There's been a lot of work on contrib syntax highlighting plugins. One should be picked and added to ikiwiki core. -Ideally, it should support both converting whole source files into wiki +We want to support both converting whole source files into wiki pages, as well as doing syntax highlighting as a preprocessor directive -(which is either passed the text, or reads it from a file). +(which is either passed the text, or reads it from a file). But, +the [[ikiwiki/directive/format]] directive makes this easy enough to +do if the plugin only supports whole source files. So, syntax plugins +do no really need their own preprocessor directive, unless it makes +things easier for the user. -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: +* [hlsimple](http://pivot.cs.unb.ca/git/?p=ikiplugins.git;a=blob_plain;f=IkiWiki/Plugin/hlsimple.pm;hb=HEAD) is a wrapper for the the perl module [[!cpan Syntax::Highlight::Engine::Simple]]. This is pure perl, pretty simple, uses css. It ought to be pretty fast (according to the author, and just because it is not external). +On the other hand, there are not many predefined languages yet. Defining language syntaxes is about as much +work as source-highlight, but in perl. I plan to package the base module for debian. Perhaps after the author +releases the 5 or 6 language definitions he has running on his web site, it might be suitable for inclusion in ikiwiki. [[DavidBremner]] + +## 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. -* Currently no single plugin supports both modes of operation (directive - and whole source file to page). + module as one option. (Or, if there's a great highlighter python module, + we could use an external plugin..) * 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. + registering the htmlize hooks, though. That also should handle the + case of source files with names that do not contain an extension (ie, + "Makefile") -- in this case you just register the while filename + in the htmlize hook. * Whole-file plugins register a bunch of htmlize hooks. The wacky thing 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. -* + "h" or "pl" etc from the dropdown that normally has "Markdown" etc in it. + Is this a bug, or a feature? Even if a feature, plugins with many + extensions make the dropdown unusable.. + + Perhaps the thing to do here is to use the new `longname` parameter to + the format hook, to give them all names that will group together at or + near the end of the list. Ie: "Syntax: perl", "Syntax: C", etc. + +## format directive and comments + +Hmm, the [[ikiwiki/directive/format]] directive 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, +which has its own set of problems.