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, such as: |
---|
6 | - [#CodeHighlightingSupport syntax highlighting] or for rendering text verbatim |
---|
7 | - rendering [#HTMLrelated Wiki markup inside a context], like inside <div> blocks or <span> or within <td> or <th> table cells |
---|
8 | - using an alternative markup syntax, like [wiki:WikiHtml raw HTML] and [wiki:WikiRestructuredText Restructured Text] or [http://www.textism.com/tools/textile/ textile] |
---|
9 | |
---|
10 | == Using Processors |
---|
11 | |
---|
12 | To use a processor on a block of text, first delimit the lines using a Wiki ''code block'': |
---|
13 | {{{ |
---|
14 | {{{ |
---|
15 | The lines |
---|
16 | that should be processed... |
---|
17 | }}} |
---|
18 | }}} |
---|
19 | |
---|
20 | Immediately after the `{{{` or on the line just below, add `#!` followed by the ''processor name'': |
---|
21 | |
---|
22 | {{{ |
---|
23 | {{{ |
---|
24 | #!processorname |
---|
25 | The lines |
---|
26 | that should be processed... |
---|
27 | }}} |
---|
28 | }}} |
---|
29 | |
---|
30 | This is the "shebang" notation, familiar to most UNIX users. |
---|
31 | |
---|
32 | Besides their content, some Wiki processors can also accept ''parameters'', which are then given as `key=value` pairs after the processor name and on the same line. If `value` has to contain space, as it's often the case for the style parameter, a quoted string can be used (`key="value with space"`). |
---|
33 | |
---|
34 | As some processors are meant to process Wiki markup, it's quite possible to ''nest'' processor blocks. |
---|
35 | You may want to indent the content of nested blocks for increased clarity, this extra indentation will be ignored when processing the content. |
---|
36 | |
---|
37 | == Examples |
---|
38 | |
---|
39 | ||= Wiki Markup =||= Display =|| |
---|
40 | {{{#!td colspan=2 align=center style="border: none" |
---|
41 | |
---|
42 | __Example 1__: Inserting raw HTML |
---|
43 | }}} |
---|
44 | |----------------------------------------------------------------- |
---|
45 | {{{#!td style="border: none" |
---|
46 | {{{ |
---|
47 | {{{ |
---|
48 | #!html |
---|
49 | <h1 style="color: grey">This is raw HTML</h1> |
---|
50 | }}} |
---|
51 | }}} |
---|
52 | }}} |
---|
53 | {{{#!td valign=top style="border: none; padding-left: 2em" |
---|
54 | {{{ |
---|
55 | #!html |
---|
56 | <h1 style="color: grey">This is raw HTML</h1> |
---|
57 | }}} |
---|
58 | }}} |
---|
59 | |----------------------------------------------------------------- |
---|
60 | {{{#!td colspan=2 align=center style="border: none" |
---|
61 | |
---|
62 | __Example 2__: Highlighted Python code in a <div> block with custom style |
---|
63 | }}} |
---|
64 | |----------------------------------------------------------------- |
---|
65 | {{{#!td style="border: none" |
---|
66 | {{{ |
---|
67 | {{{#!div style="background: #ffd; border: 3px ridge" |
---|
68 | |
---|
69 | This is an example of embedded "code" block: |
---|
70 | |
---|
71 | {{{ |
---|
72 | #!python |
---|
73 | def hello(): |
---|
74 | return "world" |
---|
75 | }}} |
---|
76 | |
---|
77 | }}} |
---|
78 | }}} |
---|
79 | }}} |
---|
80 | {{{#!td valign=top style="border: none; padding: 1em" |
---|
81 | {{{#!div style="background: #ffd; border: 3px ridge" |
---|
82 | |
---|
83 | This is an example of embedded "code" block: |
---|
84 | |
---|
85 | {{{ |
---|
86 | #!python |
---|
87 | def hello(): |
---|
88 | return "world" |
---|
89 | }}} |
---|
90 | |
---|
91 | }}} |
---|
92 | }}} |
---|
93 | |----------------------------------------------------------------- |
---|
94 | {{{#!td colspan=2 align=center style="border: none" |
---|
95 | |
---|
96 | __Example 3__: Searching tickets from a wiki page, by keywords. |
---|
97 | }}} |
---|
98 | |----------------------------------------------------------------- |
---|
99 | {{{#!td style="border: none" |
---|
100 | {{{ |
---|
101 | {{{ |
---|
102 | #!html |
---|
103 | <form action="/query" method="get"><div> |
---|
104 | <input type="text" name="keywords" value="~" size="30"/> |
---|
105 | <input type="submit" value="Search by Keywords"/> |
---|
106 | <!-- To control what fields show up use hidden fields |
---|
107 | <input type="hidden" name="col" value="id"/> |
---|
108 | <input type="hidden" name="col" value="summary"/> |
---|
109 | <input type="hidden" name="col" value="status"/> |
---|
110 | <input type="hidden" name="col" value="milestone"/> |
---|
111 | <input type="hidden" name="col" value="version"/> |
---|
112 | <input type="hidden" name="col" value="owner"/> |
---|
113 | <input type="hidden" name="col" value="priority"/> |
---|
114 | <input type="hidden" name="col" value="component"/> |
---|
115 | --> |
---|
116 | </div></form> |
---|
117 | }}} |
---|
118 | }}} |
---|
119 | }}} |
---|
120 | {{{#!td valign=top style="border: none; padding: 1em" |
---|
121 | {{{ |
---|
122 | #!html |
---|
123 | <form action="/query" method="get"><div> |
---|
124 | <input type="text" name="keywords" value="~" size="30"/> |
---|
125 | <input type="submit" value="Search by Keywords"/> |
---|
126 | <!-- To control what fields show up use hidden fields |
---|
127 | <input type="hidden" name="col" value="id"/> |
---|
128 | <input type="hidden" name="col" value="summary"/> |
---|
129 | <input type="hidden" name="col" value="status"/> |
---|
130 | <input type="hidden" name="col" value="milestone"/> |
---|
131 | <input type="hidden" name="col" value="version"/> |
---|
132 | <input type="hidden" name="col" value="owner"/> |
---|
133 | <input type="hidden" name="col" value="priority"/> |
---|
134 | <input type="hidden" name="col" value="component"/> |
---|
135 | --> |
---|
136 | </div></form> |
---|
137 | }}} |
---|
138 | }}} |
---|
139 | |
---|
140 | == Available Processors |
---|
141 | |
---|
142 | The following processors are included in the Trac distribution: |
---|
143 | |
---|
144 | || '''`#!default`''' || Present the text verbatim in a preformatted text block. This is the same as specifying ''no'' processor name (and no `#!`) || |
---|
145 | || '''`#!comment`''' || Do not process the text in this section, i.e. contents exist only in the plain text - not in the rendered page. || |
---|
146 | || '''`#!rtl`''' || Introduce a Right-To-Left block with appropriate CSS direction and styling ''(since 0.12.2)'' || |
---|
147 | |||| || |
---|
148 | ||||= '''[=#HTMLrelated HTML related]''' =|| |
---|
149 | || '''`#!html`''' || Insert custom HTML in a wiki page. || |
---|
150 | || '''`#!htmlcomment`''' || Insert an HTML comment in a wiki page (''since 0.12''). || |
---|
151 | || || 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. || |
---|
152 | || '''`#!div`''' || Wrap an arbitrary Wiki content inside a <div> element (''since 0.11''). || |
---|
153 | || '''`#!span`''' || Wrap an arbitrary Wiki content inside a <span> element (''since 0.11''). || |
---|
154 | || '''`#!td`''' || Wrap an arbitrary Wiki content inside a <td> element (''since 0.12'') || |
---|
155 | || '''`#!th`''' || Wrap an arbitrary Wiki content inside a <th> element (''since 0.12'') || |
---|
156 | || '''`#!tr`''' || Can optionally be used for wrapping `#!td` and `#!th` blocks, either for specifying row attributes or better visual grouping (''since 0.12'') || |
---|
157 | || '''`#!table`''' || Can optionally be used for wrapping `#!tr`, `#!td` and `#!th` blocks, for specifying table attributes. One current limitation however is that tables cannot be nested. (''since 0.12'') || |
---|
158 | || || See WikiHtml for example usage and more details about these processors. || |
---|
159 | |||| || |
---|
160 | ||||= '''Other Markups''' =|| |
---|
161 | || '''`#!rst`''' || Trac support for Restructured Text. See WikiRestructuredText. || |
---|
162 | || '''`#!textile`''' || Supported if [http://cheeseshop.python.org/pypi/textile Textile] is installed. See [http://www.textism.com/tools/textile/ a Textile reference]. || |
---|
163 | |||| || |
---|
164 | ||||= '''[=#CodeHighlightingSupport Code Highlighting Support]''' =|| |
---|
165 | || '''`#!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. || |
---|
166 | |||| || |
---|
167 | |
---|
168 | Since 1.1.2 the default, coding highlighting and MIME-type processors support the argument `lineno` for adding line numbering to the code block. When a value is specified, as in `lineno=3`, the numbering will start at the specified value. When used in combination with the `lineno` argument, the `marks` argument is also supported for highlighting lines. A single line number, set of line numbers and range of line numbers are allowed. For example, `marks=3`, `marks=3-6`, `marks=3,5,7` and `marks=3-5,7` are all allowed. The specified values are relative to the numbered lines, so if `lineno=2` is specified to start the line numbering at 2, `marks=2` will result in the first line being highlighted. |
---|
169 | |
---|
170 | Using the MIME type as processor, it is possible to syntax-highlight the same languages that are supported when browsing source code. |
---|
171 | |
---|
172 | ||||= '''MIME Type Processors''' =|| |
---|
173 | {{{#!tr |
---|
174 | {{{#!td |
---|
175 | Some examples: |
---|
176 | {{{ |
---|
177 | {{{ |
---|
178 | #!text/html |
---|
179 | <h1>text</h1> |
---|
180 | }}} |
---|
181 | }}} |
---|
182 | }}} |
---|
183 | {{{#!td |
---|
184 | The result will be syntax highlighted HTML code: |
---|
185 | {{{ |
---|
186 | #!text/html |
---|
187 | <h1>text</h1> |
---|
188 | }}} |
---|
189 | |
---|
190 | The same is valid for all other [TracSyntaxColoring#SyntaxColoringSupport mime types supported]. |
---|
191 | }}} |
---|
192 | }}} |
---|
193 | {{{#!td |
---|
194 | {{{ |
---|
195 | {{{ |
---|
196 | #!diff |
---|
197 | --- Version 55 |
---|
198 | +++ Version 56 |
---|
199 | @@ -115,8 +115,9 @@ |
---|
200 | name='TracHelloWorld', version='1.0', |
---|
201 | packages=find_packages(exclude=['*.tests*']), |
---|
202 | - entry_points = """ |
---|
203 | - [trac.plugins] |
---|
204 | - helloworld = myplugs.helloworld |
---|
205 | - """, |
---|
206 | + entry_points = { |
---|
207 | + 'trac.plugins': [ |
---|
208 | + 'helloworld = myplugs.helloworld', |
---|
209 | + ], |
---|
210 | + }, |
---|
211 | ) |
---|
212 | }}} |
---|
213 | }}} |
---|
214 | }}} |
---|
215 | {{{#!td |
---|
216 | '''`#!diff`''' has a particularly nice renderer: |
---|
217 | {{{ |
---|
218 | #!diff |
---|
219 | --- Version 55 |
---|
220 | +++ Version 56 |
---|
221 | @@ -115,8 +115,9 @@ |
---|
222 | name='TracHelloWorld', version='1.0', |
---|
223 | packages=find_packages(exclude=['*.tests*']), |
---|
224 | - entry_points = """ |
---|
225 | - [trac.plugins] |
---|
226 | - helloworld = myplugs.helloworld |
---|
227 | - """, |
---|
228 | + entry_points = { |
---|
229 | + 'trac.plugins': [ |
---|
230 | + 'helloworld = myplugs.helloworld', |
---|
231 | + ], |
---|
232 | + }, |
---|
233 | ) |
---|
234 | }}} |
---|
235 | }}} |
---|
236 | |
---|
237 | Line numbers can be added to code blocks and lines can be highlighted //(since 1.1.2)//. |
---|
238 | {{{ |
---|
239 | {{{#!python lineno=3 marks=3,9-10,16 |
---|
240 | def expand_markup(stream, ctxt=None): |
---|
241 | """A Genshi stream filter for expanding `genshi.Markup` events. |
---|
242 | |
---|
243 | Note: Expansion may not be possible if the fragment is badly |
---|
244 | formed, or partial. |
---|
245 | """ |
---|
246 | for event in stream: |
---|
247 | if isinstance(event[1], Markup): |
---|
248 | try: |
---|
249 | for subevent in HTML(event[1]): |
---|
250 | yield subevent |
---|
251 | except ParseError: |
---|
252 | yield event |
---|
253 | else: |
---|
254 | yield event |
---|
255 | }}} |
---|
256 | }}} |
---|
257 | {{{#!python lineno=3 marks=3,9-10,16 |
---|
258 | def expand_markup(stream, ctxt=None): |
---|
259 | """A Genshi stream filter for expanding `genshi.Markup` events. |
---|
260 | |
---|
261 | Note: Expansion may not be possible if the fragment is badly |
---|
262 | formed, or partial. |
---|
263 | """ |
---|
264 | for event in stream: |
---|
265 | if isinstance(event[1], Markup): |
---|
266 | try: |
---|
267 | for subevent in HTML(event[1]): |
---|
268 | yield subevent |
---|
269 | except ParseError: |
---|
270 | yield event |
---|
271 | else: |
---|
272 | yield event |
---|
273 | }}} |
---|
274 | |
---|
275 | For more processor macros developed and/or contributed by users, visit the [th:WikiStart Trac Hacks] community site. |
---|
276 | |
---|
277 | Developing processors is no different from Wiki macros. In fact, they work the same way, only the usage syntax differs. See WikiMacros#DevelopingCustomMacros for more information. |
---|
278 | |
---|
279 | ---- |
---|
280 | See also: WikiMacros, WikiHtml, WikiRestructuredText, TracSyntaxColoring, WikiFormatting, TracGuide |
---|