Changes between Initial Version and Version 1 of WikiProcessors


Ignore:
Timestamp:
10/22/08 23:42:59 (6 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WikiProcessors

    v1 v1  
     1= Wiki Processors =
     2
     3Processors 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''.
     4
     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.
     6
     7
     8== Using Processors ==
     9
     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
     14{{{
     15#!html
     16<pre class="wiki">{{{
     17#!html
     18&lt;h1 style="color: orange"&gt;This is raw HTML&lt;/h1&gt;
     19}}}</pre>
     20}}}
     21
     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''):
     33
     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>
     44}}}
     45
     46'''Results in:'''
     47{{{
     48#!rst
     49A header
     50--------
     51This is some **text** with a footnote [*]_.
     52
     53.. [*] This is the footnote.
     54}}}
     55----
     56'''Example 3''' (''inserting a block of C source code in wiki text''):
     57
     58{{{
     59#!html
     60<pre class="wiki">{{{
     61#!c
     62int main(int argc, char *argv[])
     63{
     64  printf("Hello World\n");
     65  return 0;
     66}
     67}}}</pre>
     68}}}
     69
     70'''Results in:'''
     71{{{
     72#!c
     73int main(int argc, char *argv[])
     74{
     75  printf("Hello World\n");
     76  return 0;
     77}
     78}}}
     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:
     109{{{
     110{{{
     111#!text/html
     112<h1>text</h1>
     113}}}
     114}}}
     115
     116The result will be syntax highlighted HTML code:
     117{{{
     118#!text/html
     119<h1>text</h1>
     120}}}
     121
     122The same is valid for all other mime types supported.
     123
     124
     125For more processor macros developed and/or contributed by users, visit:
     126 * [trac:ProcessorBazaar]
     127 * [trac:MacroBazaar]
     128 * [th:WikiStart Trac Hacks] community site
     129
     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.
     133
     134
     135----
     136See also: WikiMacros, WikiHtml, WikiRestructuredText, TracSyntaxColoring, WikiFormatting, TracGuide