Changes between Version 1 and Version 2 of WikiProcessors


Ignore:
Timestamp:
08/27/15 23:20:06 (3 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WikiProcessors

    v1 v2  
    1 = Wiki プロセッサ =
    2 
    3 プロセッサは [TracWiki Trac Wiki エンジン] が、 Wiki 以外のフォーマットを提供するために設計された WikiMacros です。プロセッサは ''ユーザが編集したテキストを処理するマクロ機能'' と考えることができます。
    4 
    5 Trac 内の全ての Wiki テキストにおいて、 [wiki:WikiRestructuredText Restructured Text], [wiki:WikiHtml raw HTML] および [http://www.textism.com/tools/textile/ textile] をプロセッサとして使用することができます。
    6 
    7 == プロセッサを使用する ==
    8 
    9 テキストブロックでプロセッサを使うには、 Wiki のコードブロックを使用し、プロセッサの名前を (Unix 系 OS のスクリプトのように) ''shebang 行'' (#!) に続いて指定します。
    10 
    11 '''例1''' (''Wiki テキストに 生 HTML を挿入する''):
    12 
     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
     5Wiki processors can be used in any Wiki text throughout Trac, such as:
     6 - [#CodeHighlightingSupport syntax highlighting] or for rendering text verbatim
     7 - rendering [#HTMLrelated Wiki markup inside a context], like inside <div> blocks or <span> or within <td> or <th> table cells
     8 - using an alternative markup syntax, like [wiki:WikiHtml raw HTML] and [wiki:WikiRestructuredText Restructured Text] or [http://www.textism.com/tools/textile/ textile]
     9
     10== Using Processors
     11
     12To use a processor on a block of text, first delimit the lines using a Wiki ''code block'':
     13{{{
     14{{{
     15The lines
     16that should be processed...
     17}}}
     18}}}
     19
     20Immediately after the `{{{` or on the line just below, add `#!` followed by the ''processor name'':
     21
     22{{{
     23{{{
     24#!processorname
     25The lines
     26that should be processed...
     27}}}
     28}}}
     29
     30This is the "shebang" notation, familiar to most UNIX users.
     31
     32Besides their content, some Wiki processors can also accept ''parameters'', which are then given as `key=value` pairs after the processor name and on the same line. If `value` has to contain space, as it's often the case for the style parameter, a quoted string can be used (`key="value with space"`).
     33
     34As some processors are meant to process Wiki markup, it's quite possible to ''nest'' processor blocks.
     35You may want to indent the content of nested blocks for increased clarity, this extra indentation will be ignored when processing the content.
     36
     37== Examples
     38
     39||= Wiki Markup =||= Display =||
     40{{{#!td colspan=2 align=center style="border: none"
     41
     42                __Example 1__: Inserting raw HTML
     43}}}
     44|-----------------------------------------------------------------
     45{{{#!td style="border: none"
     46{{{
    1347{{{
    1448#!html
    15 <pre class="wiki">{{{
     49<h1 style="color: grey">This is raw HTML</h1>
     50}}}
     51}}}
     52}}}
     53{{{#!td valign=top style="border: none; padding-left: 2em"
     54{{{
    1655#!html
    17 &lt;h1 style="color: orange"&gt;これは生 HTML です&lt;/h1&gt;
    18 }}}</pre>
    19 }}}
    20 
    21 '''結果、このように表示されます:'''
    22 {{{
    23 #!html
    24 <h1 style="color: orange">これは生 HTML です</h1>
    25 }}}
    26 
    27 ----
    28 
    29 '''例2''' (''Wiki テキストに !ReStructured テキストを挿入する''):
    30 
    31 {{{
    32 #!html
    33 <pre class="wiki">{{{
    34 #!rst
    35 見出し
    36 ------
    37 脚注 [*]_ 付きの **text** です。
    38 
    39 .. [*] ここは脚注。
    40 }}}</pre>
    41 }}}
    42 
    43 '''結果、このように表示されます:'''
    44 {{{
    45 #!rst
    46 見出し
    47 ------
    48 脚注 [*]_ 付きの **text** です。
    49 
    50 .. [*] ここは脚注。
    51 }}}
    52 (訳注: !ReStructuredText は国際化が甘いので、使えないかもしれません)
    53 ----
    54 '''例3''' (''Wiki テキストに C 言語ソースコードブロックを挿入する''):
    55 
    56 {{{
    57 #!html
    58 <pre class="wiki">{{{
    59 #!c
    60 int main(int argc, char *argv[])
    61 {
    62   printf("Hello World\n");
    63   return 0;
    64 }
    65 }}}</pre>
    66 }}}
    67 
    68 '''結果、このように表示されます:'''
    69 {{{
    70 #!c
    71 int main(int argc, char *argv[])
    72 {
    73   printf("Hello World\n");
    74   return 0;
    75 }
    76 }}}
    77 
    78 ----
    79 
    80 == プロセッサ一覧 ==
    81 以下のプロセッサが Trac の配布に含まれています:
    82  * '''html''' -- Wiki ページにカスタム HTML を挿入する。 WikiHtml を参照してください。
    83  * '''rst''' -- Restructured テキスト を Trac で利用可能にする。 WikiRestructuredText を参照してください。
    84  * '''textile''' -- [http://dealmeida.net/projects/textile/ Textile] をインストールすれば利用可能です。 [http://hobix.com/textile/ a Textile reference] を参照。
    85 
    86 上記の Textile のリンクは切れています。 [http://www.textism.com/tools/textile/ このサイト] は動いていて、試しに使ってみることが可能です。
    87 
    88 === ソースコードの強調表示対応 ===
    89 Trac では、以下のプログラミング言語でのインライン [wiki:TracSyntaxColoring シンタックスハイライト] を行うプロセッサが組み込まれています。
    90  * '''c''' -- C
    91  * '''cpp''' -- C++
    92  * '''python''' -- Python
    93  * '''perl''' -- Perl
    94  * '''ruby''' -- Ruby
    95  * '''php''' -- PHP
    96  * '''asp''' --- ASP
    97  * '''sql''' -- SQL
    98  * '''xml''' -- XML
    99 '''Note:''' ''Trac はシンタックスの色付けを、外部のソフトウェアパッケージに依存しています。詳しくは TracSyntaxColoring をご覧下さい。''
    100 
    101 プロセッサとして mime-type が指定されると、ソースコードをブラウズするときと同じく、対応されている言語であれば、シンタックスハイライトを行うことができます。例えば、以下のように書くと:
    102 {{{
     56<h1 style="color: grey">This is raw HTML</h1>
     57}}}
     58}}}
     59|-----------------------------------------------------------------
     60{{{#!td colspan=2 align=center style="border: none"
     61
     62     __Example 2__: Highlighted Python code in a <div> block with custom style
     63}}}
     64|-----------------------------------------------------------------
     65{{{#!td style="border: none"
     66  {{{
     67  {{{#!div style="background: #ffd; border: 3px ridge"
     68
     69  This is an example of embedded "code" block:
     70
     71    {{{
     72    #!python
     73    def hello():
     74        return "world"
     75    }}}
     76
     77  }}}
     78  }}}
     79}}}
     80{{{#!td valign=top style="border: none; padding: 1em"
     81  {{{#!div style="background: #ffd; border: 3px ridge"
     82
     83  This is an example of embedded "code" block:
     84
     85    {{{
     86    #!python
     87    def hello():
     88        return "world"
     89    }}}
     90
     91  }}}
     92}}}
     93|-----------------------------------------------------------------
     94{{{#!td colspan=2 align=center style="border: none"
     95
     96     __Example 3__: Searching tickets from a wiki page, by keywords.
     97}}}
     98|-----------------------------------------------------------------
     99{{{#!td style="border: none"
     100  {{{
     101  {{{
     102  #!html
     103  <form action="/query" method="get"><div>
     104  <input type="text" name="keywords" value="~" size="30"/>
     105  <input type="submit" value="Search by Keywords"/>
     106  <!-- To control what fields show up use hidden fields
     107  <input type="hidden" name="col" value="id"/>
     108  <input type="hidden" name="col" value="summary"/>
     109  <input type="hidden" name="col" value="status"/>
     110  <input type="hidden" name="col" value="milestone"/>
     111  <input type="hidden" name="col" value="version"/>
     112  <input type="hidden" name="col" value="owner"/>
     113  <input type="hidden" name="col" value="priority"/>
     114  <input type="hidden" name="col" value="component"/>
     115  -->
     116  </div></form>
     117  }}}
     118  }}}
     119}}}
     120{{{#!td valign=top style="border: none; padding: 1em"
     121  {{{
     122  #!html
     123  <form action="/query" method="get"><div>
     124  <input type="text" name="keywords" value="~" size="30"/>
     125  <input type="submit" value="Search by Keywords"/>
     126  <!-- To control what fields show up use hidden fields
     127  <input type="hidden" name="col" value="id"/>
     128  <input type="hidden" name="col" value="summary"/>
     129  <input type="hidden" name="col" value="status"/>
     130  <input type="hidden" name="col" value="milestone"/>
     131  <input type="hidden" name="col" value="version"/>
     132  <input type="hidden" name="col" value="owner"/>
     133  <input type="hidden" name="col" value="priority"/>
     134  <input type="hidden" name="col" value="component"/>
     135  -->
     136  </div></form>
     137  }}}
     138}}}
     139
     140== Available Processors
     141
     142The following processors are included in the Trac distribution:
     143
     144|| '''`#!default`''' || Present the text verbatim in a preformatted text block. This is the same as specifying ''no'' processor name (and no `#!`) ||
     145|| '''`#!comment`''' || Do not process the text in this section, i.e. contents exist only in the plain text - not in the rendered page. ||
     146|| '''`#!rtl`''' || Introduce a Right-To-Left block with appropriate CSS direction and styling ''(since 0.12.2)'' ||
     147|||| ||
     148||||= '''[=#HTMLrelated HTML related]''' =||
     149|| '''`#!html`''' || Insert custom HTML in a wiki page. ||
     150|| '''`#!htmlcomment`''' || Insert an HTML comment in a wiki page (''since 0.12''). ||
     151|| || 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.  ||
     152|| '''`#!div`''' || Wrap an arbitrary Wiki content inside a <div> element (''since 0.11''). ||
     153|| '''`#!span`''' || Wrap an arbitrary Wiki content inside a <span> element (''since 0.11''). ||
     154|| '''`#!td`''' || Wrap an arbitrary Wiki content inside a <td> element (''since 0.12'') ||
     155|| '''`#!th`''' || Wrap an arbitrary Wiki content inside a <th> element (''since 0.12'') ||
     156|| '''`#!tr`''' || Can optionally be used for wrapping `#!td` and `#!th` blocks, either for specifying row attributes or better visual grouping (''since 0.12'') ||
     157|| '''`#!table`''' || Can optionally be used for wrapping `#!tr`, `#!td` and `#!th` blocks, for specifying table attributes. One current limitation however is that tables cannot be nested. (''since 0.12'') ||
     158|| || See WikiHtml for example usage and more details about these processors. ||
     159|||| ||
     160||||= '''Other Markups''' =||
     161|| '''`#!rst`''' || Trac support for Restructured Text. See WikiRestructuredText. ||
     162|| '''`#!textile`''' || Supported if [http://cheeseshop.python.org/pypi/textile Textile] is installed. See [http://www.textism.com/tools/textile/ a Textile reference]. ||
     163|||| ||
     164||||= '''[=#CodeHighlightingSupport Code Highlighting Support]''' =||
     165|| '''`#!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. ||
     166|||| ||
     167
     168Using the MIME type as processor, it is possible to syntax-highlight the same languages that are supported when browsing source code.
     169
     170||||= '''MIME Type Processors''' =||
     171{{{#!tr
     172{{{#!td
     173Some examples:
     174 {{{
    103175{{{
    104176#!text/html
    105177<h1>text</h1>
    106178}}}
    107 }}}
    108 
    109 この結果はシンタックスハイライトされた HTML コードになります。対応している全ての mime-type でも、これは同じく有効です。
    110 
    111 
    112 ユーザによるプロセッサマクロの開発やコントリビュート:
    113  * [http://trac.edgewall.org/wiki/ProcessorBazaar ProcessorBazaar]
    114  * [http://trac.edgewall.org/wiki/MacroBazaar MacroBazaar]
    115 
    116 
    117 == 上級トピック: プロセッサマクロを開発する ==
    118 プロセッサの開発は WikiMacros と違いはありません。事実、これらは同じような機能を持ち、シンタックスだけが異なります。詳しくは WikiMacros に記述します。
    119 
    120 '''例:''' (''Restructured テキストプロセッサ''):
    121 {{{
    122 #!python
    123 from docutils.core import publish_string
    124 
    125 def execute(hdf, text, env):
    126     html = publish_string(text, writer_name = 'html')
    127     return html[html.find('<body>')+6:html.find('</body>')].strip()
    128 }}}
     179 }}}
     180}}}
     181{{{#!td
     182The result will be syntax highlighted HTML code:
     183 {{{
     184#!text/html
     185<h1>text</h1>
     186 }}}
     187
     188The same is valid for all other [TracSyntaxColoring#SyntaxColoringSupport mime types supported].
     189}}}
     190}}}
     191{{{#!td
     192 {{{
     193{{{
     194#!diff
     195--- Version 55
     196+++ Version 56
     197@@ -115,8 +115,9 @@
     198     name='TracHelloWorld', version='1.0',
     199     packages=find_packages(exclude=['*.tests*']),
     200-    entry_points = """
     201-        [trac.plugins]
     202-        helloworld = myplugs.helloworld
     203-    """,
     204+    entry_points = {
     205+        'trac.plugins': [
     206+            'helloworld = myplugs.helloworld',
     207+        ],
     208+    },
     209 )
     210}}}
     211 }}}
     212}}}
     213{{{#!td
     214'''`#!diff`''' has a particularly nice renderer:
     215 {{{
     216#!diff
     217--- Version 55
     218+++ Version 56
     219@@ -115,8 +115,9 @@
     220     name='TracHelloWorld', version='1.0',
     221     packages=find_packages(exclude=['*.tests*']),
     222-    entry_points = """
     223-        [trac.plugins]
     224-        helloworld = myplugs.helloworld
     225-    """,
     226+    entry_points = {
     227+        'trac.plugins': [
     228+            'helloworld = myplugs.helloworld',
     229+        ],
     230+    },
     231 )
     232 }}}
     233}}}
     234
     235For more processor macros developed and/or contributed by users, visit the [http://trac-hacks.org/wiki/WikiStart Trac Hacks] community site.
     236
     237Developing processors is no different from Wiki macros. In fact, they work the same way, only the usage syntax differs. See WikiMacros#DevelopingCustomMacros for more information.
    129238
    130239----