技術書典6に参加します
今回も技術書典にサークル参加します。ブースは「か54」です。
今回の本は、メタプログラミングRuby第2版の内容を追いかけつつ、現実のプログラミングという世界ではどのようにメタプログラミングが利用されているのかを解説する本です。具体的には、Sinatraのコードのなかからメタプログラミングが用いられている箇所をピックアップして、それを教本に従って解説します。
メタプログラミングRuby第2版は、本の中でいくつか現実のコードを出して解説をしている箇所がありますが、いずれも断片的で複数の巨大なコードベースにまたがったものなので、追跡が難しいです。そこで、Sinatraというミニマルなコードベースの中から、強力なメタプログラミングを使っている箇所を取り出し、それがプロダクトに対してどのような意味を持っているのかを考えていきます。
本を書いた環境
こっちが本題です。
前回の技術書典5では、StackEdit+GitBookという環境で執筆を行いました。これはいくつかの要件があったけれど、最終的になんかいろいろうまく行かなくてこうなってしまった、という環境の成れの果てです。詳細は前回のブログを見てください。
今回の環境
いくつかの選択肢がありましたが、今回は最初からRe:VIEWを使って本を書くことに決めました。理由としては、次にあげるいくつかの前回の反省があります。
-
GitBookの成果物は、印刷するのにやや難がある
-
Markdownから望むRe:VIEWの形式に変換するのには、現実的に無理がある
-
というよりも、そもそも文章フォーマットの相互変換に無理がある
Markdownで執筆したものを、望むような形で印刷可能なPDFに変換することは、もはや無理だと悟ったというのが最も大きな理由です。PandocやSphinxも、変換は行ってくれますが結局の所は出力の形式が望んだものになるかどうかは確かではありません。そうなった場合、PandocやSphinxの気持ちを感じながらMarkdownを修正していくということはもはや不可能です。ならば最初から余計な相互変換を持たないRe:VIEWを使うべきだという結論になりました。複数の入力を受けつけ、複数の出力をしてくれるソフトは確かに便利ですが、アンコントローラブルになる箇所が多く、執筆時間が限られているときには選択が難しかったのです。
幸い、Re:VIEWのフォーマットは比較的わかりやすく、リストなどにやや不満はありつつも十分に1日で書けるようになるものでした。そのため、今回は最初からRe:VIEW形式で執筆を行おうと考えました。しかしその一方で、いくつか諦める必要のあるものもありました。
-
ライブプレビュー
-
クラウドエディタ
この二点です。
ライブプレビューに関しては、まあそれはそうという感じしか無く、都度ビルドして確認することしかできません。
クラウドエディタに関しては、まあクラウドエディタでRe:VIEWファイルを書けば良いので特に諦める必要はなかったのですが、EditStackに不満を持っていた私はあれからもっと良いクラウドエディタに出会っていませんでした。良いエディタという意味で言えば、esa.ioはかなり気に入っています。しかし、これはMarkdownに特化しているため、使えませんでした。
しかし、原稿をクラウドエディタで書くことを諦められなかった私は、考えました。結果、Re:VEIWフォーマットとMarkdownはなんとなく似てないこともなかったので、今回はまず概要と草稿をesa.io上で執筆し、そのMarkdownデータを手でRe:VEIWに変換した上で、本を作るための細かな命令などを手元のエディタで行いました。おそらく、技術書を書く上で一番つらいのは、最初の草稿をあげるまでで、そこから先は多少の原稿の修正と、印刷用のマークアップ作業です。なので、その辛い箇所をクラウドエディタでなんとかして、機械的にちかい作業はローカルのエディタで行うように分担したのです。
最終的に、Re:VIEWのファイルはGitで管理してGitHubにプッシュしていたので、GitHub上からクラウドエディタのようなこともできなくはなかったですが、それはやらなかったです。
用意した環境
最終的に用意した環境は次のとおりです
-
esa.ioで草稿執筆
-
vimでRe:VIEWファイルへ書き換え
-
文章の管理はGitHub
-
Dockerコンテナでビルド
CI等は使っていません。複数人で執筆なら必要だったと思いますが、一人の場合は手元でガンガンビルドするので、特に恩恵はないと思ったからです。
Dockerのイメージには、[vvakame/docker-review: Re:VIEW build container by docker](https://github.com/vvakame/docker-review) を使わせてもらいました。
問題点
草稿までをMarkdown+クラウドエディタで書き、仕上げをRe:VEIWとGitで行うというのはなかなかいい選択肢でした。ただ、問題も一つありました。Re:VIEWは、TeXを中間表現として使っているという点です。
印刷用にマークアップを施し、Re:VEIWで実際にPDFを出力してみて、何か調整したいと思ったときに求められるのは、TeXの知識なのです。残念なことに、私は情報系にしては珍しく大学でTeXを学ぶことがなく、またその後も学ぶつもりがなかったので、TeXのことが全くわかりませんでした。
今回の原稿で具体的に困ったのは、引用したソースコードが行番号付きリストの横幅に収まらなかったケースです。何かしらの方法で改行が必要でしたが、そのために必要だったのはTeXの知識でした。
[【Re:VIEW】表のセル内でURLを折り返しする方法 - himajin315の記録](http://d.hatena.ne.jp/himajin315/20150312/1426146268)
[Re:VIEWで長い文字列を折り返すためにやったこと - patorashのブログ](https://patorash.hatenablog.com/entry/2018/12/12/160511)
これらのページに行き着いても、TeXのことが書いてあって、雰囲気ではわかっても何かエラーが発生したときにそれがどういう原因で出て、どうやって治すのかの当たりをつけるのに困難を極めました。私がうまく行かなかった理由は、設定を記述する順番が間違っていたというものでしたが、そんなもんわかるかという感じです。
とはいえ、Re:VIEWの良い点は、日本語のドキュメントが充実している点と、Twitterで泣き言を言っていると作者の方が拾ってくれたりするところです。
マジでやばい、Re:VIEWでソースコードが横に長過ぎてあふれちゃうから改行したい（ただし行番号はそのままで）みたいなのができない、技術書典の原稿がおちる > > -- kinoppyd (@GhostBrain) [April 6, 2019](https://twitter.com/GhostBrain/status/1114582738223259648?ref_src=twsrc%5Etfw)
昨日似たような話があったような。対案です＞ [https://t.co/52t50ZynVX](https://t.co/52t50ZynVX) > > -- kmuto (@kmuto) [April 6, 2019](https://twitter.com/kmuto/status/1114677623102136322?ref_src=twsrc%5Etfw)
これは本当に助かりました……
次回の執筆環境
今回、Re:VIEWはとてもいいソリューションだと思いました。Markdown2Re:VIEWは諦めて、最初からRe:VIEWで書くことをおすすめします。細かい表現とか、変換時に失われますし。
クラウドエディタに関しては、いくらか思うところがあるので、次回までにはまたいろいろと選定したいと思っています。