Re:VIEW ファイルを分割する

この記事は Goodpatch Advent Calendar 2019 の2日目です．今年も2回の技術書典があり，Goodpatch の有志メンバーで参加しました．

原稿は Re:VIEW を使って作成しましたが，そのときに Re:VIEW の re ファイルを分割したいというケースがあったので，その方法を記しておきます．

概要

複数人で書籍を作るときに CHAPS ファイルに各人の re ファイルを並べたい
各人の re ファイルが大きくなるので，CHAPS に依存しない形で切り分けられるようにしたい
Re:VIEW の preproc を使って re ファイルに re ファイルを埋め込むことができる

環境

macOS 10.14.6
ruby 2.6.5p114
docker 19.03.4
- image: vvakame/review (id: 6ad892ad81bf)

Re:VIEW

Re:VIEW は書籍データを作るためのツールで，比較的簡単な独自記法で書籍データを記述できます．データは PDF（LaTeX）や EPUB など，電子書籍（に限らず）に適した形で吐き出すことができます．

技術書典に参加されている方々の紹介記事がたくさん出ているので，知っている，使っている方も多いのではないでしょうか．私もこれまで参加した技術書典では毎回 Re:VIEW を使わせてもらっています．

Re:VIEW ファイルを分割したい

これまで出版した技術書は，複数人で集まって各自が1章ずつ好きなお題で書くアンソロジー形式のものでした． Re:VIEW ファイル構成としては，各人の名前を付けた re ファイルを CHAPS ファイルに書き連ねていく形にしました．

# CHAPS
thedoritos.re
shimamura.re
shibuya.re
honda.re

こうすると最終的に上がってきた原稿の内容やページ数をみて，章立てを組み直すことが簡単にできます．ただし，各人につき re ファイルがひとつになるので，ファイルが大きくなりがちという点は気になります．

そこで re ファイルを分割するという下記の方法に思い至りました．ファイルを分割できると，章の中の節を差し替えたり，落としたり，順番を変えたりといったことを共同の CHAPS ファイルと切り離して行うことができます．また GitHub などでレビューをするときにもファイル単位で確認したりチェックを入れたりできるので効率的です．

preproc

Re:VIEW には preproc という仕組みがあって，re ファイルに外部ファイルのソースコードなどを埋め込むことができます．

https://github.com/kmuto/review/blob/master/doc/preproc.ja.md

説明では Ruby や C といったプログラミング言語のソースを埋め込んでいますが，Re:VIEW の re ファイルでも問題なく埋め込むことができます．preproc を使って章の re ファイルに節の re ファイルを埋め込むことで，結果として複数の re ファイルをまとめたひとつの re ファイルを作ることができます．

#@mapfile() でファイルのパスを指定して #@end で閉じます．これを読み込みたいファイルの順番に並べます．

# thedoritos/main.re

#@mapfile(thedoritos/sections/0-0_introduction.re)
#@end

#@mapfile(thedoritos/sections/1-0_background_of_suugar.re)
#@end

#@mapfile(thedoritos/sections/2-0_concept_of_suugar.re)
#@end

ファイルのパスは preproc を実行する articles ディレクトリからの相対パスになります．埋め込み先の main.re ファイルからの相対パスではないので注意が必要でした．

review-preproc コマンドで preproc を実行して結果を出力し，ファイルに書き込めば OK です．

$ review-preproc thedoritos/main.re > thedoritos.re

Rake タスク化しておく

本家の preproc 説明にもありますが Rake を使ってビルドしている場合，preproc する Rake タスクを用意しておくと便利です．みんながみんな preproc を使うわけではないので，著者単位で指定できるようにしました．

namespace 'preproc' do
  desc 'generate doc from main'
  task :author, ['author'] do |task, args|
    sh "review-preproc #{args[:author]}/main.re > #{args[:author]}.re"
  end
end

Rake の PDF 生成手順に挟み込むなら次のようにできます．

$ rake preproc:author[thedoritos] clean pdf

まとめ・感想

複数人で書籍を作るときに CHAPS ファイルに各人の re ファイルを並べる構成をとった
各人の re ファイルが大きくなるので，re ファイルを分割したくなった
Re:VIEW の preproc を使って re ファイルに re ファイルを埋め込むことで実現できた
Rake タスク化しておくと便利だった

Re:VIEW は柔軟なツールで，複数人でひとつの書籍を一緒に書く技術書典のような形式でも便利に使うことができます．なんということのないひと工夫ですが，技術書を書く体験を向上させたい取り組みでした．

概要

環境

Re:VIEW

Re:VIEW ファイルを分割したい

preproc

Rake タスク化しておく

まとめ・感想

参考