Context Navigation

Changes between Version 3 and Version 4 of WikiMacros

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

Legend:

: Unmodified
: Added
: Removed
: Modified

WikiMacros

-              v3
+              v4
 = Trac マクロ = #TracMacros
+= Trac Macros
 [[PageOutline]]
+[[PageOutline(2-5,Contents,pullout)]]
+Trac マクロとは、 Python で書かれた 'カスタム関数' によって Trac の Wiki エンジンを拡張するプラグインです。 WikiFormatting エンジンが利用可能なあらゆるコンテキストにおいて、マクロを使用することによって、動的な HTML データが挿入されます。
+'''Trac macros''' extend the Trac engine with custom functionality. Macros are a special type of plugin and are written in Python. A macro inserts dynamic HTML data in any context supporting WikiFormatting.
+もう 1 種類のマクロは WikiProcessors です。これは通常、 Wiki 以外のマークアップ形式と表示を取り扱うために使用し、多くは、 (ソースコードハイライトのような) より大きいブロックに使用します。
+The macro syntax is `[[macro-name(optional-arguments)]]`.
+== マクロの利用 == #UsingMacros
+'''WikiProcessors''' are another kind of macros. They are typically used for source code highlighting, such as `!#python` or `!#apache` and when the source code spans multiple lines, such as:
+マクロ呼び出しは、二つの ''角括弧 (square brackets) '' で括られた箇所です。 Python 関数のように、マクロは引数を取ることができ、括弧 (parenthesis) の中に、カンマで区切ったリストで表記します。
+{{{
+{{{#!wiki-processor-name
+...
+}}}
+}}}
+=== 詳細なヘルプを見るには === #GettingDetailedHelp
+マクロの一覧と完全なヘルプは、 下記の[#AvailableMacros マクロ一覧] にある !MacroList マクロを使用してみることができます。
+== Using Macros
+簡単なマクロ一覧は `[[MacroList(*)]]` や `[[?]]` で見ることができます。
+Macro calls are enclosed in double-square brackets `[[..]]`. Like Python functions, macros can have arguments, which is then a comma separated list within parentheses `[[..(,)]]`.
+特定のマクロの詳細なヘルプを参照したい場合は、 !MacroList マクロに引数渡すことによって参照することができます。 例) `[[MacroList(MacroList)]]` 。もしくは、便宜上、 `[[MacroList?]]` のようにマクロ名にクエスチョンマーク ('?') をつけることでヘルプをみることができます。
+=== Getting Detailed Help
+The list of available macros and the full help can be obtained using the !MacroList macro, as seen [#AvailableMacros below].
+A brief list can be obtained via `[[MacroList(*)]]` or `[[?]]`.
+=== 利用例 === #Example
+Detailed help on a specific macro can be obtained by passing it as an argument to !MacroList, e.g. `[[MacroList(MacroList)]]`, or, more conveniently, by appending a question mark (`?`) to the macro's name, like in `[[MacroList?]]`.
+'Trac' で始まる Wiki ページの最近の変更履歴 3 件分を表示するマクロです:
+=== Example
+||= Wiki マークアップ =||= 表示 =||
+A list of the 3 most recently changed wiki pages starting with 'Trac':
+||= Wiki Markup =||= Display =||
 {{{#!td
   {{{
 …
 }}}
 {{{#!td style="padding-left: 2em"
 {{{#!html
 <div style="font-size: 80%" class="trac-macrolist">
 <h3><code>[[Image]]</code></h3>画像を Wiki 形式のテキストに組み込みます。
+{{{#!html
+<div class="trac-macrolist">
+<h3><code>[[Image]]</code></h3>Embed an image in wiki-formatted text.
+番目の引数は、ファイル名を指定します。ファイルの指定は添付ファイルなど …
 <h3><code>[[InterTrac]]</code></h3>既知の <a class="wiki" href="/wiki/InterTrac">InterTrac</a> プレフィックスをリスト形式で表示します。
 <h3><code>[[InterWiki]]</code></h3>既知の <a class="wiki" href="/wiki/InterWiki">InterWiki</a> プレフィックスに関する概要のリストを表示します。
 <h3><code>[[KnownMimeTypes]]</code></h3><a class="wiki" href="/wiki/WikiProcessors">WikiProcessors</a> で処理できる既知の mime-type を表示します。
 引数が与えられた場合は、 mime-type ...</div>
+The first argument is the file, as in <code>[[Image(filename.png)]]</code>
+<h3><code>[[InterTrac]]</code></h3>Provide a list of known <a class="wiki" href="/wiki/InterTrac">InterTrac</a> prefixes.
+<h3><code>[[InterWiki]]</code></h3>Provide a description list for the known <a class="wiki" href="/wiki/InterWiki">InterWiki</a> prefixes.
+<h3><code>[[KnownMimeTypes]]</code></h3>List all known mime-types which can be used as <a class="wiki" href="/wiki/WikiProcessors">WikiProcessors</a>.
+</div>
 }}}
 etc.
 }}}
 == マクロ一覧 == #AvailableMacros
+== Available Macros
 ''Note: 以下に示すリストはマクロドキュメントを含むものだけです。 `-OO` による最適化や、 [wiki:TracModPython mod_python] での `PythonOptimize` オプションが設定されていると表示されません。''
+''Note that the following list will only contain the macro documentation if you've not enabled `-OO` optimizations, or not set the `PythonOptimize` option for [wiki:TracModPython mod_python].''
 [[MacroList]]
 == 世界のマクロを共有 == #Macrosfromaroundtheworld
+== Macros from around the world
+[http://trac-hacks.org/ Trac Hacks] というサイトは、コミュニティに寄稿されたマクロと [TracPlugins プラグイン] を収集し提供しています。新しいマクロを探している、共有したいマクロを作成した、などの場合は遠慮なく Trac Hacks のサイトを訪問してください。
+The [http://trac-hacks.org/ Trac Hacks] site provides a wide collection of macros and other Trac [TracPlugins plugins] contributed by the Trac community. If you are looking for new macros, or have written one that you would like to share, please visit that site.
+== カスタムマクロを開発する == #DevelopingCustomMacros
+マクロは、 Trac 本体と同様 [http://python.org/ Python] で書かれています。そして TracPlugins の一種として開発します。
+== Developing Custom Macros
+マクロの開発についての詳しい情報は [trac:TracDev リソースの開発] を参照してください。
+Macros, like Trac itself, are written in the [http://python.org/ Python programming language] and are developed as part of TracPlugins.
+For more information about developing macros, see the [trac:TracDev development resources] on the main project site.
+Trac 0.11 でマクロを作成する簡単な例を 2 つ紹介します。
+Here are 2 simple examples showing how to create a Macro. Also, have a look at [trac:source:tags/trac-1.0.2/sample-plugins/Timestamp.py Timestamp.py] for an example that shows the difference between old style and new style macros and at the [trac:source:tags/trac-0.11/wiki-macros/README macros/README] which provides more insight about the transition.
+古いマクロと新しいマクロの違いを示す例は [http://trac.edgewall.org/browser/tags/trac-0.11/sample-plugins/Timestamp.py Timestamp.py] を参照してください。また、古いマクロから新しいマクロに移行するための情報は [http://trac.edgewall.org/browser/tags/trac-0.11/wiki-macros/README macros/README] を参照してください。
+=== Macro without arguments
+=== 引数なしのマクロ === #Macrowithoutarguments
+下記のソースコードをテストするためには、このソースコードを `timestamp_sample.py` として保存し、 TracEnvironment の `plugins/` に配置しなければなりません。
+{{{
+#!python
+To test the following code, save it in a `timestamp_sample.py` file located in the TracEnvironment's `plugins/` directory.
+{{{#!python
 from datetime import datetime
 # Note: since Trac 0.11, datetime objects are used internally
 …
     def expand_macro(self, formatter, name, text):
         t = datetime.now(utc)
         return tag.b(format_datetime(t, '%c'))
+        return tag.strong(format_datetime(t, '%c'))
 }}}
+=== 引数付きのマクロ === #Macrowitharguments
+下記のソースコードをテストするためには、このソースコードを `helloworld_sample.py` として保存し、 TracEnvironment の `plugins/` に配置しなければなりません。
+{{{
+#!python
+=== Macro with arguments
+To test the following code, save it in a `helloworld_sample.py` file located in the TracEnvironment's `plugins/` directory.
+{{{#!python
 from genshi.core import Markup
 …
 }}}
 Note: `expand_macro` は 第4パラメータに、 ''`args`'' を任意に取ることもできます。 このマクロが [WikiProcessors WikiProcessor] として呼ばれたとき、 `key=value` 形式の [WikiProcessors#UsingProcessors プロセッサパラメータ] を渡すことも可能です。もし、このパラメータを指定したとき、これらの値は、ディクショナリの中に保存され、 追加の `args` パラメータによって渡されます。一方で、マクロとして呼び出されたときは、 `args` パラメータは、 `None` として扱われます (''0.12 以降'') 。
+Note that `expand_macro` optionally takes a 4^th^ parameter ''`args`''. When the macro is called as a [WikiProcessors WikiProcessor], it is also possible to pass `key=value` [WikiProcessors#UsingProcessors processor parameters]. If given, those are stored in a dictionary and passed in this extra `args` parameter. In the other case, when called as a macro, `args` is `None`. (''since 0.12'').
 例として、このように記述した場合:
+For example, when writing:
 {{{
 {{{#!HelloWorld style="polite" -silent verbose
 …
 [[HelloWorld(<Hello World!>)]]
 }}}
+結果はこのようになります:
+One should get:
 {{{
 Hello World, text = <Hello World!> , args = {'style': u'polite', 'silent': False, 'verbose': True}
 Hello World, text = <Hello World!> , args = {}
 Hello World, text = <Hello World!> , args = None
+Hello World, text = <Hello World!>, args = {'style': u'polite', 'silent': False, 'verbose': True}
+Hello World, text = <Hello World!>, args = {}
+Hello World, text = <Hello World!>, args = None
 }}}
 Note: `expand_macro` が返す値は、 HTML がエスケープされて '''いない''' ことに注意して下さい。期待する戻り値によっては、あなた自身でエスケープする必要があります (`return Markup.escape(result)` を使用できます)。また、戻り値として HTML が返ってくると分かっているならば、結果を (`return Markup(result)`) という風に Genshi が提供している Markup (`from genshi.core import Markup`) オブジェクトでラップすることもできます。
+Note that the return value of `expand_macro` is '''not''' HTML escaped. Depending on the expected result, you should escape it yourself (using `return Markup.escape(result)`) or, if this is indeed HTML, wrap it in a Markup object (`return Markup(result)`) with `Markup` coming from Genshi (`from genshi.core import Markup`).
 また、`text` を Wiki としてマークアップする場合、 Wiki Formatter (`from trac.wiki import Formatter`) オブジェクトも再帰的に使用することができます。以下がサンプルです:
+You can also recursively use a wiki Formatter (`from trac.wiki import Formatter`) to process the `text` as wiki markup:
+{{{
+#!python
+{{{#!python
 from genshi.core import Markup
 from trac.wiki.macros import WikiMacroBase
 …
 class HelloWorldMacro(WikiMacroBase):
         def expand_macro(self, formatter, name, text, args):
                 text = "whatever '''wiki''' markup you want, even containing other macros"
                 # Convert Wiki markup to HTML, new style
                 out = StringIO.StringIO()
                 Formatter(self.env, formatter.context).format(text, out)
                 return Markup(out.getvalue())
+    def expand_macro(self, formatter, name, text, args):
+        text = "whatever '''wiki''' markup you want, even containing other macros"
+        # Convert Wiki markup to HTML, new style
+        out = StringIO.StringIO()
+        Formatter(self.env, formatter.context).format(text, out)
+        return Markup(out.getvalue())
 }}}