Merge pull request #632 from kmuto/doc-preproc

add preproc(.ja).md

doc/preproc.ja.md

@@ -0,0 +1,153 @@
+# review-preproc ユーザガイド
+
+Re:VIEWではソースコードなどを本文中に埋め込むことができます。
+
+## `#@mapfile`
+
+以下は`scripts/hello.rb`のソースを本文内に埋め込んでいます。
+
+```review
+//list[hello.rb][hello.rb]{
+#@mapfile(scripts/hello.rb)
+#!/usr/bin/env ruby
+
+class Hello
+  def hello(name)
+    print "hello, #{name}!\n"
+  end
+end
+
+if __FILE__ == $0
+  Hello.new.hello("world")
+end
+#@end
+//}
+```
+「`#@mapfile(ファイル名)`」から「`#@end`」は、指定したファイル名のファイル全体を本文中に埋め込むための記法です。埋め込む際には、`review-preproc`コマンドを実行します。
+
+まず、以下のように、引用したい部分に「`#@mapfile()`」と「`#@end`」だけを書きます。ここでは`//list`ブロック内にこの２行だけを記述しています。
+
+```review
+//list[hello.rb.1][hello.re]{
+#@mapfile(scripts/hello.rb)
+#@end
+//}
+```
+このソースに対して、`review-preproc`コマンドを実行します。すると、変換結果の*.reファイルを標準出力に出力します。
+
+```shell-session
+$ review-preproc hello.re
+```
+`--replace`オプションをつければ、ファイルそのものを置き換えるようになります。
+
+```shell-session
+$ review-preproc --replace hello.re
+```
+
+なお、rakeを使ってビルドしている場合、Rakefileに以下のような記述を追加すると、このコマンドを実行するtaskが定義されます。
+
+```rake
+desc 'preproc all'
+task :preproc do
+  Dir.glob("*.re").each do |file|
+    sh "review-preproc --replace #{file}"
+  end
+end
+```
+
+以下のように実行すれば、コマンドが実行されます。
+
+```shell-session
+$ rake preproc
+```
+
+## `#@maprange`
+
+対象ファイルの一部だけ抜粋することもできます。こちらは「`#@maprange`」という記法を使います。
+
+対象ファイルの抜粋したい部分の前後に、「`#@range_begin(ID)`」と「`#@range_end`」という記法を埋め込んでおきます。`#@range_begin`の引数には、その断片を抽出する際に使用するIDを指定します。以下の例では「sample」というIDにしています。
+
+```ruby
+#!/usr/bin/env ruby
+
+class Hello
+#@range_begin(sample)
+  def hello(name)
+    print "hello, #{name}!\n"
+  end
+#@range_end(sample)
+end
+
+if __FILE__ == $0
+  Hello.new.hello("world")
+end
+```
+*.reファイルの方には、「`#@mapfile(ファイル名)`」ではなく「`#@maprange(ファイル名,ID)`」を記述します。
+
+```review
+//list[range.rb][range.rb(抜粋)]{
+#@maprange(scripts/range.rb,sample)
+#@end
+//}
+```
+
+あとは、先ほど同様、`review-preproc`コマンドか`rake preproc`コマンドを実行します。そうすると、`scripts/range.rb`の一部が抽出されて埋め込まれます。
+
+```review
+//list[range.rb][range.rb(抜粋)]{
+#@maprange(scripts/range.rb,sample)
+  def hello(name)
+    print "hello, #{name}!\n"
+  end
+#@end
+//}
+```
+
+## `#@@maprange`
+
+もっとも、Ruby以外では「`#@range_begin`」などがコメントと解釈されないこともあります。そのような場合、その言語のコメントの中に「`#@@range_begin`」と「`#@@range_end`」とを記述します。
+
+Cのソースを例にします。対象となるrange.cは以下です。
+
+```c
+#include <stdio.h>
+
+/* #@@range_begin(sample)  */
+void
+put_hello(char *name)
+{
+  printf("hello, %s!\n", name);
+}
+/* #@@range_end(sample) */
+
+int main()
+{
+  put_hello("world");
+}
+```
+
+put_hello関数の定義の前後で「`#@@range_begin`」と「`#@@range_end`」が使われています。
+
+これに対し、*.reファイルでは`#@maprange(scripts/range.c,sample)`と`#@end`を記述します。
+
+```
+//list[range.c][range.c(抜粋)]{
+#@maprange(scripts/range.c,sample)
+#@end
+//}
+```
+
+変換した結果、以下のようになります。
+
+```
+//list[range.c][range.c(抜粋)]{
+#@maprange(scripts/range.c,sample)
+void
+put_hello(char *name)
+{
+  printf("hello, %s!\n", name);
+}
+#@end
+//}
+```
+このようにすると、Cなどの言語のファイルに対しても、ソースの一部を抽出して埋め込むことができます。

