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''.
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_.
Wiki processors can be used in any Wiki text throughout Trac, such as:
Wiki processors can be used in any Wiki text throughout Trac, such as:
- [#CodeHighlightingSupport syntax highlighting] or for rendering text verbatim
- [#CodeHighlightingSupport syntax highlighting] or for rendering text verbatim
- rendering [#HTMLrelated Wiki markup inside a context], like inside <div> blocks or <span> or within <td> or <th> table cells
- rendering [#HTMLrelated Wiki markup inside a context], like inside <div> blocks or <span> or within <td> or <th> table cells
- using an alternative markup syntax, like [WikiHtml raw HTML] and [WikiRestructuredText Restructured Text] or [http://www.textism.com/tools/textile/ textile]
- using an alternative markup syntax, like [WikiHtml raw HTML] and [WikiRestructuredText Restructured Text] or [textile](http://www.textism.com/tools/textile/)
== Using Processors
== Using Processors
To use a processor on a block of text, first delimit the lines using a Wiki ''code block'':
To use a processor on a block of text, first delimit the lines using a Wiki _code block_:
{{{
```
{{{
{{{
The lines
The lines
that should be processed...
that should be processed...
}}}
```
}}}
}}}
Immediately after the `{{{` or on the line just below, add `#!` followed by the ''processor name'':
Immediately after the `{{{` or on the line just below, add `#!` followed by the _processor name_:
{{{
```
{{{
{{{
#!processorname
#!processorname
The lines
The lines
that should be processed...
that should be processed...
}}}
```
}}}
}}}
This is the "shebang" notation, familiar to most UNIX users.
This is the "shebang" notation, familiar to most UNIX users.
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"`).
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"`).
As some processors are meant to process Wiki markup, it's quite possible to ''nest'' processor blocks.
As some processors are meant to process Wiki markup, it's quite possible to _nest_ processor blocks.
You may want to indent the content of nested blocks for increased clarity, this extra indentation will be ignored when processing the content.
You may want to indent the content of nested blocks for increased clarity, this extra indentation will be ignored when processing the content.
|| '''`#!rtl`''' || Introduce a Right-To-Left block with appropriate CSS direction and styling. ''(since 0.12.2)'' ||
| **`#!comment`** | Do not process the text in this section, i.e. contents exist only in the plain text - not in the rendered page. |
|||| ||
| **`#!rtl`** | Introduce a Right-To-Left block with appropriate CSS direction and styling. _(since 0.12.2)_ |
||||= '''[=#HTMLrelated HTML related]''' =||
|| |
|| '''`#!html`''' || Insert custom HTML in a wiki page. ||
||= **[=#HTMLrelated HTML related]** =|
|| '''`#!htmlcomment`''' || Insert an HTML comment in a wiki page. (''since 0.12'') ||
| **`#!html`** | Insert custom HTML in a wiki page. |
|| || 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. ||
| **`#!htmlcomment`** | Insert an HTML comment in a wiki page. (_since 0.12_) |
|| '''`#!div`''' || Wrap wiki content inside a <div> element. ||
| | 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. |
|| '''`#!span`''' || Wrap wiki content inside a <span> element. ||
| **`#!div`** | Wrap wiki content inside a <div> element. |
|| '''`#!td`''' || Wrap wiki content inside a <td> element. (''since 0.12'') ||
| **`#!span`** | Wrap wiki content inside a <span> element. |
|| '''`#!th`''' || Wrap wiki content inside a <th> element. (''since 0.12'') ||
| **`#!td`** | Wrap wiki content inside a <td> element. (_since 0.12_) |
|| '''`#!tr`''' || Can optionally be used for wrapping `#!td` and `#!th` blocks, either for specifying row attributes or better visual grouping. (''since 0.12'') ||
| **`#!th`** | Wrap wiki content inside a <th> element. (_since 0.12_) |
|| '''`#!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'') ||
| **`#!tr`** | Can optionally be used for wrapping `#!td` and `#!th` blocks, either for specifying row attributes or better visual grouping. (_since 0.12_) |
|| || See WikiHtml for example usage and more details about these processors. ||
| **`#!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_) |
|||| ||
| | See WikiHtml for example usage and more details about these processors. |
||||= '''Other Markups''' =||
|| |
|| '''`#!rst`''' || Trac support for Restructured Text. See WikiRestructuredText. ||
||= **Other Markups** =|
|| '''`#!textile`''' || Supported if [http://cheeseshop.python.org/pypi/textile Textile] is installed. See [http://www.textism.com/tools/textile/ a Textile reference]. ||
| **`#!rst`** | Trac support for Restructured Text. See WikiRestructuredText. |
|||| ||
| **`#!textile`** | Supported if [Textile](http://cheeseshop.python.org/pypi/textile) is installed. See [a Textile reference](http://www.textism.com/tools/textile/). |
|| '''`#!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 [http://pygments.org Pygments] for syntax coloring. [[BR]] [[BR]] See TracSyntaxColoring for information about which languages are supported and how to enable support for more languages. ||
|| Trac includes processors to provide inline syntax highlighting for source code in various languages.
Trac relies on [Pygments](http://pygments.org) for syntax coloring.
See TracSyntaxColoring for information about which languages are supported and how to enable support for more languages. ||
|| |
||-|
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.
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.
Using the MIME type as processor, it is possible to syntax-highlight the same languages that are supported when browsing source code.
Using the MIME type as processor, it is possible to syntax-highlight the same languages that are supported when browsing source code.
||||= '''MIME Type Processors''' =||
||= **MIME Type Processors** =|
{{{#!tr
||----------------------------|
```
{{{#!td
{{{#!td
Some examples:
Some examples:
{{{
{{{
{{{#!text/html
{{{#!text/html
<h1>text</h1>
<h1>text</h1>
```
}}}
}}}
}}}
}}}
}}}
```
{{{#!td
The result will be syntax highlighted HTML code:
The result will be syntax highlighted HTML code:
{{{#!text/html
{{{#!text/html
<h1>text</h1>
<h1>text</h1>
}}}
}}}
The same is valid for all other [TracSyntaxColoring#SyntaxColoringSupport mime types supported].
The same is valid for all other [TracSyntaxColoring#SyntaxColoringSupport mime types supported].
```
}}}
}}}
}}}
```
{{{#!td
{{{
{{{
{{{#!diff
{{{#!diff
--- Version 55
--- Version 55
...
@@ -206,11 +227,11 @@ The same is valid for all other [TracSyntaxColoring#SyntaxColoringSupport mime t
...
@@ -206,11 +227,11 @@ The same is valid for all other [TracSyntaxColoring#SyntaxColoringSupport mime t
+ ],
+ ],
+ },
+ },
)
)
```
}}}
}}}
}}}
}}}
}}}
```
{{{#!td
**`#!diff`** has a particularly nice renderer:
'''`#!diff`''' has a particularly nice renderer:
{{{#!diff
{{{#!diff
--- Version 55
--- Version 55
+++ Version 56
+++ Version 56
...
@@ -228,10 +249,10 @@ The same is valid for all other [TracSyntaxColoring#SyntaxColoringSupport mime t
...
@@ -228,10 +249,10 @@ The same is valid for all other [TracSyntaxColoring#SyntaxColoringSupport mime t
+ },
+ },
)
)
}}}
}}}
}}}
```
Line numbers can be added to code blocks and lines can be highlighted //(since 1.1.2)//.
Line numbers can be added to code blocks and lines can be highlighted //(since 1.1.2)//.
{{{
```
{{{#!python lineno=3 marks=3,9-10,16
{{{#!python lineno=3 marks=3,9-10,16
def expand_markup(stream, ctxt=None):
def expand_markup(stream, ctxt=None):
"""A Genshi stream filter for expanding `genshi.Markup` events.
"""A Genshi stream filter for expanding `genshi.Markup` events.
For more processor macros developed and/or contributed by users, visit the [https://trac-hacks.org Trac Hacks] community site.
For more processor macros developed and/or contributed by users, visit the [Trac Hacks](https://trac-hacks.org) community site.
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.
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.
