+
Wiki Processors
\n
\nProcessors are WikiMacros designed to provide alternative markup
+ formats for the Wiki engine. Processors
+ can be thought of as macro functions to process user-edited text. \n
\n
+ \nWiki processors can be used in any Wiki text throughout Trac, such as:\n
\n
+
Using Processors
\n
\nTo use a processor on a block of
+ text, first delimit the lines using a Wiki code block:\n
\n
+
{{{\nThe lines\nthat should be processed...\n}}}\n
+
\nImmediately after the {{{ or on the line just below, add #!
+ followed by the processor name:\n
\n
+
{{{\n#!processorname\nThe lines\nthat should be processed...\n}}}\n
+
\nThis is the \"shebang\" notation, familiar to most UNIX users.\n
\n
\nBesides
+ 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\").\n
\n
\nAs some
+ processors are meant to process Wiki markup, it's quite possible to nest
+ processor blocks.\nYou may want to indent the content of nested blocks for increased
+ clarity, this extra indentation will be ignored when processing the content.\n
\n
Examples
\n
\n
+ | Wiki Markup |
+ Display \n |
+
+
+
+ \n\nExample 1: Inserting raw
+ HTML\n \n \n
+ |
+
+ \n
+ {{{\n#!html\n<h1 style=\"color: grey\">This is raw HTML</h1>\n}}}\n
+ |
+
+ This is raw HTML\n
+ |
+
+ \n
+ \n\nExample 2: Highlighted
+ Python code in a <div> block with custom style\n \n
+ \n
+ |
+
+ \n
+ {{{#!div style=\"background: #ffd; border: 3px ridge\"\n\nThis is an example of embedded \"code\" block:\n\n {{{\n #!python\n def hello():\n return \"world\"\n }}}\n\n}}}\n
+ |
+
+
+ \nThis is an example of embedded \"code\" block:\n \n
+
+ def hello():\n return \"world\"\n
+
+
+ |
+
+ \n
+ \n\nExample 3: Searching tickets
+ from a wiki page, by keywords.\n \n \n
+ |
+
+ \n
+ {{{\n#!html\n<form action=\"/query\" method=\"get\"><div>\n<input type=\"text\" name=\"keywords\" value=\"~\" size=\"30\"/>\n<input type=\"submit\" value=\"Search by Keywords\"/>\n<!-- To control what fields show up use hidden fields\n<input type=\"hidden\" name=\"col\" value=\"id\"/>\n<input type=\"hidden\" name=\"col\" value=\"summary\"/>\n<input type=\"hidden\" name=\"col\" value=\"status\"/>\n<input type=\"hidden\" name=\"col\" value=\"milestone\"/>\n<input type=\"hidden\" name=\"col\" value=\"version\"/>\n<input type=\"hidden\" name=\"col\" value=\"owner\"/>\n<input type=\"hidden\" name=\"col\" value=\"priority\"/>\n<input type=\"hidden\" name=\"col\" value=\"component\"/>\n-->\n</div></form>\n}}}\n
+ |
+
+ \n
+ |
+
+
\n
Available Processors
\n
\nThe following
+ processors are included in the Trac distribution:\n
\n
\n
+ #!default |
+ Present the text verbatim in a preformatted text block. This is the same as
+ specifying no processor name (and no #!). \n |
+
+
+ #!comment |
+ Do not process the text in this section, i.e. contents exist only in the plain
+ text - not in the rendered page. \n |
+
+
+ #!rtl |
+ Introduce a Right-To-Left block with appropriate CSS direction and styling.
+ (since 0.12.2) \n |
+
+
+ | \n |
+
+
+ | HTML
+ related \n |
+
+
+ #!html |
+ Insert custom HTML in a wiki page. \n |
+
+
+ #!htmlcomment |
+ Insert an HTML comment in a wiki page. (since 0.12) \n |
+
+
+ | |
+ 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. \n |
+
+
+ #!div |
+ Wrap wiki content inside a <div> element. \n |
+
+
+ #!span |
+ Wrap wiki content inside a <span> element. \n |
+
+
+ #!td |
+ Wrap wiki content inside a <td> element. (since 0.12) \n |
+
+
+ #!th |
+ Wrap wiki content inside a <th> element. (since 0.12) \n |
+
+
+ #!tr |
+ Can optionally be used for wrapping #!td and #!th
+ blocks, either for specifying row attributes or better visual grouping.
+ (since 0.12) \n |
+
+
+ #!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) \n
+ |
+
+
+ | |
+ See WikiHtml for example usage
+ and more details about these processors. \n |
+
+
+ | \n |
+
+
+ | Other Markups \n |
+
+
+ #!rst |
+ Trac support for Restructured Text. See WikiRestructuredText. \n |
+
+
+ #!textile |
+ Supported if Textile is installed. See a Textile reference. \n |
+
+
+ | \n |
+
+
+ | Code Highlighting Support
+ \n |
+
+
+ #!c
#!cpp
+ (C++)
#!python
+ #!perl
#!ruby
+
#!php
+ #!asp
#!java
+
#!js (Javascript)
+ #!sql
#!xml
+ (XML or HTML)
#!sh (Bourne/Bash shell)
+
etc.
|
+ Trac includes processors to provide inline syntax highlighting for source code
+ in various languages.
Trac relies on Pygments for
+ syntax coloring.
See TracSyntaxColoring for information
+ about which languages are supported and how to enable support for more
+ languages. \n |
+
+
+ | \n |
+
+
\n
\nSince 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.\n
\n
+ \nUsing the MIME type as processor, it is possible to syntax-highlight the same
+ languages that are supported when browsing source code.\n
\n
\n
+
+ | MIME Type Processors \n |
+
+
+ |
+ \nSome examples:\n \n
+ {{{#!text/html\n<h1>text</h1>\n}}}\n
+ |
+
+ \nThe result will be syntax highlighted HTML code:\n \n
+ \nThe same is valid for all other mime types
+ supported.\n \n
+ |
+
+
+
+ {{{#!diff\n--- Version 55\n+++ Version 56\n@@ -115,8 +115,9 @@\n name='TracHelloWorld', version='1.0',\n packages=find_packages(exclude=['*.tests*']),\n- entry_points = \"\"\"\n- [trac.plugins]\n- helloworld = myplugs.helloworld\n- \"\"\",\n+ entry_points = {\n+ 'trac.plugins': [\n+ 'helloworld = myplugs.helloworld',\n+ ],\n+ },\n )\n}}}\n
+ |
+
+ \n#!diff has a particularly nice renderer:\n
+ \n
+ \n\n \n \n - \n \n \n \n
\n \n \n
+ \n
+
+
+
+ \n \n \n | \n \n \n | \n \n \n \n | \n | \n
+ \n \n \n \n \n \n
+ \n\n \n \n \n \n \n \n | 115 |
+ 115 |
+
+ name='TracHelloWorld', version='1.0',
+ | \n \n \n \n
+
+ \n \n \n \n \n | 116 |
+ 116 |
+
+ packages=find_packages(exclude=['*.tests*']),
+ | \n \n \n \n
+ \n \n\n \n\n \n\n \n\n \n
+
+ \n \n\n \n\n \n\n \n\n \n \n \n \n \n
+ \n | 117 |
+ |
+ entry_points =
+ \"\"\" | \n
+
+ \n | 118 |
+ |
+
+ [trac.plugins] | \n
+
+ \n | 119 |
+ |
+
+ helloworld = myplugs.helloworld |
+ \n
+
+ \n | 120 |
+ |
+ \"\"\",
+ | \n
+ \n \n \n | |
+ 117 |
+ entry_points =
+ { | \n
+
+ \n | |
+ 118 |
+
+ 'trac.plugins': [ | \n
+
+ \n | |
+ 119 |
+
+ 'helloworld =
+ myplugs.helloworld', | \n
+
+ \n | |
+ 120 |
+
+ ], | \n
+
+ \n | |
+ 121 |
+ }, | \n
+ \n \n \n \n\n \n
+
+ \n \n\n \n \n \n \n \n \n | 121
+ |
+ 122 |
+ ) | \n \n \n \n
+ \n \n\n \n\n \n\n \n\n \n \n \n \n
+ \n \n \n \n\n
+ |
+
+
\n
\nLine numbers can be added to code blocks and lines can be highlighted
+ (since 1.1.2).\n
\n
+
{{{#!python lineno=3 marks=3,9-10,16\ndef expand_markup(stream, ctxt=None):\n \"\"\"A Genshi stream filter for expanding `genshi.Markup` events.\n\n Note: Expansion may not be possible if the fragment is badly\n formed, or partial.\n \"\"\"\n for event in stream:\n if isinstance(event[1], Markup):\n try:\n for subevent in HTML(event[1]):\n yield subevent\n except ParseError:\n yield event\n else:\n yield event\n}}}\n
+
+
+
+
+ | Line |
+ |
+
+
+
+
+ | 3 |
+ def expand_markup(stream, ctxt=None): |
+
+
+ | 4 |
+ \"\"\"A Genshi stream filter for expanding
+ `genshi.Markup` events. |
+
+
+ | 5 |
+ |
+
+
+ | 6 |
+ Note: Expansion may not be possible if the
+ fragment is badly |
+
+
+ | 7 |
+ formed, or partial. |
+
+
+ | 8 |
+ \"\"\" |
+
+
+ | 9 |
+ for event in stream: |
+
+
+ | 10 |
+ if isinstance(event[1], Markup): |
+
+
+ | 11 |
+ try: |
+
+
+ | 12 |
+ for subevent in HTML(event[1]): |
+
+
+ | 13 |
+ yield subevent |
+
+
+ | 14 |
+ except ParseError: |
+
+
+ | 15 |
+ yield event |
+
+
+ | 16 |
+ else: |
+
+
+ | 17 |
+ yield event |
+
+
+
+
+
\nFor more processor macros developed and/or contributed by users, visit the Trac
+ Hacks community site.\n
\n
\nDeveloping 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.\n
\n
+
\n
\nSee also: WikiMacros, WikiHtml, WikiRestructuredText, TracSyntaxColoring, WikiFormatting, TracGuide\n
\n
+
![\"Trac](\"/chrome/common/trac_logo_mini.png\"){kind=logo}
14 comments:
\n