検討!目論見委員会Z

サーバインフラ屋10年余りやってる人

Sphinxで薄い本を書いてみた

Sphinx Advent Calendar 2012 - connpass の23 日目です。 昨日は Harrison さんの Sphinx アドベントカレンダー22日目 でした。壁ドンって重ねるとたのしいですよね。壁壁ドンドン*1。関係が前に進みそうな感じですね*2。ということでAdvent Calender初参加でございます*3*4

はじめに

Sphinx界隈の皆様、はじめまして。柱脚の多さで定評のある @tboffice と申します。よろしくお願いします*5Sphinxで薄い本を作った話をします。薄い本については最後の方で触れます。

そもそも

実は、このエントリのタイトルにもなっている「薄い本」は、今年の夏頃にも作りました。そのときは複数人で素のtex原稿を書いて持ち寄って、dvipdfmxコマンドをたたいてビルドしていました。

そのとき一緒に執筆していたid:j5ik2o(@j5ik2o)さんからこんなのあるよ、という紹介でsphinxを知りました。rst形式で文章を書けばいろんなフォーマットで出力できるよ、という話をきいて調べてみるとepubも出せるぞ!これは電子書籍化が簡単にできるぜゲヘヘ*6ということで、使ってみることにしたのでした。

執筆の流れ

  1. 各自の記事のrstを書く
  2. $ make latexpdfjaしてpdfを生成
  3. pdfを印刷屋さんに入稿
  4. おしまい*7

この流れの間に、いろいろなことが含まれているので、ひとつひとつ解きほぐしていきます。

環境構築

TeX Live 2012 をインストールしている環境があったので、そこにsphinx 1.1.3 もインストールして利用しました*8。 その後、dvipdfmxを使うために下記のパッチを適用しました。

LaTeX経由でのPDF作成 :: ドキュメンテーションツール スフィンクス Sphinx-users.jp

いざrstを書く

