Changes between Version 1 and Version 2 of WikiProcessors


Ignore:
Timestamp:
Jul 17, 2008 10:45:00 AM (12 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WikiProcessors

    v1 v2  
    33Processors 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''.  
    44 
    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] 
     5The 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. 
    136 
    147 
    158== Using Processors == 
    169 
    17 To use a processor on a block of text, first delimit the lines using 
    18 a Wiki ''code block'': 
     10To 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 
    1914{{{ 
    20 {{{ 
    21 The lines 
    22 that should be processed... 
    23 }}} 
     15#!html 
     16<pre class="wiki">{{{ 
     17#!html 
     18&lt;h1 style="color: orange"&gt;This is raw HTML&lt;/h1&gt; 
     19}}}</pre> 
    2420}}} 
    2521 
    26 Immediately after the `{{{` or on the line just below,  
    27 add `#!` followed by the ''processor name''. 
     22'''Results in:''' 
     23{{{ 
     24#!html 
     25<h1 style="color: orange">This is raw HTML</h1> 
     26}}} 
     27 
     28Note 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''): 
    2833 
    2934{{{ 
    30 {{{ 
    31 #!processorname 
    32 The lines 
    33 that should be processed... 
    34 }}} 
     35#!html 
     36<pre class="wiki">{{{ 
     37#!rst 
     38A header 
     39-------- 
     40This is some **text** with a footnote [*]_. 
     41 
     42.. [*] This is the footnote. 
     43}}}</pre> 
    3544}}} 
    3645 
    37 This is the "shebang" notation, familiar to most UNIX users. 
     46'''Results in:''' 
     47{{{ 
     48#!rst 
     49A header 
     50-------- 
     51This is some **text** with a footnote [*]_. 
    3852 
    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"`). 
     53.. [*] This is the footnote. 
     54}}} 
     55---- 
     56'''Example 3''' (''inserting a block of C source code in wiki text''): 
    4357 
    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 {{{ 
    6058{{{ 
    6159#!html 
    62 <h1 style="color: grey">This is raw HTML</h1> 
     60<pre class="wiki">{{{ 
     61#!c 
     62int main(int argc, char *argv[]) 
     63{ 
     64  printf("Hello World\n"); 
     65  return 0; 
     66} 
     67}}}</pre> 
    6368}}} 
     69 
     70'''Results in:''' 
     71{{{ 
     72#!c 
     73int main(int argc, char *argv[]) 
     74{ 
     75  printf("Hello World\n"); 
     76  return 0; 
     77} 
    6478}}} 
    65 }}} 
    66 {{{#!td valign=top style="border: none; padding-left: 2em" 
     79 
     80---- 
     81 
     82== Available Processors == 
     83The following processors are included in the Trac distribution: 
     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 
     91=== Code Highlighting Support === 
     92Trac includes processors to provide inline [wiki:TracSyntaxColoring syntax highlighting] for the following languages: 
     93 * '''c''' -- C 
     94 * '''cpp''' -- C++ 
     95 * '''python''' -- Python 
     96 * '''perl''' -- Perl 
     97 * '''ruby''' -- Ruby 
     98 * '''php''' -- PHP 
     99 * '''asp''' -- ASP 
     100 * '''java''' -- Java 
     101 * '''js''' -- Javascript 
     102 * '''sql''' -- SQL 
     103 * '''xml''' -- XML 
     104 * '''sh''' -- Bourne/Bash shell 
     105 
     106'''Note:''' ''Trac relies on external software packages for syntax coloring. See TracSyntaxColoring for more info.'' 
     107 
     108By 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: 
    67109{{{ 
    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 ||||= '''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  {{{ 
    183110{{{ 
    184111#!text/html 
    185112<h1>text</h1> 
    186113}}} 
    187  }}} 
    188114}}} 
    189 {{{#!td 
     115 
    190116The result will be syntax highlighted HTML code: 
    191  {{{ 
     117{{{ 
    192118#!text/html 
    193119<h1>text</h1> 
    194  }}} 
     120}}} 
    195121 
    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 }}} 
     122The same is valid for all other mime types supported. 
     123 
    242124 
    243125For more processor macros developed and/or contributed by users, visit:  
    244126 * [trac:ProcessorBazaar] 
    245127 * [trac:MacroBazaar] 
    246  * [http://trac-hacks.org Trac Hacks] community site 
     128 * [th:WikiStart Trac Hacks] community site 
    247129 
    248 Developing processors is no different from Wiki macros.  
    249 In fact they work the same way, only the usage syntax differs.  
    250 See WikiMacros#DevelopingCustomMacros for more information. 
     130 
     131== Advanced Topics: Developing Processor Macros == 
     132Developing processors is no different from Wiki macros. In fact they work the same way, only the usage syntax differs. See WikiMacros for more information. 
    251133 
    252134