ikiwiki (3.20130711) unstable; urgency=low
[ikiwiki.git] / doc / plugins / contrib / syntax.mdwn
1 [[!template id=plugin name=syntax author="[[VictorMoral]]"]]
2 [[!tag type/chrome type/slow]]
3
4 The `syntax` plugin adds support to ikiwiki for syntax highlighting through the *vim* editor and its perl interface [[!cpan Text::VimColor]].  It depends on a functional vim installation.
5
6 The plugin inserts a fragment of HTML with special marks from a file or a string text. It accepts the following parameters:
7
8 * **type** (optional): this is the file type for vim syntax highlighthing. It can be omitted if the param *file* exists.
9 * **file**: Path to the source file. It must exist on every rebuild of the wiki.
10 * **text**: Text string with the source.
11 * **description** (optional): little description about the content.
12 * **linenumbers** (optional): enable the line numering of the source page. A value greater than zero is the first line number.
13
14 The params *file* and *text* are mutually exclusive.
15
16 In the case of file parameter, `syntax` will build a html link for direct download.
17
18 Example:
19
20        \[[!syntax type="perl" text="""  
21        #!/usr/bin/perl
22
23        my $a = "World";
24        print "Hello, ${a}\n";
25        """]]
26
27 or 
28
29        \[[!syntax file="/examples/hello.pl" description="My first perl program"]]
30
31 This plugin create the following CSS styles:
32
33 * syntax
34 * synComment
35 * synConstant
36 * syncIdentifier
37 * synPreProc
38 * synType
39 * synSpecial
40 * synUnderlined
41 * synError
42 * synTodo
43 * synTitle
44
45 It can be downloaded from [here](http://taquiones.net/files/misc/) or through my personal debian repository at <http://taquiones.net/files/debian/>. There is a page with examples: <http://taquiones.net/software/syntax-examples.html>
46
47 _**NOTE:** all the above links are broken_
48
49 Any help, comments or critics are welcome at <victor@taquiones.net>.
50
51 ## version 0.9
52
53 - Add a force_subpage parameter for link build
54 - Fix a bug in syntax page link
55 - Documented a bug with markdown indented text
56 - Documented the syntax directive
57
58 ## version 0.7
59
60 - Version change to GPL
61 - Add *linenumbers* parameter
62 - The *file* parameter should be point to a ikiwiki source page. 
63 - The *description* parameter will be converted on a URL if the *file* parameter exist.
64
65 I need help for debugging this module. Thanks in advance.