「TWE-LiteのArduino化」のコピー本を作った話

これはなに？

前回アップしたステマ記事が
割と好評でしたので、その元ネタとなったコミックマーケット88で頒布したコピー本を
原稿ごとgithubに上げておきました。

PDFはこちら。https://github.com/soburi/jn5164-twelite-guided-tour/raw/master/publish/jn5164-twelite-guided-tour-publish.pdf

前回の記事の方では、TWE-LiteをArduino化して使う方法を紹介させていただいたのですが、
コピー本の方では、その「Arduino化」の方法、Arduinoのマイコン部分のソースを
他のアーキテクチャ(TWE-Lite)に移植する方法をハンズオンで紹介しています。
ということで、読者として以下のような層を想定した記事となっています。

• オレオレArduinoを作成したい方
• Arduinoのabyssな部分を見たい方

ストライクゾーンの狭い記事ではあるのですが、何か
刺さるものがあるようでしたら、ご高覧いただけると幸いです。

ところで、このコピー本はRe:VIEW+md2reviewの環境で作成を行ってます。
markdownを使っている故の生産性の高さ、内部的にTeXで処理を
行うRe:VIEWの出力品質の高さがあり、効率よくハッタリの効いた
文書が作成できます。
技術系同人誌の制作の敷居を下げられるメソッドかと思うので、
「雑な技術系同人誌を作成する(多少偏った)ノウハウ」として紹介します。

Re:VIEW, md2reviewについて

Re:VIEWは書籍、電子出版のためのマークアップ言語と、そのフォーマットを
行う組版システムです。
利用実績
にあるように、実際の出版でも活用されており、市販に堪えるクオリティの出力が
できます。バックエンドにTeXを利用しており、論文とかで使われたことがあれば、
出力品質の高さはご存知かと思います。

md2reviewは簡易マークアップ言語の
MarkdownをRe:VIEWのマークアップ言語に変換するツールです。
これと組み合わせることで、ゴリゴリ書けるMarkdownの生産性と、TeX由来の「美文書」の
クオリティを両立して紙ベースのドキュメント作成が行うことができます。

環境のセットアップ

Cygwin, Ruby, TeXLive のインストール

cygwinのインストーラを実行し、
cygwinをインストールします。
ruby, texlive関連も必要なので、以下のパッケージもインストーラで指定してインストールします。

• ruby
• rubygems
• gcc-core
• make
• libcrypt-devel
• libgmp-devel
• texlive
• texlive-collection-fontsrecommended
• texlive-collection-latex
• texlive-collection-latexextra
• texlive-collection-latexrecommended
• texlive-collection-langjapanese

review, md2review

メインのツールとなるreview, md2reviewはrubygemsでインストールします。
Cygwin のターミナルから、

gem install review
gem install md2review

と実行します。 md2reviewの実行可能ファイルが~/binに置かれますが、
ここにパスは通っていないので、

export PATH=$PATH:~/bin

でパスを通します。これでRe:VIEWの文書作成環境とmarkdownを処理する環境が整います。

md2reviewの改造 (optional)

2016/05/10 追記

文中の等幅フォント指定は一般的なmarkdownの``記法が使えました。
http://qiita.com/Qiita/items/c686397e4a0f4f11683d#code---%E3%82%B3%E3%83%BC%E3%83%89%E3%81%AE%E6%8C%BF%E5%85%A5

このため、このセクションの内容は不要な内容だったため、記載を訂正いたします。

プログラミング関連の技術書ではコード中のシンボルを文中で表現するため、
等幅フォントを使う場合があります。md2reviewではこの表記ができないので、
* ... * の強調の等幅フォントの指定に置き換える細工を入れています。
(md2reviewのMarkdownはRedcarpetの仕様に
依っており、方言の少ない割とピュアなMarkdownなので細工の入れどころも少ない)

[home].gem\ruby\gems\md2review-1.6.0\lib\redcarpet\render\review.rb
のファイルの

      def emphasis(text)
        "@<b>{#{escape_inline(text)}}"
      end

を

      def emphasis(text)
        "@<tt>{#{escape_inline(text)}}"
      end

