5 | ˆà | The Wiki engine uses processors to allow using [wiki:WikiRestructuredText Restructured Text], [wiki:WikiHtml raw HTML] and [http://www.textism.com/tools/textile/ textile] in any Wiki text throughout Trac.ˆà |
ˆà | 5 | Wiki processors can be used in any Wiki text throughout Trac,ˆà |
ˆà | 6 | for various different purposes, like:ˆà |
ˆà | 7 | - [#CodeHighlightingSupport syntax highlighting] or for rendering text verbatim,ˆà |
ˆà | 8 | - rendering [#HTMLrelated Wiki markup inside a context], ˆà |
ˆà | 9 | like inside <div> blocks or <span> or within <td> or <th> table cells,ˆà |
ˆà | 10 | - using an alternative markup syntax, like [wiki:WikiHtml raw HTML] andˆà |
ˆà | 11 | [wiki:WikiRestructuredText Restructured Text],ˆà |
ˆà | 12 | or [http://www.textism.com/tools/textile/ textile]ˆà |
10 | ˆà | To use a processor on a block of text, use a Wiki code block, selecting a processor by name using ''shebang notation'' (#!), familiar to most UNIX users from scripts.ˆà |
11 | ˆà | ˆà |
12 | ˆà | '''Example 1''' (''inserting raw HTML in a wiki text''):ˆà |
13 | ˆà | ˆà |
ˆà | 17 | To use a processor on a block of text, first delimit the lines usingˆà |
ˆà | 18 | a Wiki ''code block'':ˆà |
ˆà | 19 | {{{ˆà |
ˆà | 20 | {{{ˆà |
ˆà | 21 | The linesˆà |
ˆà | 22 | that should be processed...ˆà |
ˆà | 23 | }}}ˆà |
ˆà | 24 | }}}ˆà |
ˆà | 25 | ˆà |
ˆà | 26 | Immediately after the `{{{` or on the line just below, ˆà |
ˆà | 27 | add `#!` followed by the ''processor name''.ˆà |
ˆà | 28 | ˆà |
ˆà | 29 | {{{ˆà |
ˆà | 30 | {{{ˆà |
ˆà | 31 | #!processornameˆà |
ˆà | 32 | The linesˆà |
ˆà | 33 | that should be processed...ˆà |
ˆà | 34 | }}}ˆà |
ˆà | 35 | }}}ˆà |
ˆà | 36 | ˆà |
ˆà | 37 | This is the "shebang" notation, familiar to most UNIX users.ˆà |
ˆà | 38 | ˆà |
ˆà | 39 | Besides their content, some Wiki processors can also accept ''parameters'',ˆà |
ˆà | 40 | which are then given as `key=value` pairs after the processor name, ˆà |
ˆà | 41 | on the same line. If `value` has to contain space, as it's often the case forˆà |
ˆà | 42 | the style parameter, a quoted string can be used (`key="value with space"`).ˆà |
ˆà | 43 | ˆà |
ˆà | 44 | As some processors are meant to process Wiki markup, it's quite possible toˆà |
ˆà | 45 | ''nest'' processor blocks.ˆà |
ˆà | 46 | You may want to indent the content of nested blocks for increased clarity,ˆà |
ˆà | 47 | this extra indentation will be ignored when processing the content.ˆà |
ˆà | 48 | ˆà |
ˆà | 49 | ˆà |
ˆà | 50 | == Examples ==ˆà |
ˆà | 51 | ˆà |
ˆà | 52 | ||= Wiki Markup =||= Display =||ˆà |
ˆà | 53 | {{{#!td colspan=2 align=center style="border: none"ˆà |
ˆà | 54 | ˆà |
ˆà | 55 | __Example 1__: Inserting raw HTMLˆà |
ˆà | 56 | }}}ˆà |
ˆà | 57 | |-----------------------------------------------------------------ˆà |
ˆà | 58 | {{{#!td style="border: none"ˆà |
ˆà | 59 | {{{ˆà |
18 | ˆà | <h1 style="color: orange">This is raw HTML</h1>ˆà |
19 | ˆà | }}}</pre>ˆà |
20 | ˆà | }}}ˆà |
21 | ˆà | ˆà |
22 | ˆà | '''Results in:'''ˆà |
23 | ˆà | {{{ˆà |
24 | ˆà | #!htmlˆà |
25 | ˆà | <h1 style="color: orange">This is raw HTML</h1>ˆà |
26 | ˆà | }}}ˆà |
27 | ˆà | ˆà |
28 | ˆà | Note that since 0.11, such blocks of HTML have to be self-contained, i.e. you can't start an HTML element in one block and close it later in a second block. Use div or span processors for achieving similar effect (see WikiHtml).ˆà |
29 | ˆà | ˆà |
30 | ˆà | ----ˆà |
31 | ˆà | ˆà |
32 | ˆà | '''Example 2''' (''inserting Restructured Text in wiki text''):ˆà |
33 | ˆà | ˆà |
34 | ˆà | {{{ˆà |
35 | ˆà | #!htmlˆà |
36 | ˆà | <pre class="wiki">{{{ˆà |
37 | ˆà | #!rstˆà |
38 | ˆà | A headerˆà |
39 | ˆà | --------ˆà |
40 | ˆà | This is some **text** with a footnote [*]_.ˆà |
41 | ˆà | ˆà |
42 | ˆà | .. [*] This is the footnote.ˆà |
43 | ˆà | }}}</pre>ˆà |
44 | ˆà | }}}ˆà |
45 | ˆà | ˆà |
46 | ˆà | '''Results in:'''ˆà |
47 | ˆà | {{{ˆà |
48 | ˆà | #!rstˆà |
49 | ˆà | A headerˆà |
50 | ˆà | --------ˆà |
51 | ˆà | This is some **text** with a footnote [*]_.ˆà |
52 | ˆà | ˆà |
53 | ˆà | .. [*] This is the footnote.ˆà |
54 | ˆà | }}}ˆà |
55 | ˆà | ----ˆà |
56 | ˆà | '''Example 3''' (''inserting a block of C source code in wiki text''):ˆà |
57 | ˆà | ˆà |
58 | ˆà | {{{ˆà |
59 | ˆà | #!htmlˆà |
60 | ˆà | <pre class="wiki">{{{ˆà |
61 | ˆà | #!cˆà |
62 | ˆà | int main(int argc, char *argv[])ˆà |
63 | ˆà | {ˆà |
64 | ˆà | printf("Hello World\n");ˆà |
65 | ˆà | return 0;ˆà |
66 | ˆà | }ˆà |
67 | ˆà | }}}</pre>ˆà |
68 | ˆà | }}}ˆà |
69 | ˆà | ˆà |
70 | ˆà | '''Results in:'''ˆà |
71 | ˆà | {{{ˆà |
72 | ˆà | #!cˆà |
73 | ˆà | int main(int argc, char *argv[])ˆà |
74 | ˆà | {ˆà |
75 | ˆà | printf("Hello World\n");ˆà |
76 | ˆà | return 0;ˆà |
77 | ˆà | }ˆà |
78 | ˆà | }}}ˆà |
79 | ˆà | ˆà |
80 | ˆà | ----ˆà |
81 | ˆà | ˆà |
ˆà | 69 | <h1 style="color: grey">This is raw HTML</h1>ˆà |
ˆà | 70 | }}}ˆà |
ˆà | 71 | }}}ˆà |
ˆà | 72 | |-----------------------------------------------------------------ˆà |
ˆà | 73 | {{{#!td colspan=2 align=center style="border: none"ˆà |
ˆà | 74 | ˆà |
ˆà | 75 | __Example 2__: Highlighted Python code in a <div> block with custom styleˆà |
ˆà | 76 | }}}ˆà |
ˆà | 77 | |-----------------------------------------------------------------ˆà |
ˆà | 78 | {{{#!td style="border: none"ˆà |
ˆà | 79 | {{{ˆà |
ˆà | 80 | {{{#!div style="background: #ffd; border: 3px ridge"ˆà |
ˆà | 81 | ˆà |
ˆà | 82 | This is an example of embedded "code" block:ˆà |
ˆà | 83 | ˆà |
ˆà | 84 | {{{ˆà |
ˆà | 85 | #!pythonˆà |
ˆà | 86 | def hello():ˆà |
ˆà | 87 | return "world"ˆà |
ˆà | 88 | }}}ˆà |
ˆà | 89 | ˆà |
ˆà | 90 | }}}ˆà |
ˆà | 91 | }}}ˆà |
ˆà | 92 | }}}ˆà |
ˆà | 93 | {{{#!td valign=top style="border: none; padding: 1em"ˆà |
ˆà | 94 | {{{#!div style="background: #ffd; border: 3px ridge"ˆà |
ˆà | 95 | ˆà |
ˆà | 96 | This is an example of embedded "code" block:ˆà |
ˆà | 97 | ˆà |
ˆà | 98 | {{{ˆà |
ˆà | 99 | #!pythonˆà |
ˆà | 100 | def hello():ˆà |
ˆà | 101 | return "world"ˆà |
ˆà | 102 | }}}ˆà |
ˆà | 103 | ˆà |
ˆà | 104 | }}}ˆà |
ˆà | 105 | }}}ˆà |
ˆà | 106 | |-----------------------------------------------------------------ˆà |
ˆà | 107 | {{{#!td colspan=2 align=center style="border: none"ˆà |
ˆà | 108 | ˆà |
ˆà | 109 | __Example 3__: Searching tickets from a wiki page, by keywords.ˆà |
ˆà | 110 | }}}ˆà |
ˆà | 111 | |-----------------------------------------------------------------ˆà |
ˆà | 112 | {{{#!td style="border: none"ˆà |
ˆà | 113 | {{{ˆà |
ˆà | 114 | {{{ˆà |
ˆà | 115 | #!htmlˆà |
ˆà | 116 | <form action="/query" method="get"><div>ˆà |
ˆà | 117 | <input type="text" name="keywords" value="~" size="30"/>ˆà |
ˆà | 118 | <input type="submit" value="Search by Keywords"/>ˆà |
ˆà | 119 | <!-- To control what fields show up use hidden fieldsˆà |
ˆà | 120 | <input type="hidden" name="col" value="id"/>ˆà |
ˆà | 121 | <input type="hidden" name="col" value="summary"/>ˆà |
ˆà | 122 | <input type="hidden" name="col" value="status"/>ˆà |
ˆà | 123 | <input type="hidden" name="col" value="milestone"/>ˆà |
ˆà | 124 | <input type="hidden" name="col" value="version"/>ˆà |
ˆà | 125 | <input type="hidden" name="col" value="owner"/>ˆà |
ˆà | 126 | <input type="hidden" name="col" value="priority"/>ˆà |
ˆà | 127 | <input type="hidden" name="col" value="component"/>ˆà |
ˆà | 128 | -->ˆà |
ˆà | 129 | </div></form>ˆà |
ˆà | 130 | }}}ˆà |
ˆà | 131 | }}}ˆà |
ˆà | 132 | }}}ˆà |
ˆà | 133 | {{{#!td valign=top style="border: none; padding: 1em"ˆà |
ˆà | 134 | {{{ˆà |
ˆà | 135 | #!htmlˆà |
ˆà | 136 | <form action="/query" method="get"><div>ˆà |
ˆà | 137 | <input type="text" name="keywords" value="~" size="30"/>ˆà |
ˆà | 138 | <input type="submit" value="Search by Keywords"/>ˆà |
ˆà | 139 | <!-- To control what fields show up use hidden fieldsˆà |
ˆà | 140 | <input type="hidden" name="col" value="id"/>ˆà |
ˆà | 141 | <input type="hidden" name="col" value="summary"/>ˆà |
ˆà | 142 | <input type="hidden" name="col" value="status"/>ˆà |
ˆà | 143 | <input type="hidden" name="col" value="milestone"/>ˆà |
ˆà | 144 | <input type="hidden" name="col" value="version"/>ˆà |
ˆà | 145 | <input type="hidden" name="col" value="owner"/>ˆà |
ˆà | 146 | <input type="hidden" name="col" value="priority"/>ˆà |
ˆà | 147 | <input type="hidden" name="col" value="component"/>ˆà |
ˆà | 148 | -->ˆà |
ˆà | 149 | </div></form>ˆà |
ˆà | 150 | }}}ˆà |
ˆà | 151 | }}}ˆà |
84 | ˆà | * '''html''' -- Insert custom HTML in a wiki page. See WikiHtml.ˆà |
85 | ˆà | * '''div''' -- Wrap an arbitrary Wiki content in a <div> element (''since 0.11''). See WikiHtml.ˆà |
86 | ˆà | * '''span''' -- Wrap an arbitrary Wiki content in a <span> element (''since 0.11''). See also WikiHtml.ˆà |
87 | ˆà | * '''rst''' -- Trac support for Restructured Text. See WikiRestructuredText.ˆà |
88 | ˆà | * '''textile''' -- Supported if [http://cheeseshop.python.org/pypi/textile Textile] is installed. See [http://www.textism.com/tools/textile/ a Textile reference].ˆà |
89 | ˆà | * '''comment''' -- Do not process the text in this section (i.e. contents exist only in the plain text - not in the rendered page).ˆà |
90 | ˆà | * '''diff''' -- Pretty print patches and diffs.ˆà |
91 | ˆà | ˆà |
92 | ˆà | === Code Highlighting Support ===ˆà |
93 | ˆà | Trac includes processors to provide inline [wiki:TracSyntaxColoring syntax highlighting] for the following languages:ˆà |
94 | ˆà | * '''c''' -- Cˆà |
95 | ˆà | * '''cpp''' -- C++ˆà |
96 | ˆà | * '''csharp''' --- C# (''use #!text/x-csharp'')ˆà |
97 | ˆà | * '''python''' -- Pythonˆà |
98 | ˆà | * '''perl''' -- Perlˆà |
99 | ˆà | * '''ruby''' -- Rubyˆà |
100 | ˆà | * '''php''' -- PHPˆà |
101 | ˆà | * '''asp''' -- ASPˆà |
102 | ˆà | * '''java''' -- Javaˆà |
103 | ˆà | * '''js''' -- Javascriptˆà |
104 | ˆà | * '''sql''' -- SQLˆà |
105 | ˆà | * '''xml''' -- XMLˆà |
106 | ˆà | * '''sh''' -- Bourne/Bash shellˆà |
107 | ˆà | ˆà |
108 | ˆà | '''Note:''' ''Trac relies on external software packages for syntax coloring. See TracSyntaxColoring for more info.''ˆà |
109 | ˆà | ˆà |
110 | ˆà | By using the MIME type as processor, it is possible to syntax-highlight the same languages that are supported when browsing source code. For example, you can write:ˆà |
111 | ˆà | {{{ˆà |
ˆà | 155 | ˆà |
ˆà | 156 | || '''`#!default`''' || Present the text verbatim in a preformatted text block. This is the same as specifying ''no'' processor name (and no `#!`) ||ˆà |
ˆà | 157 | || '''`#!comment`''' || Do not process the text in this section (i.e. contents exist only in the plain text - not in the rendered page). ||ˆà |
ˆà | 158 | |||| ||ˆà |
ˆà | 159 | ||||= '''HTML related''' =||ˆà |
ˆà | 160 | || '''`#!html`''' || Insert custom HTML in a wiki page. ||ˆà |
ˆà | 161 | || '''`#!htmlcomment`''' || Insert an HTML comment in a wiki page (''since 0.12''). ||ˆà |
ˆà | 162 | || || Note that `#!html` blocks have to be ''self-contained'', i.e. you can't start an HTML element in one block and close it later in a second block. Use the following processors for achieving a similar effect. ||ˆà |
ˆà | 163 | || '''`#!div`''' || Wrap an arbitrary Wiki content inside a <div> element (''since 0.11''). ||ˆà |
ˆà | 164 | || '''`#!span`''' || Wrap an arbitrary Wiki content inside a <span> element (''since 0.11''). ||ˆà |
ˆà | 165 | || '''`#!td`''' || Wrap an arbitrary Wiki content inside a <td> element (''since 0.12'') ||ˆà |
ˆà | 166 | || '''`#!th`''' || Wrap an arbitrary Wiki content inside a <th> element (''since 0.12'') ||ˆà |
ˆà | 167 | || '''`#!tr`''' || Can optionally be used for wrapping `#!td` and `#!th` blocks, either for specifying row attributes of better visual grouping (''since 0.12'') ||ˆà |
ˆà | 168 | || || See WikiHtml for example usage and more details about these processors. ||ˆà |
ˆà | 169 | |||| ||ˆà |
ˆà | 170 | ||||= '''Other Markups''' =||ˆà |
ˆà | 171 | || '''`#!rst`''' || Trac support for Restructured Text. See WikiRestructuredText. ||ˆà |
ˆà | 172 | || '''`#!textile`''' || Supported if [http://cheeseshop.python.org/pypi/textile Textile] is installed. See [http://www.textism.com/tools/textile/ a Textile reference]. ||ˆà |
ˆà | 173 | |||| ||ˆà |
ˆà | 174 | ||||= '''Code Highlighting Support''' =||ˆà |
ˆà | 175 | || '''`#!c`''' [[BR]] '''`#!cpp`''' (C++) [[BR]] '''`#!python`''' [[BR]] '''`#!perl`''' [[BR]] '''`#!ruby`''' [[BR]] '''`#!php`''' [[BR]] '''`#!asp`''' [[BR]] '''`#!java`''' [[BR]] '''`#!js`''' (Javascript) [[BR]] '''`#!sql`''' [[BR]] '''`#!xml`''' (XML or HTML) [[BR]] '''`#!sh`''' (!Bourne/Bash shell) [[BR]] '''etc.''' [[BR]] || Trac includes processors to provide inline syntax highlighting for source code in various languages. [[BR]] [[BR]] Trac relies on external software packages for syntax coloring, like [http://pygments.org Pygments]. [[BR]] [[BR]] See TracSyntaxColoring for information about which languages are supported and how to enable support for more languages. ||ˆà |
ˆà | 176 | |||| ||ˆà |
ˆà | 177 | ||||= '''MIME Type Processors''' =||ˆà |
ˆà | 178 | |||| Using the MIME type as processor, it is possible to syntax-highlight the same languages that are supported when browsing source code. ||ˆà |
ˆà | 179 | {{{#!trˆà |
ˆà | 180 | {{{#!tdˆà |
ˆà | 181 | Some examples:ˆà |
ˆà | 182 | {{{ˆà |
122 | ˆà | }}}ˆà |
123 | ˆà | ˆà |
124 | ˆà | The same is valid for all other mime types supported.ˆà |
125 | ˆà | ˆà |
ˆà | 194 | }}}ˆà |
ˆà | 195 | ˆà |
ˆà | 196 | The same is valid for all other [TracSyntaxColoring#SyntaxColoringSupport mime types supported].ˆà |
ˆà | 197 | }}}ˆà |
ˆà | 198 | }}}ˆà |
ˆà | 199 | {{{#!tdˆà |
ˆà | 200 | {{{ˆà |
ˆà | 201 | {{{ˆà |
ˆà | 202 | #!diffˆà |
ˆà | 203 | --- Version 55ˆà |
ˆà | 204 | +++ Version 56ˆà |
ˆà | 205 | @@ -115,8 +115,9 @@ˆà |
ˆà | 206 | name='TracHelloWorld', version='1.0',ˆà |
ˆà | 207 | packages=find_packages(exclude=['*.tests*']),ˆà |
ˆà | 208 | - entry_points = """ˆà |
ˆà | 209 | - [trac.plugins]ˆà |
ˆà | 210 | - helloworld = myplugs.helloworldˆà |
ˆà | 211 | - """,ˆà |
ˆà | 212 | + entry_points = {ˆà |
ˆà | 213 | + 'trac.plugins': [ˆà |
ˆà | 214 | + 'helloworld = myplugs.helloworld',ˆà |
ˆà | 215 | + ],ˆà |
ˆà | 216 | + },ˆà |
ˆà | 217 | )ˆà |
ˆà | 218 | }}}ˆà |
ˆà | 219 | }}}ˆà |
ˆà | 220 | }}}ˆà |
ˆà | 221 | {{{#!tdˆà |
ˆà | 222 | '''`#!diff`''' has a particularly nice renderer:ˆà |
ˆà | 223 | {{{ˆà |
ˆà | 224 | #!diffˆà |
ˆà | 225 | --- Version 55ˆà |
ˆà | 226 | +++ Version 56ˆà |
ˆà | 227 | @@ -115,8 +115,9 @@ˆà |
ˆà | 228 | name='TracHelloWorld', version='1.0',ˆà |
ˆà | 229 | packages=find_packages(exclude=['*.tests*']),ˆà |
ˆà | 230 | - entry_points = """ˆà |
ˆà | 231 | - [trac.plugins]ˆà |
ˆà | 232 | - helloworld = myplugs.helloworldˆà |
ˆà | 233 | - """,ˆà |
ˆà | 234 | + entry_points = {ˆà |
ˆà | 235 | + 'trac.plugins': [ˆà |
ˆà | 236 | + 'helloworld = myplugs.helloworld',ˆà |
ˆà | 237 | + ],ˆà |
ˆà | 238 | + },ˆà |
ˆà | 239 | )ˆà |
ˆà | 240 | }}}ˆà |
ˆà | 241 | }}}ˆà |