How I accomplished this and where I'd like to take it

[git.ikiwiki.info.git] / doc / todo / syntax_highlighting.mdwn

diff --git a/doc/todo/syntax_highlighting.mdwn b/doc/todo/syntax_highlighting.mdwn
index e992cc51444144f8e1501d0a0966aa5c07fc906b..43878437f7fd8cb1496c06e9dbc7b77a33a89d5d 100644 (file)
--- a/doc/todo/syntax_highlighting.mdwn
+++ b/doc/todo/syntax_highlighting.mdwn
@@ -5,7 +5,7 @@ Ideally, it should 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).
 
 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]],
   operates on whole source files only, has a few bugs (see
 
 * [[plugins/contrib/highlightcode]] uses [[cpan Syntax::Highlight::Engine::Kate]],
   operates on whole source files only, has a few bugs (see


@@ -22,13 +22,14 @@ The big list of possibilities:
   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.
   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`.

 
 

-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
 
 * 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).
 * Nothing seems to support 
 * Currently no single plugin supports both modes of operation (directive
   and whole source file to page).
 * Nothing seems to support 


@@ -41,6 +42,9 @@ General problems:
 * 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.
 * 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 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.
 * 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.


@@ -48,7 +52,38 @@ General problems:
   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
   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.
+
+## 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 allows it to be guessed (which some syntax highlighters
+can do).
+
+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.