doc/preproc.md

@@ -0,0 +1,160 @@
+# `review-preproc` User Guide
+
+Re:VIEW has a preprocessor, `review-preproc`.  It can embed a (part of) file into *.re files.
+
+## `#@mapfile`
+
+The code below is a sample of embedding code from `scripts/hello.rb`.
+
+```review
+//list[hello.rb][hello.rb]{
+#@mapfile(scripts/hello.rb)
+#!/usr/bin/env ruby
+
+class Hello
+  def hello(name)
+    print "hello, #{name}!\n"
+  end
+end
+
+if __FILE__ == $0
+  Hello.new.hello("world")
+end
+#@end
+ //}
+```
+
+`#@mapfile(filename)` and `#@end` are markers for preprocessor.  You can embed and update the content of the file `filename` into Re:VIEW file with `review-preproc` command.
+
+First, add `#@mapfile()` and `#@end` on the document.
+
+```review
+//list[hello.rb.1][hello.re]{
+#@mapfile(scripts/hello.rb)
+#@end
+//}
+```
+
+Then execute `review-preproc` command.  The command display the result on stdout.
+
+```shell-session
+$ review-preproc hello.re
+```
+
+With `--replace` option, `review-preproc` replaces the Re:VIEW file.
+
+```shell-session
+$ review-preproc --replace hello.re
+```
+
+If you use `rake` to build Re:VIEW document, you can add the code to Rakefile to define a task of `review-preproc`.
+
+```rake
+desc 'preproc all'
+task :preproc do
+  Dir.glob("*.re").each do |file|
+    sh "review-preproc --replace #{file}"
+  end
+end
+```
+
+Then, you can execute preprocessor with `rake`.
+
+```shell-session
+$ rake preproc
+```
+
+## `#@maprange`
+
+You also can embed a part of the target file with `#@maprange` marker.
+
+Add `#@range_begin(ID)` and `#@range_end` in the target file you want to embed.
+In `#@range_begin(ID)`, you must add ID as parameger to identify the part.
+
+In the code below, `sample` is the ID of the range to embed.
+
+```ruby
+#!/usr/bin/env ruby
+
+class Hello
+#@range_begin(sample)
+  def hello(name)
+    print "hello, #{name}!\n"
+  end
+#@range_end(sample)
+end
+
+if __FILE__ == $0
+  Hello.new.hello("world")
+end
+```
+
+In *.re file, add `#@maprange(filename,ID)`, instead of `#@mapfile(filename)`, and `#@end`.
+
+```review
+//list[range.rb][range.rb(partial)]{
+#@maprange(scripts/range.rb,sample)
+#@end
+//}
+```
+
+After that, execute `review-preproc` or `rake preproc`, and you get the *.re files embedded the `hello` method in `scripts/range.rb`.
+
+```review
+//list[range.rb][range.rb(partial)]{
+#@maprange(scripts/range.rb,sample)
+  def hello(name)
+    print "hello, #{name}!\n"
+  end
+#@end
+ //}
+```
+
+## `#@@maprange`
+
+But in some language, a line `#@range_begin` is not a comment.  If you want to embed some code of such languages, you can use new markers `#@@range_begin` and `#@@range_end` into a comment in the target document.
+
+Let's explain how to do.  A target file `range.c` is below:
+
+```c
+#include <stdio.h>
+
+/* #@@range_begin(sample)  */
+void
+put_hello(char *name)
+{
+  printf("hello, %s!\n", name);
+}
+/* #@@range_end(sample) */
+
+int main()
+{
+  put_hello("world");
+}
+```
+
+There are markers `#@@range_begin` and `#@@range_end` around `put_hello` method.
+
+In `*.re`, add `#@maprange(scripts/range.c,sample)` and `#@end`.
+
+
+```
+//list[range.c][range.c(抜粋)]{
+#@maprange(scripts/range.c,sample)
+#@end
+//}
+```
+
+With `review-preproc`, we get the result of conversion like below:
+
+```
+//list[range.c][range.c(抜粋)]{
+#@maprange(scripts/range.c,sample)
+void
+put_hello(char *name)
+{
+  printf("hello, %s!\n", name);
+}
+#@end
+//}
+```