allow format to use any language supported by highlight

format: Provide a htmlizefallback hook that other plugins can use to
handle formats that are not suitable for general-purpose htmlize hooks.

highlight: Use the hook to allow formatting of any language/extension,
without it needing to be enabled for standalone source files.

highlight: If the highlight perl binding is not available, fallback
safely to a passthrough mode.

1 files changed, 35 insertions, 32 deletions

diff --git a/doc/plugins/highlight.mdwn b/doc/plugins/highlight.mdwn
index 5172af759..44ced80f7 100644
--- a/doc/plugins/highlight.mdwn
+++ b/doc/plugins/highlight.mdwn
@@ -1,7 +1,7 @@
 [[!template id=plugin name=highlight author="[[Joey]]"]]
 [[!tag type/format]]
 
-This plugin allows ikiwiki to syntax highlight source files, using
+This plugin allows ikiwiki to syntax highlight source code, using
 a fast syntax highlighter that supports over a hundred programming
 languages and file formats.
 
@@ -11,26 +11,10 @@ You will need to install the perl bindings to the
 [highlight library](http://www.andre-simon.de/), which in Debian
 are in the [[!debpkg libhighlight-perl]] package.
 
-## configuration
-
-Nothing will be highlighted by default.
-To enable syntax highlighting, use the `tohighlight` setting in your
-setup file to control which files should be syntax highlighted.
-Here is a typical setting for it, enabling highlighting for files
-with the extensions .c, etc, and also for any files named "Makefile".
-
-	tohighlight => ".c .h .cpp .pl .py Makefile:make",
-
-It knows what language to use for most filename extensions (see
-`/etc/highlight/filetypes.conf` for a partial list), but if you want to
-bind an unusual filename extension, or any file without an extension
-(such as a Makefile), to a language, you can do so by appending a colon
-and the name of the language, as illustrated for Makefiles above.
-
 ## embedding highlighted code
 
 To embed highlighted code on a page, you can use the
-[[ikiwiki/directive/format]] directive.
+[[format]] plugin.
 
 For example:
 
@@ -40,21 +24,36 @@ For example:
 	}
 	"""]]
 
-You can do this for any of the extensions/filenames enabled in
-`tohighlight`.
+	\[[!format diff """
+	-bar
+	+foo
+	"""]]
 
-## colors
+You can do this for any extension or language name supported by
+the [highlight library](http://www.andre-simon.de/) -- basically anything
+you can think of should work.
 
-The colors etc used for the syntax highlighting are entirely configurable
-by CSS. See ikiwiki's [[style.css]] for the defaults.
+## highlighting entire source files
 
-## limitations
+To enable syntax highlighting of entire standalone source files, use the
+`tohighlight` setting in your setup file to control which files should be
+syntax highlighted. Here is a typical setting for it, enabling highlighting
+for files with the extensions .c, etc, and also for any files named
+"Makefile".
 
-With this plugin enabled, source files become full-fledged ikiwiki pages,
-which means they can include [[WikiLinks|ikiwiki/wikilink]] and
-[[directives|ikiwiki/directive]] like any other page can, and are also
-affected by the [[smiley]] plugin, if it is enabled. This can be
-annoying if your code accidentially contains things that look like those.
+	tohighlight => ".c .h .cpp .pl .py Makefile:make",
+
+It knows what language to use for most filename extensions (see
+`/etc/highlight/filetypes.conf` for a partial list), but if you want to
+bind an unusual filename extension, or any file without an extension
+(such as a Makefile), to a language, you can do so by appending a colon
+and the name of the language, as illustrated for Makefiles above.
+
+With the plugin configured this way, source files become full-fledged
+wiki pages, which means they can include [[WikiLinks|ikiwiki/wikilink]]
+and [[directives|ikiwiki/directive]] like any other page can, and are also
+affected by the [[smiley]] plugin, if it is enabled. This can be annoying
+if your code accidentially contains things that look like those.
 
 On the other hand, this also allows your syntax highlighed
 source code to contain markdown formatted comments and hyperlinks
@@ -66,7 +65,11 @@ to other code files, like this:
 		See \[[bar.h]].
 	""]] */
 
-## security
+Finally, bear in mind that this lets anyone who can edit a page in your
+wiki also edit source code files that are in your wiki. Use appropriate
+caution.
+
+## colors
 
-This lets anyone who can edit a page in your wiki also edit
-source code files that are in your wiki. Use appropriate caution.
+The colors etc used for the syntax highlighting are entirely configurable
+by CSS. See ikiwiki's [[style.css]] for the defaults.