@@ -2,12 +2,21 @@
 $(DDOC_AUTHORS k.inaba)
 $(DDOC_LICENSE NYSL 0.9982 (http://www.kmonos.net/nysl/))
 
 <p>
-このファイルは、言語仕様などの簡単な説明です。
+左のサイドバーの "Package" タブをクリックすると実装のソースのドキュメントが読めます。
 </p>
 <p>
-あとついでに、左のサイドバーの "Package" タブをクリックすると実装のソースのドキュメントが読めます。
+このファイルは、言語仕様などの、やや辞書的な説明です。<br />
+もっとざっくりとした、言語デザインの方向性の魂的なものについては、
+「メタプログラミングの会」の発表スライドをご覧下さい。
+</p>
+<p>
+あと、 やたらとマクロの章が長くなっていますが、 この部分は、
+レイヤ機能を入れたら自動的にすごく自然にマクロが入るなーと思って、
+おまけで実装してみた程度のものです。
+あんまり重要ではないので、適当にスルーして下さいませ。
+単に、適当に入れたら適当で微妙な部分が多く残ってしまったので注意書きが増えているだけで…。
 </p>
 
 $(DDOC_MEMBERS
 
@@ -174,9 +183,9 @@
 （再帰関数の定義が"うまく"いっているのはこの上書きのためです）。
 なんでこんなことになっているかというと、
 後で説明する「レイヤ」を使ったときに
 <tt>let foo = ... in @lay foo = ... in ...</tt>
-で他レイヤに重ね書きするためであります。
+で他レイヤに重ね書きするため、のつもりです。詳しくは後で。
 </p>
 ))
 )
 ))
@@ -206,9 +215,9 @@
   <li>整数:     <tt>0</tt>, <tt>123</tt>, <tt>456666666666666666666666666666666666666789</tt>, ...</li>
   <li>文字列:   <tt>"hello, world!"</tt>, ...</li>
   <li>関数:     <tt>fun(x){x+1}</tt></li>
   <li>テーブル: <tt>{car: 1, cdr: {car: 2, cdr: {}}}</tt></li>
-  <li>未定義値: (特殊なケースで作られます。「レイヤ」の説明参照のこと。)</li>
+  <li>ボトム:   (特殊なケースで作られます。「レイヤ」の説明参照のこと。)</li>
 </ul>
 <p>
 関数はいわゆる「クロージャ」です。静的スコープで外側の環境にアクセスできます。
 テーブルはいわゆるプロトタイプチェーンを持っていて、
@@ -447,10 +456,9 @@
 </p>
 <ol>
 <li>関数呼び出し時（とトップレベル環境の実行開始時）に、
 	まず、<code>@macro</code> レイヤでコードを実行。</li>
-<li>返ってきた構文木を、<code>@value</code> レイヤ、
-	またはその関数を呼び出したときのレイヤで実行。</li>
+<li>返ってきた構文木を、その関数を呼び出したときのレイヤで実行。</li>
 </ol>
 <p>
 <code>@macro</code> レイヤも所詮ただのレイヤですので、
 上で説明した方法で <code>@macro</code> レイヤに関数などを登録しておくことで、
@@ -529,10 +537,10 @@
 <p>
 <tt>reverseArgs</tt> は、関数呼び出しの構文木の、引数の順番を逆転する関数です。
 <tt>@macro(e)</tt> によってマクロレイヤにセットされている構文木引数を取り出し、
 それを <tt>@value</tt> レイヤによる普通の計算プログラムで操作しています。
-要は、<tt>@macro(...)</tt> はいわゆる「準クオート (quasiquote)」、
-<tt>@value(...)</tt> は「逆クオート (unquote)」に近い働きをします。
+<tt>@macro(...)</tt> はいわゆる「準クオート (quasiquote)」、
+<tt>@value(...)</tt> は「逆クオート (unquote)」にちょっと近いかもしれません。
 </p>
 <p>
 <tt>@layer(...)</tt> だけでなく、関数のレイヤ指定引数なども同様に使うことができるので、
 一部の引数は <tt>@macro</tt>、一部の引数は <tt>@value</tt> レイヤで受け取る関数を書くなど、
@@ -559,12 +567,12 @@
 配列メンバは cons リストになって入ってきます。
 自分で構文木を作る時は、<tt>pos</tt> フィールドだけは省略しても構いません。
 </p>
 ))
