1 | = Wiki Processors = |
---|
2 | |
---|
3 | Processors are WikiMacros designed to provide alternative markup formats for the [TracWiki Wiki engine]. Processors can be thought of as ''macro functions to process user-edited text''. |
---|
4 | |
---|
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] |
---|
13 | |
---|
14 | |
---|
15 | == Using Processors == |
---|
16 | |
---|
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 | {{{ |
---|
60 | {{{ |
---|
61 | #!html |
---|
62 | <h1 style="color: grey">This is raw HTML</h1> |
---|
63 | }}} |
---|
64 | }}} |
---|
65 | }}} |
---|
66 | {{{#!td valign=top style="border: none; padding-left: 2em" |
---|
67 | {{{ |
---|
68 | #!html |
---|
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 | }}} |
---|
152 | == Available Processors == |
---|
153 | |
---|
154 | The following processors are included in the Trac distribution: |
---|
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 | |
---|
178 | Using the MIME type as processor, it is possible to syntax-highlight the same languages that are supported when browsing source code. |
---|
179 | |
---|
180 | ||||= '''MIME Type Processors''' =|| |
---|
181 | {{{#!tr |
---|
182 | {{{#!td |
---|
183 | Some examples: |
---|
184 | {{{ |
---|
185 | {{{ |
---|
186 | #!text/html |
---|
187 | <h1>text</h1> |
---|
188 | }}} |
---|
189 | }}} |
---|
190 | }}} |
---|
191 | {{{#!td |
---|
192 | The result will be syntax highlighted HTML code: |
---|
193 | {{{ |
---|
194 | #!text/html |
---|
195 | <h1>text</h1> |
---|
196 | }}} |
---|
197 | |
---|
198 | The same is valid for all other [TracSyntaxColoring#SyntaxColoringSupport mime types supported]. |
---|
199 | }}} |
---|
200 | }}} |
---|
201 | {{{#!td |
---|
202 | {{{ |
---|
203 | {{{ |
---|
204 | #!diff |
---|
205 | --- Version 55 |
---|
206 | +++ Version 56 |
---|
207 | @@ -115,8 +115,9 @@ |
---|
208 | name='TracHelloWorld', version='1.0', |
---|
209 | packages=find_packages(exclude=['*.tests*']), |
---|
210 | - entry_points = """ |
---|
211 | - [trac.plugins] |
---|
212 | - helloworld = myplugs.helloworld |
---|
213 | - """, |
---|
214 | + entry_points = { |
---|
215 | + 'trac.plugins': [ |
---|
216 | + 'helloworld = myplugs.helloworld', |
---|
217 | + ], |
---|
218 | + }, |
---|
219 | ) |
---|
220 | }}} |
---|
221 | }}} |
---|
222 | }}} |
---|
223 | {{{#!td |
---|
224 | '''`#!diff`''' has a particularly nice renderer: |
---|
225 | {{{ |
---|
226 | #!diff |
---|
227 | --- Version 55 |
---|
228 | +++ Version 56 |
---|
229 | @@ -115,8 +115,9 @@ |
---|
230 | name='TracHelloWorld', version='1.0', |
---|
231 | packages=find_packages(exclude=['*.tests*']), |
---|
232 | - entry_points = """ |
---|
233 | - [trac.plugins] |
---|
234 | - helloworld = myplugs.helloworld |
---|
235 | - """, |
---|
236 | + entry_points = { |
---|
237 | + 'trac.plugins': [ |
---|
238 | + 'helloworld = myplugs.helloworld', |
---|
239 | + ], |
---|
240 | + }, |
---|
241 | ) |
---|
242 | }}} |
---|
243 | }}} |
---|
244 | |
---|
245 | For more processor macros developed and/or contributed by users, visit: |
---|
246 | * [trac:ProcessorBazaar] |
---|
247 | * [trac:MacroBazaar] |
---|
248 | * [http://trac-hacks.org Trac Hacks] community site |
---|
249 | |
---|
250 | Developing processors is no different from Wiki macros. |
---|
251 | In fact they work the same way, only the usage syntax differs. |
---|
252 | See WikiMacros#DevelopingCustomMacros for more information. |
---|
253 | |
---|
254 | |
---|
255 | ---- |
---|
256 | See also: WikiMacros, WikiHtml, WikiRestructuredText, TracSyntaxColoring, WikiFormatting, TracGuide |
---|