Changes between Version 2 and Version 3 of WikiMacros


Ignore:
Timestamp:
Oct 1, 2012 9:35:34 AM (12 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WikiMacros

    v2 v3  
    1 = Trac マクロ = #TracMacros 
     1= Trac Macros = 
    22 
    33[[PageOutline]] 
    44 
    5 Trac マクロとは、 Python で書かれた 'カスタム関数' によって Trac の Wiki エンジンを拡張するプラグインです。 WikiFormatting エンジンが利用可能なあらゆるコンテキストにおいて、マクロを使用することによって、動的な HTML データが挿入されます。 
     5Trac macros are plugins to extend the Trac engine with custom 'functions' written in Python. A macro inserts dynamic HTML data in any context supporting WikiFormatting. Its syntax is `[[macro-name(optional-arguments)]]`. 
    66 
    7 もう 1 種類のマクロは WikiProcessors です。これは通常、 Wiki 以外のマークアップ形式と表示を取り扱うために使用し、多くは、 (ソースコードハイライトのような) より大きいブロックに使用します。 
     7The WikiProcessors are another kind of macros. They typically deal with alternate markup formats and transformation of larger "blocks" of information (like source code highlighting). They are used for processing the multiline `{{{#!wiki-processor-name ... }}}` blocks. 
    88 
    9 == マクロの利用 == #UsingMacros 
     9== Using Macros == 
    1010 
    11 マクロ呼び出しは、二つの ''角括弧 (square brackets) '' で括られた箇所です。 Python 関数のように、マクロは引数を取ることができ、括弧 (parenthesis) の中に、カンマで区切ったリストで表記します。 
     11Macro calls are enclosed in two ''square brackets''. Like Python functions, macros can also have arguments, a comma separated list within parentheses. 
    1212 
    13 === 詳細なヘルプを見るには ===#GettingDetailedHelp  
    14 マクロの一覧と完全なヘルプは、 下記の[#AvailableMacros マクロ一覧] にある !MacroList マクロを使用してみることができます。 
     13=== Getting Detailed Help === 
     14The list of available macros and the full help can be obtained using the !MacroList macro, as seen [#AvailableMacros below]. 
    1515 
    16 簡単なマクロ一覧は ![[MacroList(*)]] や ![[?]] で見ることができます。 
     16A brief list can be obtained via `[[MacroList(*)]]` or `[[?]]`. 
    1717 
    18 特定のマクロの詳細なヘルプを参照したい場合は、 !MacroList マクロに引数渡すことによって参照することができます。例) ![[MacroList(MacroList)]] 。もしくは、便宜上、 ![[MacroList?]] のようにマクロ名にクエスチョンマーク (?) をつけることでヘルプをみることができます。 
     18Detailed 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?]]`. 
    1919 
    2020 
    2121 
    22 === 利用例 === #Example 
     22=== Example === 
    2323 
    24 'Trac' で始まる Wiki ページの最近の変更履歴 3 件分を表示するマクロです: 
     24A list of 3 most recently changed wiki pages starting with 'Trac': 
    2525 
    26 ||= Wiki マークアップ =||= 表示 =|| 
     26||= Wiki Markup =||= Display =|| 
    2727{{{#!td 
    2828  {{{ 
    … …  
    4848  }}} 
    4949}}} 
    50 {{{#!td style="padding-left: 2em; font-size: 80%" 
    51 [[?]] 
     50{{{#!td style="padding-left: 2em" 
     51{{{#!html  
     52<div style="font-size: 80%" class="trac-macrolist"> 
     53<h3><code>[[Image]]</code></h3>Embed an image in wiki-formatted text. 
     54 
     55The first argument is the file … 
     56<h3><code>[[InterTrac]]</code></h3>Provide a list of known <a class="wiki" href="/wiki/InterTrac">InterTrac</a> prefixes. 
     57<h3><code>[[InterWiki]]</code></h3>Provide a description list for the known <a class="wiki" href="/wiki/InterWiki">InterWiki</a> prefixes. 
     58<h3><code>[[KnownMimeTypes]]</code></h3>List all known mime-types which can be used as <a class="wiki" href="/wiki/WikiProcessors">WikiProcessors</a>. 
     59Can be …</div> 
     60}}} 
     61etc. 
    5262}}} 
    5363 
    54 == マクロ一覧 == #AvailableMacros 
     64== Available Macros == 
    5565 
    56 ''Note: 以下に示すリストはマクロドキュメントを含むものだけです。 `-OO` による最適化や、 [wiki:TracModPython mod_python] での `PythonOptimize` オプションが設定されていると表示されません。'' 
     66''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].'' 
    5767 
    5868[[MacroList]] 
    5969 
    60 == 世界のマクロを共有 == #Macrosfromaroundtheworld 
     70== Macros from around the world == 
    6171 
    62 [http://trac-hacks.org/ Trac Hacks] というサイトは、コミュニティに寄稿されたマクロと [TracPlugins プラグイン] を収集し提供しています。新しいマクロを探している、共有したいマクロを作成した、などの場合は遠慮なく Trac Hacks のサイトを訪問してください。 
     72The [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're looking for new macros, or have written one that you'd like to share with the world, please don't hesitate to visit that site. 
    6373 
    64 == カスタムマクロを開発する == #DevelopingCustomMacros 
    65 マクロは、 Trac 本体と同様 [http://python.org/ Python] で書かれています。そして TracPlugins の一種として開発します 
     74== Developing Custom Macros == 
     75Macros, like Trac itself, are written in the [http://python.org/ Python programming language] and are developed as part of TracPlugins. 
    6676 
    67 マクロの開発についての詳しい情報は [http://trac.edgewall.org/wiki/TracDev リソースの開発] を参照してください。 
     77For more information about developing macros, see the [trac:TracDev development resources] on the main project site. 
    6878 
    6979 
    70 Trac 0.11 でマクロを作成する簡単な例を 2 つ紹介します。 
     80Here are 2 simple examples showing how to create a Macro with Trac 0.11.  
    7181 
    72 古いマクロと新しいマクロの違いを示す例は [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] を参照してください。 
     82Also, have a look at [trac:source:tags/trac-0.11/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 a little more insight about the transition. 
    7383 
    74 === 引数なしのマクロ === #Macrowithoutarguments 
    75 下記のソースコードをテストするためには、このソースコードを `timestamp_sample.py` として保存し、 TracEnvironment の `plugins/` に配置しなければなりません。 
     84=== Macro without arguments === 
     85To test the following code, you should saved it in a `timestamp_sample.py` file located in the TracEnvironment's `plugins/` directory. 
    7686{{{ 
    7787#!python 
    … …  
    95105}}} 
    96106 
    97 === 引数付きのマクロ === #Macrowitharguments 
    98 下記のソースコードをテストするためには、このソースコードを `helloworld_sample.py` として保存し、 TracEnvironment の `plugins/` に配置しなければなりません。 
     107=== Macro with arguments === 
     108To test the following code, you should saved it in a `helloworld_sample.py` file located in the TracEnvironment's `plugins/` directory. 
    99109{{{ 
    100110#!python 
    … …  
    134144}}} 
    135145 
    136 Note: `expand_macro` は 第4パラメータに、 ''`args`'' を任意に取ることもできます。 このマクロが [WikiProcessors WikiProcessor] として呼ばれたとき、 `key=value` 形式の [WikiProcessors#UsingProcessors プロセッサパラメータ] を渡すことも可能です。もし、このパラメータを指定したとき、これらの値は、ディクショナリの中に保存され、 追加の `args` パラメータによって渡されます。一方で、マクロとして呼び出されたときは、 `args` パラメータは、 `None` として扱われます (''0.12 以降'') 。 
     146Note that `expand_macro` optionally takes a 4^th^ parameter ''`args`''. When the macro is called as a [WikiProcessors WikiProcessor], it's 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. On the contrary, when called as a macro, `args` is  `None`. (''since 0.12''). 
    137147 
    138 例として、このように記述した場合: 
     148For example, when writing: 
    139149{{{ 
    140 {{{#!HelloWorld style="polite" 
     150{{{#!HelloWorld style="polite" -silent verbose 
    141151<Hello World!> 
    142152}}} 
    … …  
    148158[[HelloWorld(<Hello World!>)]] 
    149159}}} 
    150 結果はこのようになります: 
     160One should get: 
    151161{{{ 
    152 Hello World, text = <Hello World!> , args = {'style': u'polite'} 
     162Hello World, text = <Hello World!> , args = {'style': u'polite', 'silent': False, 'verbose': True} 
    153163Hello World, text = <Hello World!> , args = {} 
    154164Hello World, text = <Hello World!> , args = None 
    155165}}} 
    156166 
    157 Note: `expand_macro` が返す値は、 HTML がエスケープされて '''いない''' ことに注意して下さい。期待する戻り値によっては、あなた自身でエスケープする必要があります (`return Markup.escape(result)` を使用できます)。また、戻り値として HTML が返ってくると分かっているならば、結果を (`return Markup(result)`) という風に Genshi が提供している Markup (`from genshi.core import Markup`) オブジェクトでラップすることもできます。 
     167Note that the return value of `expand_macro` is '''not''' HTML escaped. Depending on the expected result, you should escape it by 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`).   
    158168 
    159 また、`text` を Wiki としてマークアップする場合、 Wiki Formatter (`from trac.wiki import Formatter`) オブジェクトも再帰的に使用することができます。以下がサンプルです: 
     169You can also recursively use a wiki Formatter (`from trac.wiki import Formatter`) to process the `text` as wiki markup, for example by doing: 
    160170 
    161171{{{ 
    162172#!python 
    163     text = "whatever wiki markup you want, even containing other macros" 
    164     # Convert Wiki markup to HTML, new style 
    165     out = StringIO() 
    166     Formatter(self.env, formatter.context).format(text, out) 
    167     return Markup(out.getvalue()) 
     173from genshi.core import Markup 
     174from trac.wiki.macros import WikiMacroBase 
     175from trac.wiki import Formatter 
     176import StringIO 
     177 
     178class HelloWorldMacro(WikiMacroBase): 
     179        def expand_macro(self, formatter, name, text, args): 
     180                text = "whatever '''wiki''' markup you want, even containing other macros" 
     181                # Convert Wiki markup to HTML, new style 
     182                out = StringIO.StringIO() 
     183                Formatter(self.env, formatter.context).format(text, out) 
     184                return Markup(out.getvalue()) 
    168185}}}