ReVIEWではドキュメントの中に、外部のテキストファイルの内容やコマンドの結果を取り込む方法が用意されています。ReVIEWドキュメントの中を検索しながら編集しなくても、外部ファイルを差し替えればすべての参照箇所が書き換えられます。
特定の単語を差し込む
まずは簡単な単語差し込みを試してみましょう。ReVIEWドキュメントと同じ階層に「name.txt」というテキストファイルを用意してください。「name.txt」の中身は自分の名前を書いておきます。
ReVIEWドキュメントの方は「name.txt」を参照するためにインライン要素@<include>{pathname}を使います。たとえば、実際にはこうなります。
私が担当の@<include>{name.txt}です。
このReVIEWドキュメントからHTMLを生成すると、「name.txt」の内容を差し込みしました。
このname.txtにはReVIEW記法が使えます。テキストの差し込みが行われた後に、ReVIEW記法が評価されているようです。
ちなみに、@<include>{pathname}はパスを理解するので、「name.txt」がimagesディレクトリの中にあれば、@<include>{images/name.txt}と書けるでしょう。
段落を含んだ文章を差し込む
@<include>{pathname}はあくまでインライン要素として文中に差し込むためのコマンドです。別管理されたコードリストなどの外部ファイルの内容など、複数行の段落にわたるブロックとして取り込みたいときには、ちょっと手順を踏む必要があります。
（1）外部ファイルを用意する
ここでは「script.rb」というテキストファイルを用意しました。
（2）オリジナルReVIEWドキュメントにファイル指定する
オリジナルReVIEWドキュメント「ch02_org.re」の中の挿入位置に下記マーキングをします。
#@mapfile(script.rb) #@end
（3）review-preprocコマンドで外部ファイルをマージする
ターミナルから下記review-preprocコマンドをタイプします。
$ review-preproc ch02_org.re > ch02.re
プリプロセッサで生成した「ch02.re」を見てみましょう。
「script.rb」の内容が「ch02.re」の中に挿入されているのがわかります。あとで「script.rb」の中を修正したとしても、プリプロセッサで再マージすれば常に新しいReVIEWドキュメントが生成されます。「#@mapfile(script.rb)」と「#@end」の行は「ch02.re」内に残っていますが、「review-compile」コマンドで変換時、EPUBやXMLなどの最終生成物には残りません。
一連の手順を図にするとこんな感じになります。
「#@mapfile(pathname)」で展開されるテキスト中にあるタブ文字は、すべてスペースに変換されますから注意してください。もしタブ文字のままであったら、表組みのTSVなども差し込みできるのになあ... と思います。
外部ファイルの一部だけを利用する
外部ファイルの一定の範囲だけを選択的に差し込むためには
#@maprange(filepath, rangename) #@end
を使うらしいのですが、ちょっとよくわかっていません。MLでそれらしい議論もあるのですが...
外部ファイルを読み込む記法 - qwik.jp/review
詳細が分かり次第、追記したいと思います。
コマンドの実行結果を取り込む
「#@mapoutput(コマンド) 〜 #@end」を使えば、コマンドの実行結果を取り込むことができます。
たとえば、今年の年号を表記する時などはこのように書くことができます。
#@mapoutput(date +"%Y") #@end
review-preprocコマンド後には展開されてこうなります。
review-compileでHTMLを生成するとこうなります。
コマンドで展開できるのは、既存のアプリケーションだけではありません。テキストを返すものならば、自作のスクリプトでもよいのです。たとえば、昨日こちらのアップした「特定のTweet引用時の正書法」をつかってみましょう。
#@mapoutput(ruby19 cite_a_tweet.rb "https://twitter.com/#!/never4get_jp/status/178718486745452544") #@end
review-preprocコマンド後には展開されてこうなります。
review-compileでHTMLを生成するとこうなります。
