Changes between Version 2 and Version 3 of WikiProcessors

Timestamp:

Oct 1, 2012 9:35:34 AM (12 years ago)

Author:

trac

Comment:

--

WikiProcessors

@@ -1 @@
-= Wiki プロセッサ = #WikiProcessors
-
-プロセッサは [WikiMacros Wiki マクロ] の一種です。 [TracWiki Trac Wiki エンジン] 以外のマークアップフォーマットを使用するために設計されています。プロセッサは ''ユーザが編集したテキストを処理するマクロ機能'' と考えることができます。
-
-Trac 内の全ての Wiki テキストにおいて、 Wiki プロセッサを使用することができます。
-例えば、以下に述べる様々な用途で使用することができます:
- - [#CodeHighlightingSupport シンタックスハイライト] またはテキストを逐語的にレンダリングする,
- -  <div> ブロックや <span> や <td>, <th> のテーブルのセルの内容など
-   [#HTMLrelated コンテキスト内の Wiki のマークアップ]をレンダリングする,
- - [wiki:WikiHtml HTML] や
-   [wiki:WikiRestructuredText Restructured テキスト]
-   または [http://www.textism.com/tools/textile/ textile] のシンタックスをマークアップの代替手段として使用する
-
-
-== プロセッサを使用する == #UsingProcessors
-
-テキストブロック上に Wiki プロセッサを適用するには、
-最初のデリミタとして Wiki の ''コードブロック'' を使用します:
-{{{
-{{{
-これらの行は
-処理されるでしょう...
-}}}
-}}}
-
-`{{{` のすぐ後または直後の行に, 
-`#!` に続けて ''プロセッサ名'' を追加します。.
-
-{{{
-{{{
-#!プロセッサ名
-これらの行は
-処理されるでしょう...
-}}}
-}}}
-
-これはほとんどの UNIX ユーザにはおなじみである "shebang" を用いた表記法です。
-
-これらの内容に加えて、いくつかの Wiki プロセッサでは、 
-プロセッサ名に続けて同じ行に、 `key=value` のペアを書くことによって、 
-''パラメータ'' を許容するものがあります。もし、 `value` にスペースが含まれるケースがたびたび起こるようであれば、
-クオテーションで囲んだ文字列を使用することができます (`key="スペースが含まれている文字列"`) 。
-
-いくつかのプロセッサは Wiki のマークアップを処理することを意味するので、
-プロセッサのブロックを ''ネスト'' させることができます。
-可読性を向上させるためにネストしたブロックの内容をインデントさせたいと思うかもしれません。
-この種のインデントは中身を処理する際に無視されます。
-
-
-== 例 ==
-
-||= Wiki マークアップ =||= 表示 =||
+= Wiki Processors =
+
+Processors 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''. 
+
+Wiki processors can be used in any Wiki text throughout Trac,
+for various different purposes, like:
+ - [#CodeHighlightingSupport syntax highlighting] or for rendering text verbatim,
+ - rendering [#HTMLrelated Wiki markup inside a context], 
+   like inside <div> blocks or <span> or within <td> or <th> table cells,
+ - using an alternative markup syntax, like [wiki:WikiHtml raw HTML] and
+   [wiki:WikiRestructuredText Restructured Text],
+   or [http://www.textism.com/tools/textile/ textile]
+
+
+== Using Processors ==
+
+To use a processor on a block of text, first delimit the lines using
+a Wiki ''code block'':
+{{{
+{{{
+The lines
+that should be processed...
+}}}
+}}}
+
+Immediately after the `{{{` or on the line just below, 
+add `#!` followed by the ''processor name''.
+
+{{{
+{{{
+#!processorname
+The lines
+that should be processed...
+}}}
+}}}
+
+This is the "shebang" notation, familiar to most UNIX users.
+
+Besides their content, some Wiki processors can also accept ''parameters'',
+which are then given as `key=value` pairs after the processor name, 
+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"`).
+
+As some processors are meant to process Wiki markup, it's quite possible to
+''nest'' processor blocks.
+You may want to indent the content of nested blocks for increased clarity,
+this extra indentation will be ignored when processing the content.
+
+
+== Examples ==
+
+||= Wiki Markup =||= Display =||
 {{{#!td colspan=2 align=center style="border: none"
 
-                __例 1__: HTML を挿入する
+                __Example 1__: Inserting raw HTML
 }}}
 |-----------------------------------------------------------------
@@ -59 +59 @@
 {{{
 {{{
-<h1 style="color: grey">HTML テスト</h1>
+#!html
+<h1 style="color: grey">This is raw HTML</h1>
 }}}
 }}}
@@ -66 +67 @@
 {{{
 #!html
-<h1 style="color: grey">HTML テスト</h1>
+<h1 style="color: grey">This is raw HTML</h1>
 }}}
 }}}
@@ -72 +73 @@
 {{{#!td colspan=2 align=center style="border: none"
 
-     __例 2__: <div> ブロック内のカスタマイズしたスタイルシートでハイライトした Python のコード
+     __Example 2__: Highlighted Python code in a <div> block with custom style
 }}}
 |-----------------------------------------------------------------
@@ -79 +80 @@
   {{{#!div style="background: #ffd; border: 3px ridge"
 
-  これは 埋め込まれた "コード" ブロックの例です:
+  This is an example of embedded "code" block:
 
     {{{
@@ -93 +94 @@
   {{{#!div style="background: #ffd; border: 3px ridge"
 
-  これは 埋め込まれた "コード" ブロックの例です:
+  This is an example of embedded "code" block:
 
     {{{
@@ -106 +107 @@
 {{{#!td colspan=2 align=center style="border: none"
 
-     __例 3__: Wiki ページでチケットのキーワード検索を行なう
+     __Example 3__: Searching tickets from a wiki page, by keywords.
 }}}
 |-----------------------------------------------------------------
@@ -113 +114 @@
   {{{
   #!html
-  <form action="/query" method="get">
-  <input type="text" name="keywords" value="~" size="30">
-  <input type="submit" value="キーワードで検索">
+  <form action="/query" method="get"><div>
+  <input type="text" name="keywords" value="~" size="30"/>
+  <input type="submit" value="Search by Keywords"/>
   <!-- To control what fields show up use hidden fields
-  <input type="hidden" name="col" value="id">
-  <input type="hidden" name="col" value="summary">
-  <input type="hidden" name="col" value="status">
-  <input type="hidden" name="col" value="milestone">
-  <input type="hidden" name="col" value="version">
-  <input type="hidden" name="col" value="owner">
-  <input type="hidden" name="col" value="priority">
-  <input type="hidden" name="col" value="component">
+  <input type="hidden" name="col" value="id"/>
+  <input type="hidden" name="col" value="summary"/>
+  <input type="hidden" name="col" value="status"/>
+  <input type="hidden" name="col" value="milestone"/>
+  <input type="hidden" name="col" value="version"/>
+  <input type="hidden" name="col" value="owner"/>
+  <input type="hidden" name="col" value="priority"/>
+  <input type="hidden" name="col" value="component"/>
   -->
-  </form>
+  </div></form>
   }}}
   }}}
@@ -133 +134 @@
   {{{
   #!html
-  <form action="/query" method="get">
-  <input type="text" name="keywords" value="~" size="30">
-  <input type="submit" value="キーワードで検索">
+  <form action="/query" method="get"><div>
+  <input type="text" name="keywords" value="~" size="30"/>
+  <input type="submit" value="Search by Keywords"/>
   <!-- To control what fields show up use hidden fields
-  <input type="hidden" name="col" value="id">
-  <input type="hidden" name="col" value="summary">
-  <input type="hidden" name="col" value="status">
-  <input type="hidden" name="col" value="milestone">
-  <input type="hidden" name="col" value="version">
-  <input type="hidden" name="col" value="owner">
-  <input type="hidden" name="col" value="priority">
-  <input type="hidden" name="col" value="component">
+  <input type="hidden" name="col" value="id"/>
+  <input type="hidden" name="col" value="summary"/>
+  <input type="hidden" name="col" value="status"/>
+  <input type="hidden" name="col" value="milestone"/>
+  <input type="hidden" name="col" value="version"/>
+  <input type="hidden" name="col" value="owner"/>
+  <input type="hidden" name="col" value="priority"/>
+  <input type="hidden" name="col" value="component"/>
   -->
-  </form>
-  }}}
-}}}
-== プロセッサ一覧 == #AvailableProcessors
-
-以下のプロセッサが Trac の配布に含まれています:
-
- `#!default` :: フォーマット済みのテキストブロック内でテキストを逐語的に表示する。 
-                これはプロセッサ名を指定 ''しない'' のと同じです。
-                (さらに `#!` を指定しないのと同じです)
- `#!comment` :: このセクション内のテキストを処理しません(つまり、このセクションの内容は
-                プレインテキスト内にのみ存在します - レンダリングしたページには表示されません)。
-
-=== HTML 関連 === #HTMLrelated
-
- `#!html`        :: Wiki ページにカスタムした HTML を挿入する。
- `#!htmlcomment` :: Wiki ページに HTML のコメントを挿入する (''0.12 以降'') 。
-
-`#!html` ブロックは ''自己完結型'' でなければなりません。
-つまり、1つ目のブロックである HTML 要素を開始し、後に記述する2つ目のブロックでその要素を閉じるということはできません。これに類似した効果を得るためには、下記に述べるプロセッサを使用して下さい。
-
-  `#!div` :: <div> 要素内の任意の Wiki の内容をラップする
-             (''0.11 以降'').
- `#!span` :: <span> 要素内の任意の Wiki の内容をラップする 
-             (''0.11 以降''). 
-
- `#!td` :: <td> 要素内の任意の Wiki の内容をラップする (''0.12 以降'')
- `#!th` :: <th> 要素内の任意の Wiki の内容をラップする (''0.12 以降'') 
- `#!tr` :: `#!td` や `#!th` ブロックをラッピングしたり、
-       グルーピングした列を見やすくするために属性を指定する際、オプションとして使用することができます。
-       (''0.12 以降'')
-
-これらのプロセッサについての詳細と使用例については、 WikiHtml を参照して下さい。
-
-=== その他のプロセッサ ===#OtherMarkups
-
-     `#!rst` :: Trac における Restructured テキストのサポート. WikiRestructuredText 参照。
- `#!textile` :: [http://cheeseshop.python.org/pypi/textile Textile] がインストール
-                されている場合のサポート。
-                [http://www.textism.com/tools/textile/ a Textile リファレンス] 参照。
-
-
-=== コードのハイライトのサポート ===#CodeHighlightingSupport
-
-Trac はインラインのシンタックスハイライトを提供するプロセッサを同梱しています:
- `#!c` (C), `#!cpp` (C++), `#!python` (Python), `#!perl` (Perl), 
- `#!ruby` (Ruby), `#!php` (PHP), `#!asp` (ASP), `#!java` (Java), 
- `#!js` (Javascript), `#!sql (SQL)`, `#!xml` (XML または HTML),
- `#!sh` (!Bourne/Bash シェル), など。
-
-Trac では、シンタックスのカラーリングについて外部のソフトウェア
-例えば [http://pygments.org Pygments] に依存しています。 
-
-TracSyntaxColoring にどの言語のシンタックスハイライトがサポートされているかについての情報と
-その他の言語のシンタックスハイライトのサポートを有効にする方法について書かれています。 
-
-MIME タイプをプロセッサ名として使用することによって、ソースコードをブラウズするときに、サポートしている言語についてはシンタックスハイライトをすることが可能です。例えば、このように書くことができます:
-{{{
-{{{
-#!text/html
-<h1>テキスト</h1>
-}}}
-}}}
-
-この結果はシンタックスハイライトされた HTML コードになります:
+  </div></form>
+  }}}
+}}}
+== Available Processors ==
+
+The following processors are included in the Trac distribution:
+
+|| '''`#!default`''' || Present the text verbatim in a preformatted text block. This is the same as specifying ''no'' processor name (and no `#!`) ||
+|| '''`#!comment`''' || Do not process the text in this section (i.e. contents exist only in the plain text - not in the rendered page). ||
+|||| ||
+||||= '''HTML related''' =||
+|| '''`#!html`''' || Insert custom HTML in a wiki page. ||
+|| '''`#!htmlcomment`''' || Insert an HTML comment in a wiki page (''since 0.12''). ||
+|| || 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.  ||
+|| '''`#!div`''' || Wrap an arbitrary Wiki content inside a <div> element (''since 0.11''). ||
+|| '''`#!span`''' || Wrap an arbitrary Wiki content inside a <span> element (''since 0.11''). ||
+|| '''`#!td`''' || Wrap an arbitrary Wiki content inside a <td> element (''since 0.12'') ||
+|| '''`#!th`''' || Wrap an arbitrary Wiki content inside a <th> element (''since 0.12'') ||
+|| '''`#!tr`''' || Can optionally be used for wrapping `#!td` and `#!th` blocks, either for specifying row attributes of better visual grouping (''since 0.12'') ||
+|| || See WikiHtml for example usage and more details about these processors. ||
+|||| ||
+||||= '''Other Markups''' =||
+|| '''`#!rst`''' || Trac support for Restructured Text. See WikiRestructuredText. ||
+|| '''`#!textile`''' || Supported if [http://cheeseshop.python.org/pypi/textile Textile] is installed. See [http://www.textism.com/tools/textile/ a Textile reference]. ||
+|||| ||
+||||= '''Code Highlighting Support''' =||
+|| '''`#!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. ||
+|||| ||
+
+Using the MIME type as processor, it is possible to syntax-highlight the same languages that are supported when browsing source code.
+
+||||= '''MIME Type Processors''' =||
+{{{#!tr
+{{{#!td
+Some examples:
+ {{{
 {{{
 #!text/html
 <h1>text</h1>
 }}}
-
-これは、対応しているすべての [TracSyntaxColoring#SyntaxColoringSupport 対応している MIME タイプ] に対して有効です。
-
-
-ユーザによるプロセッサマクロの開発やコントリビュート:
- * [http://trac.edgewall.org/wiki/ProcessorBazaar ProcessorBazaar]
- * [http://trac.edgewall.org/wiki/MacroBazaar MacroBazaar]
- * [http://trac-hacks.org/ Trac Hacks] コミュニティサイト
-
-プロセッサは Wiki マクロを開発するのと変わりはありません。
-実際、開発方法は同じであり、シンタックスの使用方法のみが異なります。 
-詳細情報については、 [WikiMacros#DevelopingCustomMacros カスタムマクロを開発する] を参照して下さい。
+ }}}
+}}}
+{{{#!td
+The result will be syntax highlighted HTML code:
+ {{{
+#!text/html
+<h1>text</h1>
+ }}}
+
+The same is valid for all other [TracSyntaxColoring#SyntaxColoringSupport mime types supported].
+}}}
+}}}
+{{{#!td
+ {{{
+{{{
+#!diff
+--- Version 55
++++ Version 56
+@@ -115,8 +115,9 @@
+     name='TracHelloWorld', version='1.0',
+     packages=find_packages(exclude=['*.tests*']),
+-    entry_points = """
+-        [trac.plugins]
+-        helloworld = myplugs.helloworld
+-    """,
++    entry_points = {
++        'trac.plugins': [
++            'helloworld = myplugs.helloworld',
++        ],
++    },
+ )
+}}}
+ }}}
+}}}
+{{{#!td
+'''`#!diff`''' has a particularly nice renderer:
+ {{{
+#!diff
+--- Version 55
++++ Version 56
+@@ -115,8 +115,9 @@
+     name='TracHelloWorld', version='1.0',
+     packages=find_packages(exclude=['*.tests*']),
+-    entry_points = """
+-        [trac.plugins]
+-        helloworld = myplugs.helloworld
+-    """,
++    entry_points = {
++        'trac.plugins': [
++            'helloworld = myplugs.helloworld',
++        ],
++    },
+ )
+ }}}
+}}}
+
+For more processor macros developed and/or contributed by users, visit: 
+ * [trac:ProcessorBazaar]
+ * [trac:MacroBazaar]
+ * [http://trac-hacks.org Trac Hacks] community site
+
+Developing 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.
 
 
 ----
 See also: WikiMacros, WikiHtml, WikiRestructuredText, TracSyntaxColoring, WikiFormatting, TracGuide
-