Edgewall Software

Changes between Version 44 and Version 45 of WikiProcessors


Ignore:
Timestamp:
Apr 10, 2010, 7:43:21 PM (14 years ago)
Author:
Christian Boos
Comment:

copied from 0.12/WikiProcessors@6

Legend:

Unmodified
Added
Removed
Modified

  • WikiProcessors

    v44 v45  
     1** Note: this page documents the 0.12 version of Trac, see [[0.11/WikiProcessors]] if you need the previous version **
    12= Wiki Processors =
    23
    34Processors 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''.
    45
    5 The 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.
     6Wiki processors can be used in any Wiki text throughout Trac,
     7for various different purposes, like:
     8 - [#CodeHighlightingSupport syntax highlighting] or for rendering text verbatim,
     9 - rendering [#HTMLrelated Wiki markup inside a context],
     10   like inside <div> blocks or <span> or within <td> or <th> table cells,
     11 - using an alternative markup syntax, like [wiki:WikiHtml raw HTML] and
     12   [wiki:WikiRestructuredText Restructured Text],
     13   or [http://www.textism.com/tools/textile/ textile]
    614
    715
    816== Using Processors ==
    917
    10 To 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 
    14 {{{
     18To use a processor on a block of text, first delimit the lines using
     19a Wiki ''code block'':
     20{{{
     21{{{
     22The lines
     23that should be processed...
     24}}}
     25}}}
     26
     27Immediately after the `{{{` or on the line just below,
     28add `#!` followed by the ''processor name''.
     29
     30{{{
     31{{{
     32#!processorname
     33The lines
     34that should be processed...
     35}}}
     36}}}
     37
     38This is the "shebang" notation, familiar to most UNIX users.
     39
     40Besides their content, some Wiki processors can also accept ''parameters'',
     41which are then given as `key=value` pairs after the processor name,
     42on the same line. If `value` has to contain space, as it's often the case for
     43the style parameter, a quoted string can be used (`key="value with space"`).
     44
     45As some processors are meant to process Wiki markup, it's quite possible to
     46''nest'' processor blocks.
     47You may want to indent the content of nested blocks for increased clarity,
     48this extra indentation will be ignored when processing the content.
     49
     50
     51== Examples ==
     52
     53||= Wiki Markup =||= Display =||
     54{{{#!td colspan=2 align=center style="border: none"
     55
     56                __Example 1__: Inserting raw HTML
     57}}}
     58|-----------------------------------------------------------------
     59{{{#!td style="border: none"
     60{{{
     61{{{
     62<h1 style="color: grey">This is raw HTML</h1>
     63}}}
     64}}}
     65}}}
     66{{{#!td valign=top style="border: none; padding-left: 2em"
    1567{{{
    1668#!html
    17 <h1 style="color: orange">This is raw HTML</h1>
    18 }}}
    19 }}}
    20 
    21 '''Results in:'''
    22 {{{
    23 #!html
    24 <h1 style="color: orange">This is raw HTML</h1>
    25 }}}
    26 
    27 Note 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).
    28 
    29 ----
    30 
    31 '''Example 2''' (''inserting Restructured Text in wiki text''):
    32 
    33 {{{
    34 {{{
    35 #!rst
    36 A header
    37 --------
    38 This is some **text** with a footnote [*]_.
    39 
    40 .. [*] This is the footnote.
    41 }}}
    42 }}}
    43 
    44 '''Results in:'''
    45 {{{
    46 #!rst
    47 A header
    48 --------
    49 This is some **text** with a footnote [*]_.
    50 
    51 .. [*] This is the footnote.
    52 }}}
    53 ----
    54 '''Example 3''' (''inserting a block of C source code in wiki text''):
    55 
    56 {{{
    57 {{{
    58 #!c
    59 int main(int argc, char *argv[])
    60 {
    61   printf("Hello World\n");
    62   return 0;
    63 }
    64 }}}
    65 }}}
    66 
    67 '''Results in:'''
    68 {{{
    69 #!c
    70 int main(int argc, char *argv[])
    71 {
    72   printf("Hello World\n");
    73   return 0;
    74 }
    75 }}}
    76 
    77 ----
    78 '''Example 4''' (''Searching from a wiki page by custom field. Allows user to reuse most common searches on a wiki page''):
    79 
    80 {{{
    81 {{{
    82 #!html
    83 <form action="/query" method="get">
    84 <input type="text" name="keywords" value="~" size="30"> <input type="submit" value="Search by Keywords#">
    85 <!-- To control what fields show up use hidden fields
    86 <input type="hidden" name="col" value="id">
    87 <input type="hidden" name="col" value="summary">
    88 <input type="hidden" name="col" value="status">
    89 <input type="hidden" name="col" value="milestone">
    90 <input type="hidden" name="col" value="version">
    91 <input type="hidden" name="col" value="owner">
    92 <input type="hidden" name="col" value="priority">
    93 <input type="hidden" name="col" value="component">
    94 -->
    95 </form>
    96 }}}
    97 }}}
    98 
    99 
    100 ''' Result:'''
    101 {{{
    102 #!html
    103 <form action="/query" method="get">
    104 <input type="text" name="keywords" value="~" size="30"> <input type="submit" value="Search by Keywords#">
    105 <!-- To control what fields show up use hidden fields
    106 <input type="hidden" name="col" value="id">
    107 <input type="hidden" name="col" value="summary">
    108 <input type="hidden" name="col" value="status">
    109 <input type="hidden" name="col" value="milestone">
    110 <input type="hidden" name="col" value="version">
    111 <input type="hidden" name="col" value="owner">
    112 <input type="hidden" name="col" value="priority">
    113 <input type="hidden" name="col" value="component">
    114 -->
    115 </form>
    116 }}}
    117 
    118 
    119 ----
    120 
     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">
     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  </form>
     130  }}}
     131  }}}
     132}}}
     133{{{#!td valign=top style="border: none; padding: 1em"
     134  {{{
     135  #!html
     136  <form action="/query" method="get">
     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  </form>
     150  }}}
     151}}}
    121152== Available Processors ==
     153
    122154The following processors are included in the Trac distribution:
    123  * '''html''' -- Insert custom HTML in a wiki page. See WikiHtml.
    124  * '''div''' -- Wrap an arbitrary Wiki content in a <div> element (''since 0.11''). See WikiHtml.
    125  * '''span''' -- Wrap an arbitrary Wiki content in a <span> element (''since 0.11''). See also WikiHtml.
    126  * '''rst''' -- Trac support for Restructured Text. See WikiRestructuredText.
    127  * '''textile''' -- Supported if [http://cheeseshop.python.org/pypi/textile Textile] is installed. See [http://www.textism.com/tools/textile/ a Textile reference].
    128  * '''comment''' -- Do not process the text in this section (i.e. contents exist only in the plain text that can be viewed when editing the wiki page content - not in the rendered page).
    129  * '''diff''' -- Pretty print patches and diffs.
     155
     156 `#!default` :: Present the text verbatim in a preformatted text block.
     157                This is the same as specifying ''no'' processor name
     158                (and no `#!`)
     159 `#!comment` :: Do not process the text in this section (i.e. contents exist
     160                only in the plain text - not in the rendered page).
     161
     162=== HTML related ===
     163
     164 `#!html`        :: Insert custom HTML in a wiki page.
     165 `#!htmlcomment` :: Insert an HTML comment in a wiki page (''since 0.12'').
     166
     167Note that `#!html` blocks have to be ''self-contained'',
     168i.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.
     169
     170  `#!div` :: Wrap an arbitrary Wiki content inside a <div> element
     171             (''since 0.11'').
     172 `#!span` :: Wrap an arbitrary Wiki content inside a <span> element
     173             (''since 0.11'').
     174
     175 `#!td` :: Wrap an arbitrary Wiki content inside a <td> element (''since 0.12'')
     176 `#!th` :: Wrap an arbitrary Wiki content inside a <th> element (''since 0.12'')
     177 `#!tr` :: Can optionally be used for wrapping `#!td` and `#!th` blocks,
     178       either for specifying row attributes of better visual grouping
     179       (''since 0.12'')
     180
     181See WikiHtml for example usage and more details about these processors.
     182
     183=== Other Markups ===
     184
     185     `#!rst` :: Trac support for Restructured Text. See WikiRestructuredText.
     186 `#!textile` :: Supported if [http://cheeseshop.python.org/pypi/textile Textile]
     187                is installed.
     188                See [http://www.textism.com/tools/textile/ a Textile reference].
     189
    130190
    131191=== Code Highlighting Support ===
    132 Trac includes processors to provide inline [wiki:TracSyntaxColoring syntax highlighting] for the following languages:
    133  * '''c''' -- C
    134  * '''cpp''' -- C++
    135  * '''csharp''' --- C#
    136  * '''python''' -- Python
    137  * '''perl''' -- Perl
    138  * '''ruby''' -- Ruby
    139  * '''php''' -- PHP
    140  * '''asp''' -- ASP
    141  * '''java''' -- Java
    142  * '''js''' -- Javascript
    143  * '''sql''' -- SQL
    144  * '''xml''' -- XML
    145  * '''sh''' -- Bourne/Bash shell
    146 
    147 '''Note:''' ''Trac relies on external software packages for syntax coloring. See TracSyntaxColoring for more info.''
    148 
    149 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:
     192
     193Trac includes processors to provide inline syntax highlighting:
     194 `#!c` (C), `#!cpp` (C++), `#!python` (Python), `#!perl` (Perl),
     195 `#!ruby` (Ruby), `#!php` (PHP), `#!asp` (ASP), `#!java` (Java),
     196 `#!js` (Javascript), `#!sql (SQL)`, `#!xml` (XML or HTML),
     197 `#!sh` (!Bourne/Bash shell), etc.
     198
     199Trac relies on external software packages for syntax coloring,
     200like [http://pygments.org Pygments].
     201
     202See TracSyntaxColoring for informations about which languages
     203are supported and how to enable support for more languages.
     204
     205Note 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:
    150206{{{
    151207{{{
    … …  
    169225 * [th:WikiStart Trac Hacks] community site
    170226
    171 
    172 == Advanced Topics: Developing Processor Macros ==
    173 Developing processors is no different from Wiki macros. In fact they work the same way, only the usage syntax differs. See WikiMacros for more information.
     227Developing processors is no different from Wiki macros.
     228In fact they work the same way, only the usage syntax differs.
     229See WikiMacros#DevelopingCustomMacros for more information.
    174230
    175231