Changes between Version 3 and Version 4 of WikiProcessors


Ignore:
Timestamp:
Apr 4, 2012, 2:28:20 PM (13 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WikiProcessors

    v3 v4  
    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 `{{{
    27 ` or on the line just below,
    28 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''):
    2933
    3034{{{
    31 {{{
    32 #!processorname
    33 The lines
    34 that should be processed...
    35 }}}
     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>
    3644}}}
    3745
    38 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 [*]_.
    3952
    40 Besides their content, some Wiki processors can also accept ''parameters'',
    41 which are then given as `key=value` pairs after the processor name,
    42 on the same line. If `value` has to contain space, as it's often the case for
    43 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''):
    4457
    45 As some processors are meant to process Wiki markup, it's quite possible to
    46 ''nest'' processor blocks.
    47 You may want to indent the content of nested blocks for increased clarity,
    48 this extra indentation will be ignored when processing the content.
    49 
    50 
    51 == Examples ==
    52 
    53 ||= Wiki Markup =||= Display =||
    54 {{{
    55 #!td colspan=2 align=center style="border: none"
    56 
    57                 __Example 1__: Inserting raw HTML
    58 }}}
    59 |-----------------------------------------------------------------
    60 {{{
    61 #!td style="border: none"
    62 {{{
    63 {{{
    64 <h1 style="color: grey">This is raw HTML</h1>
    65 }}}
    66 }}}
    67 }}}
    68 {{{
    69 #!td valign=top style="border: none; padding-left: 2em"
    7058{{{
    7159#!html
    72 <h1 style="color: grey">This is raw HTML</h1>
    73 }}}
    74 }}}
    75 |-----------------------------------------------------------------
    76 {{{
    77 #!td colspan=2 align=center style="border: none"
    78 
    79      __Example 2__: Highlighted Python code in a <div> block with custom style
    80 }}}
    81 |-----------------------------------------------------------------
    82 {{{
    83 #!td style="border: none"
    84   {{{
    85   {{{
    86 #!div style="background: #ffd; border: 3px ridge"
    87 
    88   This is an example of embedded "code" block:
    89 
    90     {{{
    91     #!python
    92     def hello():
    93         return "world"
    94    
     60<pre class="wiki">{{{
     61#!c
     62int main(int argc, char *argv[])
     63{
     64  printf("Hello World\n");
     65  return 0;
     66}
     67}}}</pre>
    9568}}}
    9669
    97  
    98 }}}
    99  
    100 }}}
    101 }}}
     70'''Results in:'''
    10271{{{
    103 #!td valign=top style="border: none; padding: 1em"
    104   {{{
    105 #!div style="background: #ffd; border: 3px ridge"
    106 
    107   This is an example of embedded "code" block:
    108 
    109     {{{
    110     #!python
    111     def hello():
    112         return "world"
    113    
     72#!c
     73int main(int argc, char *argv[])
     74{
     75  printf("Hello World\n");
     76  return 0;
     77}
    11478}}}
    11579
    116  
    117 }}}
    118 }}}
    119 |-----------------------------------------------------------------
    120 {{{
    121 #!td colspan=2 align=center style="border: none"
     80----
    12281
    123      __Example 3__: Searching tickets from a wiki page, by keywords.
    124 }}}
    125 |-----------------------------------------------------------------
    126 {{{
    127 #!td style="border: none"
    128   {{{
    129   {{{
    130   #!html
    131   <form action="/query" method="get">
    132   <input type="text" name="keywords" value="~" size="30">
    133   <input type="submit" value="Search by Keywords">
    134   <!-- To control what fields show up use hidden fields
    135   <input type="hidden" name="col" value="id">
    136   <input type="hidden" name="col" value="summary">
    137   <input type="hidden" name="col" value="status">
    138   <input type="hidden" name="col" value="milestone">
    139   <input type="hidden" name="col" value="version">
    140   <input type="hidden" name="col" value="owner">
    141   <input type="hidden" name="col" value="priority">
    142   <input type="hidden" name="col" value="component">
    143   -->
    144   </form>
    145  
    146 }}}
    147  
    148 }}}
    149 }}}
    150 {{{
    151 #!td valign=top style="border: none; padding: 1em"
    152   {{{
    153   #!html
    154   <form action="/query" method="get">
    155   <input type="text" name="keywords" value="~" size="30">
    156   <input type="submit" value="Search by Keywords">
    157   <!-- To control what fields show up use hidden fields
    158   <input type="hidden" name="col" value="id">
    159   <input type="hidden" name="col" value="summary">
    160   <input type="hidden" name="col" value="status">
    161   <input type="hidden" name="col" value="milestone">
    162   <input type="hidden" name="col" value="version">
    163   <input type="hidden" name="col" value="owner">
    164   <input type="hidden" name="col" value="priority">
    165   <input type="hidden" name="col" value="component">
    166   -->
    167   </form>
    168  
    169 }}}
    170 }}}
    17182== Available Processors ==
    172 
    17383The following processors are included in the Trac distribution:
    174 
    175  `#!default` :: Present the text verbatim in a preformatted text block.
    176                 This is the same as specifying ''no'' processor name
    177                 (and no `#!`)
    178  `#!comment` :: Do not process the text in this section (i.e. contents exist
    179                 only in the plain text - not in the rendered page).
    180 
    181 === HTML related ===
    182 
    183  `#!html`        :: Insert custom HTML in a wiki page.
    184  `#!htmlcomment` :: Insert an HTML comment in a wiki page (''since 0.12'').
    185 
    186 Note that `#!html` blocks have to be ''self-contained'',
    187 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.
    188 
    189   `#!div` :: Wrap an arbitrary Wiki content inside a <div> element
    190              (''since 0.11'').
    191  `#!span` :: Wrap an arbitrary Wiki content inside a <span> element
    192              (''since 0.11'').
    193 
    194  `#!td` :: Wrap an arbitrary Wiki content inside a <td> element (''since 0.12'')
    195  `#!th` :: Wrap an arbitrary Wiki content inside a <th> element (''since 0.12'')
    196  `#!tr` :: Can optionally be used for wrapping `#!td` and `#!th` blocks,
    197        either for specifying row attributes of better visual grouping
    198        (''since 0.12'')
    199 
    200 See WikiHtml for example usage and more details about these processors.
    201 
    202 === Other Markups ===
    203 
    204      `#!rst` :: Trac support for Restructured Text. See WikiRestructuredText.
    205  `#!textile` :: Supported if [http://cheeseshop.python.org/pypi/textile Textile]
    206                 is installed.
    207                 See [http://www.textism.com/tools/textile/ a Textile reference].
    208 
     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).
    20990
    21091=== 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
    211105
    212 Trac includes processors to provide inline syntax highlighting:
    213  `#!c` (C), `#!cpp` (C++), `#!python` (Python), `#!perl` (Perl),
    214  `#!ruby` (Ruby), `#!php` (PHP), `#!asp` (ASP), `#!java` (Java),
    215  `#!js` (Javascript), `#!sql (SQL)`, `#!xml` (XML or HTML),
    216  `#!sh` (!Bourne/Bash shell), etc.
     106'''Note:''' ''Trac relies on external software packages for syntax coloring. See TracSyntaxColoring for more info.''
    217107
    218 Trac relies on external software packages for syntax coloring,
    219 like [http://pygments.org Pygments].
    220 
    221 See TracSyntaxColoring for information about which languages
    222 are supported and how to enable support for more languages.
    223 
    224 Note also that by 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:
     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:
    225109{{{
    226110{{{
    … …  
    236120}}}
    237121
    238 The same is valid for all other [TracSyntaxColoring#SyntaxColoringSupport mime types supported].
     122The same is valid for all other mime types supported.
    239123
    240124
    … …  
    244128 * [th:WikiStart Trac Hacks] community site
    245129
    246 Developing processors is no different from Wiki macros.
    247 In fact they work the same way, only the usage syntax differs.
    248 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.
    249133
    250134
    251135----
    252136See also: WikiMacros, WikiHtml, WikiRestructuredText, TracSyntaxColoring, WikiFormatting, TracGuide
    253 
    254