のように改造します。
これで * ... * もしくは _ ... _ で囲まれた部分が等幅フォントになります。

文書の設定

Re:VIEWの基本設定

まず、

review-init [フォルダ名]

を実行して文書の雛形を作ります。
これで作成されるconfig.ymlに必要な設定を埋めていきます。

• bookname 作成されるファイル名. epubでなければ特にこだわらなくて良い。
• booktitle 書名.ここはフリーフォーマット
• aut 著者名. 実名でもハンドル名でもペンネームでも。
• prt 出版社名. 同人誌ならサークル名でも入れておきましょう。
• date 発行日を記入
• rights (C)表記

体裁にかかわるところも指定します。

• titlepage trueにすると表紙を出力する。pdfを編集して差し替えるためtrueにしておく。

• toc 目次を作る場合true.

• toclevel このレベルまで目次として使う. ページ数が増えすぎないようtoclevelを調整する。

• secnolevel このレベルまでセクション番号が振られる.

• texdocumentclass texのドキュメントクラスの指定. フォントサイズの指定に必要.

具体的な指定は紹介事例
を参照してください。

Rakefileの修正

review-initで生成されるRakefileは.mdファイルから変換する動作が
定義されていないので、この定義を作成する必要があります。
また、config.ymlの設定を反映していないので、これを反映するよう修正します。

.md→.re ルールの追加

md2reviewを使って、.mdファイルから.reファイルを生成するルールを
Rakefileに追加します。
以下のコードをRakefileの末尾に追加。

rule '.re' => ['.md'] do |t|
  sh "md2review #{t.source} > #{t.name}"
end

.reファイルを.mdファイルから生成するため、.mdファイルの拡張子を置き換えたリストを
review-pdfmakerの入力に取るように変更します。

SRC = FileList['*.re'] + [CONFIG_FILE]

を

SRC = FileList['*.md'].collect{|f| f.gsub(/\.md$/, '.re')} + [CONFIG_FILE]

のように修正します。
ruleで依存関係が定義されているので、.reファイルが無い場合や
.mdファイルが更新された場合には、md2reviewが実行されて.reファイルが再生成されます。

clean時には生成された.reファイルも消したいので、末尾に以下の行を追加します。

CLEAN.include( FileList['*.re'] )

config.ymlの反映

雛形のRakefileはconfig.ymlから生成されるファイル名を反映しないので、

BOOK = "book"

の行を以下のように修正します。

require 'yaml'
BOOK = YAML.load_file('config.yml')['bookname']

これで文書を書くための下準備が完了しました。

rake pdf

を実行してpdfが生成されることと、

rake clean
rake pdf

で、ファイルのcleanと再度pdfの生成がうまく実行できることを確認します。

執筆する

文書の体裁は通常のmarkdownのルールに従うため、markdownを理解しているのであれば
特に説明は不要なはず。

勢いに任せてMarkdownをゴリゴリ書きます。

ページが増えた場合にはは、catalog.ymlで書籍に含まれる.reファイルを指定しているので、
ファイルの追加を行った場合にはこれに追加します。.mdではなく.reのファイル名を指定することに注意。

体裁など

md2reviewでpdfを生成する場合、一旦TeXを経由して変換するので、
書式などのレイアウトはTeXのスタイルファイルで行います。

よくある設定の文書余白の設定は、sty/reviewmacro.styに

\geometry{top=20mm,bottom=15mm,left=15mm,right=20mm}

のように記載することで可能です。
この辺の詳細は、pLaTeX2e 新ドキュメントクラス
の情報を参照のこと。

印刷用に整形する

印刷に適当な体裁に整えるために、出来上がったPDFのファイルをページ単位で切り貼りしたりして整形します。
この作業は文書の構成などで様々なやり方が考えられるのですが、
ここでは著者の事例(ローコストな造りのコピー本)として紹介します。

冊子のレイアウト

今回のドキュメントは、以下のような条件で作成しています

• A4の2つ折りでA5版の冊子にする
• 表紙はカラー刷り
• コピー本なので当然コピー機で刷る
• 極少部数なので手製本でも構わない