-$(SECTION 微妙なところ, $(SECBODY
+$(SECTION 微妙なところ１, $(SECBODY
 <p>
-ここまで、<tt>@macro</tt> が本当にただの１レイヤであるかのように説明してきましたが、
-実はちょっと幾つかのトリックが潜んでいます。
+ここまで、<tt>@macro</tt> が本当にただの１レイヤと説明してきましたが、
+実はちょっとトリックが潜んでいます。
 </p>
 <pre>
     &gt;&gt; @macro twice(x) {x; x} in twice($(B @value)(print("Hello")))
     Hello
@@ -572,40 +580,72 @@
     Hello
 </pre>
 <p>
 先ほどの例に <tt>@value</tt> を増やしたものですが、これでもやはり、Hello
-が２回 print されるようになります。
+が２回 print されるようになります。これは本来はおかしな話で、<tt>print("Hello")</tt>
+は <tt>@value</tt> レイヤで実行されて値に落ちるはずなので、１回しか print されないはず。
+</p>
+<p>
+実は、Polemy の中では、<tt>@macro</tt> レイヤと <tt>(rawmacro)</tt>
+レイヤという二つの異なるマクロ用レイヤが動いています。
+</p>
+<ul>
+	<li><tt>(rawmacro)</tt> も <tt>@macro</tt> も、コードを動かすとその構文木を返す意味論。</li>
+	<li>ただし、<tt>(rawmacro)</tt> も <tt>@macro</tt> も、
+		<tt>@macro</tt> レイヤに値のセットされた変数をみつけたときは、
+		その変数という構文木を作るのではなく、変数の内容を展開。</li>
+	<li>また <tt>@macro</tt> は、
+		レイヤ指定式を見ると実行レイヤを切り替て、構文木生成モードをやめてしまう。</li>
+	<li><tt>(rawmacro)</tt> は、
+		レイヤ指定式を見ても実行レイヤを切り替えないで構文木にする。</li>
+</ul>
+<p>
+ユーザーから直接 <tt>(rawmacro)</tt> は呼べませんが、
+「関数やトップレベル実行開始前のマクロ処理は <tt>(rawmacro)</tt> で実行開始」
+「<tt>@macro</tt> レイヤ以外で呼び出した関数の仮引数に <tt>@macro</tt> がついていたら、
+その実引数は <tt>(rawmacro)</tt> で実行」
+という２つのタイミングで <tt>(rawmacro)</tt> が動き出します。
+<tt>(rawmacro)</tt> が <tt>@macro</tt> レイヤから変数を見つけてマクロし始める時に、
+そこで <tt>@macro</tt> に動作が移ります。
+</p>
+<p>
+こうなっているのは、全部がレイヤ指定式に反応する <tt>@macro</tt> の動作だと、
+レイヤを使ったプログラムが全て <tt>@value</tt> 実行時ではなく、
+マクロ展開の時点で動き始めてしまって、おかしなことになるためです。
+色々考えた結果、とりあえずこの中途半端な混合が具合がよいのではないかということになりました。
+</p>
+))
+$(SECTION 微妙なところ２, $(SECBODY
+<p>
+「関数実行開始時に、まずマクロレイヤを実行」と書きましたが、この時、関数内関数まで辿りにいくので、
+何重にもネストした関数を使っていると、内側の関数は、何重にもマクロ展開が走ってしまいます。
+これはなにかおかしい気がしますね。Scheme などはどうなっているのか調べないと…。
+</p>
+))
+$(SECTION 微妙なところ３, $(SECBODY
+<p>
+これはエラーになります。
 </p>
 <pre>
-<tt>@macro</tt> レイヤと <tt>(rawmacro)</tt> レイヤという二つが協調して動作しています。
-   (rawmacro) レイヤの話
-
-      [[limitations]]
-
-   This @macro layer is a very primitive one, and not a perfect macro language.
-   Two major limitations are seen in the following "it" example.
-
-     >> @macro LetItBe(x, y) { let it = x in y };
-
-   The variable name is not hygenic, and so without any effort, the syntax tree "y"
-   can access the outer variable "it".
-
-     >> def foo() { LetItBe( 1+2+3, it*it ) }
-     >> foo()
-     36
-
-   Of course, this is not just a limitation; it can sometimes allow us to write
-   many interesting macros.
-
-   The other problem is that the macro expansion is only done at function startup.
-   So 
-
-     >> LetItBe( 1+2+3, it*it )
-     ...\value.d(173): [<REPL>:24:1] variable LetItBe is not set in layer @value
-
-   you cannot directly use the macro in the same scope as the definition.
-   You need to wrap it up in a function (like the foo() in the above example).
+    &gt;&gt; let _ = (@macro twice(x) {x;x} in twice(print("Hello")))
+    polemy.failure.RuntimeException@C:\Develop\Projects\Polemy\polemy\value.d(109):
+    [<REPL>:2:35] 'twice' is not set in @value layer
 </pre>
+<p>
+どういうことかというと、<tt>@macro</tt> で定義したマクロはいつから使えるようになるかという話で、
+この <tt>@macro twice(x) {x;x} in ...</tt> の部分は <tt>@value</tt> レイヤの式なので、
+まずこの式全体のマクロ展開が終わったあとにしか実行されないのです。<tt>twice</tt>
+がマクロと見なされはじめるのは、<tt>@macro</tt> 実行が終わった後。
+なので、
+例えば <tt>twice(print("Hello"))</tt> の部分を無名関数にラップしてやれば、
+マクロ展開を遅らせられて、 ちゃんと実行ができます。
+</p>
+<p>
+これだと余りにも不便なので、関数のトップレベルの変数宣言式の列についてだけは、
+<tt>@macro</tt> と <tt>@value</tt> の評価を交互にインターリーブするようにしました。
+「関数やREPLのトップレベルの最初に宣言したマクロだけは、その関数内で即座に使える」わけです。
+これも Scheme の let-syntax などなどの動きを調べて勉強しないと…。
+</p>
 ))
 )
 ))