Changes between Version 4 and Version 5 of WikiProcessors


Ignore:
Timestamp:
Apr 13, 2010, 3:53:03 AM (10 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WikiProcessors

    v4 v5  
    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 {{{
    60 {{{
    61 <h1 style="color: grey">This is raw HTML</h1>
    62 }}}
    63 }}}
    64 }}}
    65 {{{#!td valign=top style="border: none; padding-left: 2em"
    6658{{{
    6759#!html
    68 <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>
    6968}}}
     69
     70'''Results in:'''
     71{{{
     72#!c
     73int main(int argc, char *argv[])
     74{
     75  printf("Hello World\n");
     76  return 0;
     77}
    7078}}}
    71 |-----------------------------------------------------------------
    72 {{{#!td colspan=2 align=center style="border: none"
    7379
    74      __Example 2__: Highlighted Python code in a <div> block with custom style
    75 }}}
    76 |-----------------------------------------------------------------
    77 {{{#!td style="border: none"
    78   {{{
    79   {{{#!div style="background: #ffd; border: 3px ridge"
     80----
    8081
    81   This is an example of embedded "code" block:
    82 
    83     {{{
    84     #!python
    85     def hello():
    86         return "world"
    87     }}}
    88 
    89   }}}
    90   }}}
    91 }}}
    92 {{{#!td valign=top style="border: none; padding: 1em"
    93   {{{#!div style="background: #ffd; border: 3px ridge"
    94 
    95   This is an example of embedded "code" block:
    96 
    97     {{{
    98     #!python
    99     def hello():
    100         return "world"
    101     }}}
    102 
    103   }}}
    104 }}}
    105 |-----------------------------------------------------------------
    106 {{{#!td colspan=2 align=center style="border: none"
    107 
    108      __Example 3__: Searching tickets from a wiki page, by keywords.
    109 }}}
    110 |-----------------------------------------------------------------
    111 {{{#!td style="border: none"
    112   {{{
    113   {{{
    114   #!html
    115   <form action="/query" method="get">
    116   <input type="text" name="keywords" value="~" size="30">
    117   <input type="submit" value="Search by Keywords">
    118   <!-- To control what fields show up use hidden fields
    119   <input type="hidden" name="col" value="id">
    120   <input type="hidden" name="col" value="summary">
    121   <input type="hidden" name="col" value="status">
    122   <input type="hidden" name="col" value="milestone">
    123   <input type="hidden" name="col" value="version">
    124   <input type="hidden" name="col" value="owner">
    125   <input type="hidden" name="col" value="priority">
    126   <input type="hidden" name="col" value="component">
    127   -->
    128   </form>
    129   }}}
    130   }}}
    131 }}}
    132 {{{#!td valign=top style="border: none; padding: 1em"
    133   {{{
    134   #!html
    135   <form action="/query" method="get">
    136   <input type="text" name="keywords" value="~" size="30">
    137   <input type="submit" value="Search by Keywords">
    138   <!-- To control what fields show up use hidden fields
    139   <input type="hidden" name="col" value="id">
    140   <input type="hidden" name="col" value="summary">
    141   <input type="hidden" name="col" value="status">
    142   <input type="hidden" name="col" value="milestone">
    143   <input type="hidden" name="col" value="version">
    144   <input type="hidden" name="col" value="owner">
    145   <input type="hidden" name="col" value="priority">
    146   <input type="hidden" name="col" value="component">
    147   -->
    148   </form>
    149   }}}
    150 }}}
    15182== Available Processors ==
    152 
    15383The following processors are included in the Trac distribution:
    154 
    155  `#!default` :: Present the text verbatim in a preformatted text block.
    156                 This is the same as specifying ''no'' processor name
    157                 (and no `#!`)
    158  `#!comment` :: Do not process the text in this section (i.e. contents exist
    159                 only in the plain text - not in the rendered page).
    160 
    161 === HTML related ===
    162 
    163  `#!html`        :: Insert custom HTML in a wiki page.
    164  `#!htmlcomment` :: Insert an HTML comment in a wiki page (''since 0.12'').
    165 
    166 Note that `#!html` blocks have to be ''self-contained'',
    167 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.
    168 
    169   `#!div` :: Wrap an arbitrary Wiki content inside a <div> element
    170              (''since 0.11'').
    171  `#!span` :: Wrap an arbitrary Wiki content inside a <span> element
    172              (''since 0.11'').
    173 
    174  `#!td` :: Wrap an arbitrary Wiki content inside a <td> element (''since 0.12'')
    175  `#!th` :: Wrap an arbitrary Wiki content inside a <th> element (''since 0.12'')
    176  `#!tr` :: Can optionally be used for wrapping `#!td` and `#!th` blocks,
    177        either for specifying row attributes of better visual grouping
    178        (''since 0.12'')
    179 
    180 See WikiHtml for example usage and more details about these processors.
    181 
    182 === Other Markups ===
    183 
    184      `#!rst` :: Trac support for Restructured Text. See WikiRestructuredText.
    185  `#!textile` :: Supported if [http://cheeseshop.python.org/pypi/textile Textile]
    186                 is installed.
    187                 See [http://www.textism.com/tools/textile/ a Textile reference].
    188 
     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).
    18990
    19091=== 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
    191105
    192 Trac includes processors to provide inline syntax highlighting:
    193  `#!c` (C), `#!cpp` (C++), `#!python` (Python), `#!perl` (Perl),
    194  `#!ruby` (Ruby), `#!php` (PHP), `#!asp` (ASP), `#!java` (Java),
    195  `#!js` (Javascript), `#!sql (SQL)`, `#!xml` (XML or HTML),
    196  `#!sh` (!Bourne/Bash shell), etc.
     106'''Note:''' ''Trac relies on external software packages for syntax coloring. See TracSyntaxColoring for more info.''
    197107
    198 Trac relies on external software packages for syntax coloring,
    199 like [http://pygments.org Pygments].
    200 
    201 See TracSyntaxColoring for informations about which languages
    202 are supported and how to enable support for more languages.
    203 
    204 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:
    205109{{{
    206110{{{
     
    216120}}}
    217121
    218 The same is valid for all other [TracSyntaxColoring#SyntaxColoringSupport mime types supported].
     122The same is valid for all other mime types supported.
    219123
    220124
     
    224128 * [th:WikiStart Trac Hacks] community site
    225129
    226 Developing processors is no different from Wiki macros.
    227 In fact they work the same way, only the usage syntax differs.
    228 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.
    229133
    230134
    231135----
    232136See also: WikiMacros, WikiHtml, WikiRestructuredText, TracSyntaxColoring, WikiFormatting, TracGuide
    233 

Search

Context Navigation

ZOO Sponsors

http://www.zoo-project.org/trac/chrome/site/img/geolabs-logo.pnghttp://www.zoo-project.org/trac/chrome/site/img/neogeo-logo.png http://www.zoo-project.org/trac/chrome/site/img/apptech-logo.png http://www.zoo-project.org/trac/chrome/site/img/3liz-logo.png http://www.zoo-project.org/trac/chrome/site/img/gateway-logo.png

Become a sponsor !

Knowledge partners

http://www.zoo-project.org/trac/chrome/site/img/ocu-logo.png http://www.zoo-project.org/trac/chrome/site/img/gucas-logo.png http://www.zoo-project.org/trac/chrome/site/img/polimi-logo.png http://www.zoo-project.org/trac/chrome/site/img/fem-logo.png http://www.zoo-project.org/trac/chrome/site/img/supsi-logo.png http://www.zoo-project.org/trac/chrome/site/img/cumtb-logo.png

Become a knowledge partner

Related links

http://zoo-project.org/img/ogclogo.png http://zoo-project.org/img/osgeologo.png