表紙だけカラーにしたいので、kinko'sあたりの
高性能コピー機についているホチキス綴じ機能は使わないで自前でページの面付けを行いました。

全面モノクロ、もしくは全面カラーであれば、kinko's のコピー機で
面付け・中綴じまでやってくれるので、冊子のになった状態で
出てきます。現地製本しなくてよいので楽チンです。

別の言い方をすると、この後のセクションはこのkinko'sのコピー機が
よろしくやってくれる作業を自前で行う手順ということになります。

pdfjamのインストール

印刷のための後処理でPDFの操作を行うために
PDFjam
をインストールします。
PDFjamはスクリプトで構成されているので、圧縮ファイルのbinフォルダの中身を~/binに
設定ファイルのpdfjam.confを/etcにコピーします。

ページの配置

TeXのjsbook.clsでは、第一章が左ページに配置されますが、ページの構成が図のようになるので、

表紙を除いた文面については、右開きとなるように配置します。
そのため、目次を1ページ分配置して、本文始りが左ページにレイアウトされるようにします。
(目次を1ページに収まるよう調整しています)

PDFjamを使うことでRe:VIEWが出力したPDFファイルから
特定のページを抜いたり、入れ替えたりできます。
これで、Re:VIEWの出力したPDFから、本文印刷用のPDFファイルと
表紙用のPDFファイルの2つを作って、それぞれモノクロとカラーで印刷しています。

今回Re:VIEWで生成したPDFは以下のようなページの構成で、

• 1ページ 表紙
• 2ページ 目次
• 3ページ 空白ページ
• 4ページ～ 本文
• 最後のページ 奥付

1ページの表紙、3ページの空白ページ、最後の奥付を除いた部分が実際の文面に
なっています。

pdfjamによる面付け

pdfbookというコマンドは、2upで中綴じできるように並べ替えてくれるところまで
一発でやってくれます。
ページを指定できるので、1,3ページと最後の35ページを抜いて指定して、

pdfbook --short-edge jn5164-twelite-guided-tour.pdf '2,4-34' -o printable-body.pdf

のように実行するとprintable-body.pdfという名前で中綴じで本になるPDFができます。
ここでは、長辺綴じだと表裏で天地がひっくり返るので、--short-edgeで短辺綴じを指定しています。

両面印刷だと1枚4ページになるので、空白ページを出さないようにするためには、
ページ数が4の倍数になるよう編集する必要があります。

表紙ページは別途作成したA4,1ページのデータのcover.pdfを使用し、
Re:VIEWが生成した奥付ページを裏表紙にして、合わせて2upにします。
(あまりカッコよくはないと思いますが、コピーの原価削減のため
こんなレイアウトで。)

右側が表紙で左側が裏表紙なので、裏, 表の順で 2ページを合わせます。

pdfnup --nup 2x1 jn5164-twelite-guided-tour.pdf 35 cover.pdf 1 -o printable-cover.pdf

これで、本文ページ、表紙ページのデータが一式できあがります。
USBメモリに入れてコンビニのコピー機で印刷して、
ホチキスで閉じればコピー本の完成です。

頒布する

この手順で一通り、コピー本の小冊子が作れます。
ネタと勢いでmarkdownを書いていくと、なんとなく本になってるような感じです。
出来上がったら、是非イベントに参加して頒布しましょう。
技術系同人誌だと、コミケのUNIX島や評論の中の電子工作ジャンルあたりが定番かと。
忘れちゃいけないのがコストで、参加費(コミケの場合8000円)と
製造原価として2ページあたり10円のコピー代がかかります。
プログラミングのドキュメントはコードの引用を使わなければならない
ケースが多く、案外とページが膨れ上がります。 (つまり、原価が嵩む )

UNIX島について

コミケのジャンルコード201:同人ソフト の ジャンル補足:情報・評論(コンピュータ・ソフト系)
の一部、UNIX/Linuxなんぞが集まる界隈がUNIX島とか呼ばれたりしています。
(一応、島を形成できる程度の人口は居るのだ。)
マサカリを投げる余裕があるなら一冊でも多くの薄い本を買う、という人しかいないので、
きっと平和な島なんじゃないかと思います。皆様おいでませ。