merged, bug left open

[git.ikiwiki.info.git] / doc / plugins / highlight.mdwn

diff --git a/doc/plugins/highlight.mdwn b/doc/plugins/highlight.mdwn
index 07e888f36673fafebce773ed8caf7723c90dea05..5f04fda522987900f803788f62672c0fd6f36b51 100644 (file)
--- a/doc/plugins/highlight.mdwn
+++ b/doc/plugins/highlight.mdwn
@@ -1,36 +1,22 @@
 [[!template id=plugin name=highlight author="[[Joey]]"]]
 [[!tag type/format]]
 
 [[!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.
 
 ## prerequisites
 
 You will need to install the perl bindings to the
 a fast syntax highlighter that supports over a hundred programming
 languages and file formats.
 
 ## prerequisites
 
 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.
+[highlight library](http://www.andre-simon.de/). In Debian
+they are in the [[!debpkg libhighlight-perl]] package. If
+your distribution does not have them, look in `examples/swig`
+in highlight's source.

 
 ## embedding highlighted code
 
 To embed highlighted code on a page, you can use the
 
 ## embedding highlighted code
 
 To embed highlighted code on a page, you can use the

-[[ikiwiki/directive/format]] directive.
+[[format]] plugin.

 
 For example:
 
 
 For example:
 


@@ -40,21 +26,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
+
+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".
+
+       tohighlight => ".c .h .cpp .pl .py Makefile:make",

 
 

-## limitations
+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 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.
+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
 
 On the other hand, this also allows your syntax highlighed
 source code to contain markdown formatted comments and hyperlinks


@@ -63,10 +64,14 @@ to other code files, like this:
        /* \[[!format mdwn """
                This comment will be formatted as *markdown*!
 
        /* \[[!format mdwn """
                This comment will be formatted as *markdown*!
 

-               See [[bar.h]].
+               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.