githubに慣れてしまった若者のrst離れが叫ばれている中、我々はrstという茨の道(ry*9

複数人で原稿を書いていたので、各自rstを覚えるというところからスタートしました。自分の感覚だと、rstを覚えるのはMarkdownやはてな記法より障壁高めという印象でした。構造を理解するまで1-2日程度かかりました*10

自分が理解したところで、まだ覚えてない人には、基本的なのrst記法と、それに対応するpdfを出力して対比して見せました。

余談ですが、締め切りが近くなった頃、各自のセクションの記号は統一されていないことが発覚。あとで大変なことに…。

セオリーに倣って統一しましょう:reStructuredText入門 — Sphinx v1.0 (hg) documentation

みんなでrstを書く

1つのファイルをみんなでよってたかって編集すると衝突するので、include的な仕組みを使いました。 index.rstにこんな感じで記述しました。

.. toctree::
   :maxdepth: 4
   :numbered:

   first.rst
   hoge/fuga.rst
   second.rst
   foo/bar.rst

pdfのフォーマットを決めていく

入稿するpdfの仕様は、「モノクロ・B5サイズ・フォント埋め込み済み」です。

jsarticleを使いたい

デフォルトでpdfをビルドしようとすると、sphinx.styを使ったa4paper的なPDFが出来ます。これを入稿する仕様に合わせていきます。早速、conf.pyの編集です。デフォルトのpdfの見栄えがアレゲだったので、jsarticleを使いました。すると、\chapterが表示されないという問題が発生。それもそのはず、jsarticleはchapter表示できないのでした。jsbookにすれば\chapterを解釈できるのですが、ページ数をふんだんに使ってしまうのと、前回jsarticleで本を作ったのでjsarticleをどうしても使いたい!という状態になりました。結局 howto にして jsarticle を使う設定にもっていってそこから小手先の技術を使います。

\partが出力できなかったので、rstファイルに 「.. raw:: latex」を書いてそこに \part を書き込むというよろしくない感じになりました。仕方ないのです。偉い人にはそれがわからんのです*11

ページ数がローマ字に

なってしまったので、conf.pyのpreambleで「\pagenumbering{arabic}」を設定して解決。

コードブロックに枠線を付けたい

という要望が執筆者から挙がりました。調べてみたのですが、結局生成したtexファイルをsedして置換するということで対応*12

$ sed -i -e 's/commandchars/frame=single,commandchars/' $TEXFILE

このあたりの解決は、入稿まで時間のない中、 id:mtgto/@mtgto に何とか解決してもらいました。多謝。

コードブロックのカラーリングをオフにする

デフォルトでコードブロックにカラー設定がされています。入稿するPDFはモノクロで作ろうとしていたため、dvipdfmxでグレースケールにするオプション(-c)を使ったところ、コードブロックの部分がすべて四角い黒ベタになってしまいました*13

f:id:tboffice:20121219014538p:plain

コードブロックのカラー部分をすべてモノクロに出来ないかと、生成されたtexファイルを見てみたところ、カラー設定が書かれている部分がありました。しかし、定義行数が多すぎたためなんとかせず、印刷屋さんでグレースケール化してもらいました*14

blockdiag

試しに使ってみると、pngで画像が生成されて、platex が png を食えなくて止まるという現象に遭遇。 extractbb で xbb ファイルをどうにかこうにかするというところまで辿り着いたのですが、そこから先がなんとか出来ずにblockdiagを使うのを諦めました*15。結果的にはblockdiagを使わなくてもなんとかなりました...

印刷関連

sphinxから離れますが、ついでなので印刷関連のお約束に触れておきます。

PDFフォント埋め込み問題

フォントを埋め込むか、アウトライン化しないと、別の環境でpdfを開くとフォントが再現できず、化けることがあります*16。 今回は下記サイトの記述通りにやったらうまくいきました*17

日本語フォントのセットアップ

今回こんなコマンドを打ちました*18

# updmap-setup-kanji ipaex

ページ数

ページ数は「4ページ単位」を意識しないと面倒なことになるので、本文のページ数は注意しましょう*19

できなかったこと

字下げができない

できあがったPDFファイルで、文章の1行目の字下げができませんでした。そんな文句をかいたエントリにコメントを書いてくださった方がおりまして、preambleに「\setlength\parindent{1zw}」と書いたところ、意図したとおりになりました。この場をお借りしてありがとうございます。入稿には間に合いませんでしたが、次回への糧としていきます。

まとめ

  • sphinx.styを使わずに素のTeXファイルを出してくれないもんかなあ
  • rstで文章中に柱脚を書くとき、TeXでいうところの\footnote{}的な書き方できないっすかねー。はてな記法だと柱脚は二重括弧なのでそんな感じがあると嬉しい*20

え?薄い本はどうしたって?

そんなsphinxでビルドした「薄い本」のタイトルは、「ななかInside Press vol.2」です。冬コミ3日目の12/31(月)の大晦日に頒布しますのでみんな来てね*21!スペースナンバーは 東Y14b だよ*22

f:id:tboffice:20121222002601p:plain

特集はGitとなっております。私は特集記事の中で、「Git + Jenkins + Sphinxでドキュメント生成」の記事を書きました*23。なお、本の奥付にQRコードがありましてそれを読み取ると<censored>自分でビルドできます*24

詳細は http://nanaka-inside.net でチェックしてください。

おわりに

sphinxのことだったら何でも書いて良い気がするという雰囲気を感じ取ったので今回参加させていただきました。ひどいステマで申し訳ありませんでした。このエントリが何かのお役に立てれば幸いです。 バッドノウハウに対するナウでヤングなグッドノウハウを教えていただけるとありがたいです。

明日は、@tcshさんです。

追記(2013/01/05)

あけましておめでとうございます。当日お越しいただいた皆様、ありがとうございました。 まだ手元に若干の在庫がございますので、「とらのあな」に委託します。新刊・既刊とも委託します。もしよろしければどうぞ。

*1:何いってんだこいつ

*2:進まねーよ、壁あるし

*3:関係ないですけど、壁丼って美味しそうですね

*4:B級グルメか!

*5:ついでに、はてなblogデビューだぜヒャッハー!

*6:まだ手が付けられていない

*7:おいっ!

*8:さくらのVPS@CentOSを利用

*9:おいやめろ

*10:インデントとかどこまで掛かっているか難しいし...おすし...

*11:あ、すいません、jsbookを使うのが自然ですよねーごめんなさい~石投げないでー

*12:こうしてバッドノウハウがまたひとつ

*13:ご唱和ください「これはひどい」

*14:あとで考えるとadobe社製のなんかのソフトでなんとかできたかもね…

*15:生成されたpngをconvertコマンドでepsに変換しても良いかも

*16:当然ながらフォントのライセンスにも注意を払う必要があります

*17:フォントが埋め込まれているかどうか確認するには、PDFをAdobe Readerで開いて、ファイル->プロパティーのフォントタブの中にフォントの一覧が表示されているので、すべて「埋め込みサブセット」となっていること

*18:設定していないと$PATHに通っていないので注意ネ

*19:一行だけはみ出して予定ページオーバーになったので、文章を一行削ってもらったり...

*20:ここにきてrstに文句言ってどうする

*21:えっ

*22:えっえっ

*23:ほか1本

*24:censored入れた意味があったかどうか<censored>