PIYO - Tech & Life -

md2review+ReVIEW+guard+livereloadで快適ドキュメントライティング

ReVIEW Ruby

先日はてなで見かけたこちらの記事みて自分なりにやってみたいことがでてきたのでそれについてメモってみます。

Markdown記法+Git+md2review+ReVIEWで原稿・ドキュメント管理 - プログラマになりたい

[http://d.hatena.ne.jp/dkfj/20131215/1387093204:image:large]

やりたいことというのはこんな流れです。

  • Markdownでドキュメントを書く
  • 自動でHTMLに変換しタブをリロード
  • PDFに清書（？）する

先の記事の方は手動で変換をかけているようですが、僕はそこを自動化してみようと思います。

pandocについて

そもそも僕は上のようなドキュメントライティングプロセスをpandocを用いて行っていました。それがこちら。

pi-chan/Pandoc-Guard

PandocはMS Wordのドキュメントを生成できるのであるとき仕事で使ったことがありますが、見た目が超見づらいです。正直使い物にはなりませんでした。ですが、Markdownで書いてHTMLで読めるというところはとても良いです。

今回はReVIEWというものがどの程度使えるかを知ってみようと思います。

登場するソフトウェア

Guard

ファイルの変更を監視して、変更があったら何かするといった自動化をサポートするRubyのソフトウェア。

LiveReload

ブラウザで開いているWebページを自動的に更新するツールで、Guardと連携して特定のファイルが更新されたら特定のタブを更新するといった機能を実現できる。

md2review

Markdown形式で書かれたテキストファイルをReVIEW形式に変換するRubyプログラム。

ReVIEW

ReVIEW用のフォーマットからHTMLやTeX、PDFなど様々なフォーマットに変換可能な電子書籍向けフォーマットとそのプログラム群。

サンプル環境

（おそらく）簡単に導入できるであろう環境を作ってみました。

pi-chan/review-livereload

Guardで*.mdと*.htmlを監視する

# Guardfile
guard 'shell' do
  watch(/.*markdown\/(.*)\.md$/) do |m|
    `./bin/md2review #{m[0]} > review/#{m[1]}.re`
    Dir.chdir("./review") do
      `../bin/review-compile --target=html #{m[1]}.re > ../html/#{m[1]}.html`
    end
    puts "built #{m[1]}.html"
  end
end

guard 'livereload', :apply_js_live => false do
  watch(%r{html/.+\.(html)})
end

markdown/ 以下の*.mdファイルを監視して、変更があったらmd2reviewコマンドでReVIEW形式に一旦変換します。その後review-compileコマンドでHTMLファイルを生成します。

2番めのwatch文ではhtmlディレクトリ以下のhtmlファイルを監視しており、htmlに変更があった場合にそのファイルを開いているブラウザタブを更新しにいきます。つまり、Markdown形式のファイルを更新するとブラウザが勝手にリロードして確認できるというわけです。

スタティックファイルをサーブするWebサーバーを起動する

ローカル用のウェブサーバーなのでRubyで気軽に起動する方法をとりました。

bundle exec ruby -run -e httpd -- --port=5000 ./html

スタイルシートを指定する

review-compileコマンドではスタイルシートを指定することもできます。これをやらないと見た目がプレーンすぎて味気なく、テンションがあがりません。

review-compile --target=html --stylesheet=style.css input.re > output.html

このように書くと生成されるhtmlファイルにstyleタグが生成されます。相対パスで書かれるのでウェブサーバーやhtmlファイルのパスに注意が必要です。

章立て

記事を書きながら使っていて気がついたのですが、複数ファイルあると複数の章立てになるんですね！これはうまく使うとすごく便利？だけど、1ファイルごとに独立させたい場合はちょっと不便なのかも。

pandocとの比較

様々な入出力に対応しているという点ではpandocのほうが優秀かも。だけど、ReVIEWが標榜しているように書籍などの長めの文章を書く際はReVIEWのほうがいいのかな。

今回はReVIEWを使い倒すというわけではなく、ReVIEWをカジュアルに使ってmarkdownでドキュメントを書いてみようという話でした。