Changes between Version 3 and Version 4 of WikiProcessors


Ignore:
Timestamp:
Dec 30, 2016, 2:54:47 AM (8 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WikiProcessors

    v3 v4  
    1 = Wiki プロセッサ = #WikiProcessors
    2 
    3 プロセッサは [WikiMacros Wiki マクロ] の一種です。 [TracWiki Trac Wiki エンジン] 以外のマークアップフォーマットを使用するために設計されています。プロセッサは ''ユーザが編集したテキストを処理するマクロ機能'' と考えることができます。
    4 
    5 Trac 内の全ての Wiki テキストにおいて、 Wiki プロセッサを使用することができます。
    6 例えば、以下に述べる様々な用途で使用することができます:
    7  - [#CodeHighlightingSupport シンタックスハイライト] またはテキストを逐語的にレンダリングする
    8  -  <div> ブロックや <span> や <td>, <th> のテーブルのセルの内容など
    9    [#HTMLrelated コンテキスト内の Wiki のマークアップ] をレンダリングする
    10  - [wiki:WikiHtml HTML] や
    11    [wiki:WikiRestructuredText Restructured テキスト]
    12    または [http://www.textism.com/tools/textile/ textile] のシンタックスをマークアップの代替手段として使用する
    13 
    14 
    15 == プロセッサを使用する == #UsingProcessors
    16 
    17 テキストブロック上に Wiki プロセッサを適用するには、
    18 最初のデリミタとして Wiki の ''コードブロック'' を使用します:
    19 {{{
    20 {{{
    21 これらの行は
    22 処理されるでしょう...
    23 }}}
    24 }}}
    25 
    26 `{{{` のすぐ後または直後の行に,
    27 `#!` に続けて ''プロセッサ名'' を追加します。
    28 
    29 {{{
    30 {{{
    31 #!プロセッサ名
    32 これらの行は
    33 処理されるでしょう...
    34 }}}
    35 }}}
    36 
    37 これはほとんどの UNIX ユーザにはおなじみである "shebang" を用いた表記法です。
    38 
    39 これらの内容に加えて、いくつかの Wiki プロセッサでは、
    40 プロセッサ名に続けて同じ行に、 `key=value` のペアを書くことによって、
    41 ''パラメータ'' を許容するものがあります。もし、 `value` にスペースが含まれるケースがたびたび起こるようであれば、
    42 クオテーションで囲んだ文字列を使用することができます (`key="スペースが含まれている文字列"`) 。
    43 
    44 いくつかのプロセッサは Wiki のマークアップを処理することを意味するので、
    45 プロセッサのブロックを ''ネスト'' させることができます。
    46 可読性を向上させるためにネストしたブロックの内容をインデントさせたいと思うかもしれません。
    47 この種のインデントは中身を処理する際に無視されます。
    48 
    49 
    50 == 例 ==
    51 
    52 ||= Wiki マークアップ =||= 表示 =||
     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 [WikiHtml raw HTML] and [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 =||
    5340{{{#!td colspan=2 align=center style="border: none"
    5441
    55                 __例 1__: HTML を挿入する
     42                __Example 1__: Inserting raw HTML
    5643}}}
    5744|-----------------------------------------------------------------
    … …  
    6047{{{
    6148#!html
    62 <h1 style="color: grey">HTML テスト</h1>
     49<h1 style="color: grey">This is raw HTML</h1>
    6350}}}
    6451}}}
    … …  
    6754{{{
    6855#!html
    69 <h1 style="color: grey">HTML テスト</h1>
     56<h1 style="color: grey">This is raw HTML</h1>
    7057}}}
    7158}}}
    … …  
    7360{{{#!td colspan=2 align=center style="border: none"
    7461
    75      __例 2__: <div> ブロック内のカスタマイズしたスタイルシートでハイライトした Python のコード
     62     __Example 2__: Highlighted Python code in a <div> block with custom style
    7663}}}
    7764|-----------------------------------------------------------------
    … …  
    8067  {{{#!div style="background: #ffd; border: 3px ridge"
    8168
    82   これは 埋め込まれた "コード" ブロックの例です:
     69  This is an example of embedded "code" block:
    8370
    8471    {{{
    … …  
    9481  {{{#!div style="background: #ffd; border: 3px ridge"
    9582
    96   これは 埋め込まれた "コード" ブロックの例です:
     83  This is an example of embedded "code" block:
    9784
    9885    {{{
    … …  
    10794{{{#!td colspan=2 align=center style="border: none"
    10895
    109      __例 3__: Wiki ページでチケットのキーワード検索を行なう
     96     __Example 3__: Searching tickets from a wiki page, by keywords.
    11097}}}
    11198|-----------------------------------------------------------------
    … …  
    116103  <form action="/query" method="get"><div>
    117104  <input type="text" name="keywords" value="~" size="30"/>
    118   <input type="submit" value="キーワードで検索"/>
     105  <input type="submit" value="Search by Keywords"/>
    119106  <!-- To control what fields show up use hidden fields
    120107  <input type="hidden" name="col" value="id"/>
    … …  
    136123  <form action="/query" method="get"><div>
    137124  <input type="text" name="keywords" value="~" size="30"/>
    138   <input type="submit" value="キーワードで検索"/>
     125  <input type="submit" value="Search by Keywords"/>
    139126  <!-- To control what fields show up use hidden fields
    140127  <input type="hidden" name="col" value="id"/>
    … …  
    150137  }}}
    151138}}}
    152 == プロセッサ一覧 == #AvailableProcessors
    153 
    154 以下のプロセッサが Trac の配布に含まれています:
    155 
    156 || '''`#!default`''' || フォーマット済みのテキストブロック内でテキストを逐語的に表示する。これはプロセッサ名を指定 ''しない'' のと同じです (さらに `#!` を指定しないのと同じです)。 ||
    157 || '''`#!comment`''' || このセクション内のテキストを処理しません (つまり、このセクションの内容はプレインテキスト内にのみ存在します - レンダリングしたページには表示されません)。 ||
    158 |||| ||
    159 ||||= '''HTML 関連''' =||
    160 || '''`#!html`''' || Wiki ページにカスタムした HTML を挿入する。 ||
    161 || '''`#!htmlcomment`''' || Wiki ページに HTML のコメントを挿入する (''0.12 以降'') 。 ||
    162 || || `#!html` ブロックは ''自己完結型'' でなければなりません。つまり、1つ目のブロックである HTML 要素を開始し、後に記述する2つ目のブロックでその要素を閉じるということはできません。これに類似した効果を得るためには、下記に述べるプロセッサを使用して下さい。  ||
    163 || '''`#!div`''' || <div> 要素内の任意の Wiki の内容をラップする (''0.11 以降'') 。 ||
    164 || '''`#!span`''' || <span> 要素内の任意の Wiki の内容をラップする (''0.11 以降'') 。 ||
    165 || '''`#!td`''' || <td> 要素内の任意の Wiki の内容をラップする (''0.12 以降'') 。 ||
    166 || '''`#!th`''' || <th> 要素内の任意の Wiki の内容をラップする (''0.12 以降'') 。 ||
    167 || '''`#!tr`''' || `#!td` や `#!th` ブロックをラッピングしたり、グルーピングした列を見やすくするために属性を指定する際、オプションとして使用することができます (''0.12 以降'') 。 ||
    168 || || これらのプロセッサについての詳細と使用例については、 WikiHtml を参照して下さい。 ||
    169 |||| ||
    170 ||||= '''その他のプロセッサ''' =||
    171 || '''`#!rst`''' || Trac における Restructured テキストのサポート。WikiRestructuredText 参照。 ||
    172 || '''`#!textile`''' || [http://cheeseshop.python.org/pypi/textile Textile] がインストールされている場合のサポート。 [http://www.textism.com/tools/textile/ a Textile リファレンス] 参照。 ||
    173 |||| ||
    174 ||||= '''コードのハイライトのサポート''' =||
    175 || '''`#!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 は、さまざまなプログラミング言語のソースコードに対応するインラインのシンタックスハイライトを提供するプロセッサを同梱しています。[[BR]] [[BR]] Trac では、シンタックスのカラーリングについて外部のソフトウェア (例えば [http://pygments.org Pygments]) に依存しています。[[BR]] [[BR]] サポートしている言語の情報と他の言語のサポートを有効にする方法については TracSyntaxColoring を参照してください。 ||
    176 |||| ||
    177 ||||= '''MIME タイププロセッサ''' =||
    178 |||| プロセッサに MIME タイプを使用することによって、ソースコードをブラウズするとき、サポートしている言語に対してシンタックスハイライトを適用することが可能です。 ||
     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 wiki content inside a <div> element. ||
     153|| '''`#!span`''' || Wrap wiki content inside a <span> element. ||
     154|| '''`#!td`''' || Wrap wiki content inside a <td> element. (''since 0.12'') ||
     155|| '''`#!th`''' || Wrap 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 [http://pygments.org Pygments] for syntax coloring. [[BR]] [[BR]] See TracSyntaxColoring for information about which languages are supported and how to enable support for more languages. ||
     166|||| ||
     167
     168Since 1.1.2 the default, coding highlighting and MIME-type processors support the argument `lineno` for adding line numbering to the code block. When a value is specified, as in `lineno=3`, the numbering will start at the specified value. When used in combination with the `lineno` argument, the `marks` argument is also supported for highlighting lines. A single line number, set of line numbers and range of line numbers are allowed. For example, `marks=3`, `marks=3-6`, `marks=3,5,7` and `marks=3-5,7` are all allowed. The specified values are relative to the numbered lines, so if `lineno=2` is specified to start the line numbering at 2, `marks=2` will result in the first line being highlighted.
     169
     170Using the MIME type as processor, it is possible to syntax-highlight the same languages that are supported when browsing source code.
     171
     172||||= '''MIME Type Processors''' =||
    179173{{{#!tr
    180174{{{#!td
    181 例:
     175Some examples:
    182176 {{{
    183 {{{
    184 #!text/html
    185 <h1>テキスト</h1>
    186 }}}
    187  }}}
    188 }}}
    189 {{{#!td
    190 この結果はシンタックスハイライトされた HTML コードになります:
     177{{{#!text/html
     178<h1>text</h1>
     179}}}
     180 }}}
     181}}}
     182{{{#!td
     183The result will be syntax highlighted HTML code:
     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
    191192 {{{
    192 #!text/html
    193 <h1>テキスト</h1>
    194  }}}
    195 
    196 これは、すべての [TracSyntaxColoring#SyntaxColoringSupport 対応している MIME タイプ] に対して有効です。
    197 }}}
    198 }}}
    199 {{{#!td
    200  {{{
    201 {{{
    202 #!diff
     193{{{#!diff
    203194--- Version 55
    204195+++ Version 56
    … …  
    220211}}}
    221212{{{#!td
    222 '''`#!diff`''' は細部までレンダリングします:
    223  {{{
    224 #!diff
     213'''`#!diff`''' has a particularly nice renderer:
     214 {{{#!diff
    225215--- Version 55
    226216+++ Version 56
    … …  
    241231}}}
    242232
    243 ユーザによるプロセッサマクロの開発やコントリビュート:
    244  * [trac:ProcessorBazaar]
    245  * [trac:MacroBazaar]
    246  * [http://trac-hacks.org/ Trac Hacks] コミュニティサイト
    247 
    248 プロセッサは Wiki マクロを開発するのと変わりはありません。
    249 実際、開発方法は同じであり、シンタックスの使用方法のみが異なります。
    250 詳細情報については、 [WikiMacros#DevelopingCustomMacros カスタムマクロを開発する] を参照して下さい。
    251 
     233Line numbers can be added to code blocks and lines can be highlighted //(since 1.1.2)//.
     234{{{
     235{{{#!python lineno=3 marks=3,9-10,16
     236def expand_markup(stream, ctxt=None):
     237    """A Genshi stream filter for expanding `genshi.Markup` events.
     238
     239    Note: Expansion may not be possible if the fragment is badly
     240    formed, or partial.
     241    """
     242    for event in stream:
     243        if isinstance(event[1], Markup):
     244            try:
     245                for subevent in HTML(event[1]):
     246                    yield subevent
     247            except ParseError:
     248                yield event
     249        else:
     250            yield event
     251}}}
     252}}}
     253{{{#!python lineno=3 marks=3,9-10,16
     254def expand_markup(stream, ctxt=None):
     255    """A Genshi stream filter for expanding `genshi.Markup` events.
     256
     257    Note: Expansion may not be possible if the fragment is badly
     258    formed, or partial.
     259    """
     260    for event in stream:
     261        if isinstance(event[1], Markup):
     262            try:
     263                for subevent in HTML(event[1]):
     264                    yield subevent
     265            except ParseError:
     266                yield event
     267        else:
     268            yield event
     269}}}
     270
     271For more processor macros developed and/or contributed by users, visit the [https://trac-hacks.org Trac Hacks] community site.
     272
     273Developing 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.
    252274
    253275----