<?xml version="1.0" encoding="Shift_JIS" ?>
<doc>

<title>マクロを使おう</title>

<para>
<ptitle>マクロとは</ptitle>
　マクロとは、「複数のタグや文章を一つのタグで表せるようにする」ための物です。<r/>
<r/>
　既存のタグや文章を組み合わせて、自由に新しいタグを定義する方法です。<r/>
　KAG では、いくつも、何回も同じようなタグを指定しなければいけない場面が多いかと思いますが、マクロの機能を使えば、そのような作業を大幅に減らすことが出来ます。<r/>
　おきまりのタグの連続は、マクロ化して楽しましょう<tt>(^^)</tt><r/>
</para>

<para>
<ptitle>基本的な使い方</ptitle>
　マクロを使うには、まずマクロを「定義」しなければなりません。マクロは一度だけ定義すれば、あとはそのマクロを何回でも使うことができます。ですので、マクロを定義する場合はfirst.ksの最初などに書いておくとよいでしょう。<r/>
<r/>
　マクロを定義する場合は、<kw>macro</kw> タグと <kw>endmacro</kw> タグで、マクロにしたい部分を囲みます。macro タグの属性 name には、マクロ名を指定します。<r/>
<r/>
<bq>
[wait time=200]<r/>
*start|スタート<r/>
[cm]<r/>
; -- マクロの定義 --<r/>
<b>[macro name=newtag]</b>[font color=0xff0000]こんな風にマクロを作ります[resetfont]<b>[endmacro]</b><r/>
</bq>
<r/>
これを使いたい場合は、タグを書くのとまったく同じ要領でマクロ名を使います。<r/>
<bq>
; -- マクロを使う --<r/>
[newtag]<r/>
</bq>
<r/>
　これを実行すると、<tt>[newtag]</tt> のところで、この <tt>[newtag]</tt> というタグが、 <tt>[font color=0xff0000]こんな風にマクロを作ります[resetfont]</tt> に置き換わるため、赤い文字で「こんな風にマクロを作ります」と表示されるはずです。<r/>
<r/>
　複数行に書くこともできます。<r/>
<r/>
<bq>
[wait time=200]<r/>
*start|スタート<r/>
[cm]<r/>
; -- マクロの定義 --<r/>
[macro name=newtag]<r/>
[font color=0xff0000]<r/>
こんな風にマクロを作ります<r/>
[resetfont]<r/>
[endmacro]<r/>
</bq>
<bq>
; -- マクロを使う --<r/>
[newtag]<r/>
</bq>
</para>

<para>
<ptitle>マクロの属性</ptitle>
　マクロに属性を与え、その属性をマクロ中で置き換えることが出来ます。<r/>
　マクロ中で、属性の値に <kw>%</kw> で始まるものを指定すると、それがマクロに与えられた属性に置き換わります。<r/>
　以下の例を見てください。<r/>
<bq>
[wait time=200]<r/>
*start|スタート<r/>
[cm]<r/>
; -- マクロの定義 --<r/>
[macro name=newtag]<r/>
[font color=<b>%iro</b>]<r/>
こんな風にマクロを作ります<r/>
[resetfont]<r/>
[endmacro]<r/>
</bq>
<bq>
; -- マクロを使う --<r/>
[newtag <b>iro=0x00ff00</b>]<r/>
</bq>
<r/>
　この例では、iro という属性を与え、それをエンティティにより font タグの color 属性と置き換えています。<r/>
　実行すると、緑色の文字で「こんな風にマクロを作ります」と表示されるはずです。<r/>
<r/>
<r/>
　また、マクロ中のタグの属性に <kw>*</kw> を指定すると、マクロに渡された属性をすべて渡すことができます。たとえば、trans タグのあとに wt タグをつけたマクロを作りたい場合、<r/>
<r/>
<bq>
[macro name=transwait][trans <b>*</b>][wt][endmacro]<r/>
</bq>
<r/>
　と書くことができます。このようにすると、たとえば transwait マクロを使うときに、transwait マクロに対して指定した属性がそっくりそのまま trans タグに渡されるので、既存のタグに毛の生えた程度のマクロを作るときに便利です。<r/>
<r/>
　マクロ中にあったマクロは再び展開されますので、マクロの中に自分のマクロを書かないようにご注意ください(^^)<r/>
<r/>
　値が省略されたときに、デフォルトの値を指定したい場合は、% 付きの属性に、 <kw>|</kw> ( 縦棒 ) を書き、そのあとに省略された場合の値を指定します。下の例を見てください。<r/>
<r/>
<bq>
[wait time=200]<r/>
*start|スタート<r/>
[cm]<r/>
; -- マクロの定義 --<r/>
[macro name=newtag]<r/>
[font color=%color<b>|0xff0000</b>]<r/>
こんな風にマクロを作ります<r/>
[resetfont]<r/>
[endmacro]<r/>
</bq>
<bq>
; -- マクロを使う --<r/>
[newtag color=0x00ff00]<r/>
[newtag]<r/>
</bq>
　最初の [newtag] を使っているところでは color 属性を指定しているので、その属性の値である 0x00ff00 と置き換わり、緑色で文字が表示されています。<r/>
　二番目の [newtag] を使っているところでは、属性がなにも指定されていないので、デフォルトである "0xff0000" が採用され、文字は赤で表示されます。<r/>
<r/>
<note>
　属性名の指定には英半角小文字を用いてください。大文字を指定すると正常に動作しません。
</note>
</para>
</doc>

