ePubでシンタックスハイライト
OS X 10.10, Sigil 0.8.0, google-code-prettify 4-Mar-2013, Murasaki 2 1.0.2
プログラマーの仕事の9割はプログラムを記述することである。
と言いたいところではあるが、現実はそうではない。
何割くらいの負担かはともかく、かなりの割合で、プログラマーはドキュメントを書かなければならない。
設計書、運用マニュアル、デプロイ手順書、など書かなければならないドキュメントにはいくつか種類があるが、さて、プログラマが書くドキュメントは、どのようなファイル形式が適切だろうか。
いくつか候補はある。以下は私の主観であるので、あくまで参考程度に。
・Microsoft Word
論外。だが、最終的にPDFで納品することが決まっているのであれば、編集段階として使うことは多いだろう。
・Microsoft Excel
本当に表計算の機能を必要とする部分だけに限定して使うべきと思う。
Excel方眼紙反対。
・PDF
紙に印刷する前提ならばやむなし。
ただ、なんでもかんでもPDF、PDFが最小公倍数という昨今の風潮は好きではない。事務系書類ならともかく、技術文書を印字用にレイアウトするなんて、あまり考えたくないことだ。無駄な工数が発生するし、人は頑張って作ったものほど後で修正したがらない。
・プレーンテキスト
readmeファイルのように、短いドキュメントを記述する場合で、かつドキュメントを読む人がプログラマ、他技術系の人であれば、プレーンテキストが一番良いと思う。
ただ、あまりに長いドキュメントを書くのには向いていない。
読む方が大変。
せめてハイパーリンクは欲しいと思うことは多い。
・マークダウン記法のテキストファイル
そこそこ書くのが楽で、そこそこ見た目がよく、そこそこ長文でも整理しやすい。
見る人が見る場合はVimなどのテキストエディタで見てもいいし、見せる相手が相手ならば、HTMLに変換してやればいい。ここのはてな記法なんかも結構書きやすい。（使いこなしてないけど）
わりと良い落とし所だと思うが、積極的に採用しているチームをあまり見たことがない。
・TeX, LaTeX
数式を多用するドキュメントなら、まあ、妥当。
・HTML
現実的に、これが一番無難であり、多くの場合に最良の選択でしょうな。
オンライン公開するドキュメントならHTML一択。
ただし、オフラインでの配布、参照にはやや不向きか。
・ePub
そこでePubですよ。
オンラインで公開しないもので、かつ、iPhoneなどのスマートデバイスで参照する可能性があるならばePubが良いだろう。あるいは、しおりや蛍光ペンなどでマークしながら使う可能性を視野に入れる場合も、ePubが良い。
MicrosoftやAppleは、最近、技術書をePubで配布してくれており、これは大変ありがたいことだと思う。
未だに技術書をPDFで配布している企業や研究者は遅れている！
（と、個人的には思う）
それなのに、私の周りのプログラマは、ドキュメントをePub形式で書くことに対してあまり積極的ではなく、みんなしてPDFにしたがる。
原因としては、色々と思い当たるところはあるが、それは今回は置いておこう。
さて、本題。
技術系のドキュメントをePubで書く際に気になることといえば、プログラムコードの見栄え、即ち、シンタックスハイライトを手軽に使えるかどうかという点であろう。
ということで、用意するもの。
・Google Code Prettify
今回はprettifyを使うが、JavaScript形式のシンタックスハイライターならたぶんなんでも大丈夫。
https://code.google.com/p/google-code-prettify/
・Sigil
今回はSigilというePubエディタを使う。
バグが多く、不安定だが、シンプルで使いやすい。
というか、他にあまり良いePubエディタがない。
https://github.com/user-none/Sigil/releases
・ePubビューワー
作成したePubを閲覧するアプリ。
JavaScriptの埋め込みに対応しているePubビューワーならなんでも良いのだが、私はMurasakiを好んで使っている。
http://genjiapp.com/mac/murasaki/
【ドキュメント作成手順】
・prettifyをどこかに解凍して、.jsファイルと.cssファイルを用意しておく。
・Sigil.appを起動する。
・左側のブックブラウザー内のStylesを右クリックして、既存のファイルを追加を選ぶ。
・prettifyの全ての.jsファイルと.cssファイルを選択して追加する。
・すると、一瞬、
「Stylesの中にpretiffy.cssしか入っていない！.jsが入っていないじゃないか！」
と驚くかもしれないが、安心したまえ。
.jsはMiscの中に入っている。
・Sigilの真ん中のエリアにドキュメントをHTML形式で記述することができる。
<link href="../Styles/prettify.css" rel="stylesheet" type="text/css" /> <script src="../Misc/prettify.js" type="text/javascript"> </script> ...
・bodyタグにonload="prettyPrint()"を追加する。
<body onload="prettyPrint()"> ...
・ソースコードはpreタグで記述する。その際、class="prettyprint" を指定する。
<pre class="prettyprint">ここにソースコードを書く ... </pre>
ソースコードをコピペする場合は、もちろんHTMLコードのエスケープが必要である。
まあ、たいした問題ではない。
:%s /&/\&/g :%s /</\</g :%s />/\>/g :%s /\t/ /g
まあ、こんくらいで大丈夫だろう。
手順は以上である。
その他、ePubでドキュメントを作成するにあたって、多くのことについては、普通にHTMLを記述するのとなんら変わりない。たったこれだけで、美しいソースコードの見栄えを持つePubドキュメントを作成することができる。
素晴らしいネ。
