何とは言わない天然水飲みたさ

ロ技研の部誌を書いた記録


東工大 ロボット技術研究会の部誌を編集した。 つらぽよレベルが非常に高まった。 部誌編集のつらぽよ等について、ここに記録を残す。 愚痴っぽくなったけど誰かが悪いと文句を言ってるわけじゃないんです信じてください。

概要

(EPUB も考えなくもなかったが、 Linux でまともなビューアを知らないので却下した。)

簡単に説明しよう。

DocBook

DocBook は、技術文書のためのマークアップ言語である。 技術文書というか、特にソフトウェア方面に強い。 manページやリファレンス等、 DocBook 形式を用いて書かれた文書は多い。

この形式の良いところは、何といっても文書構造が明確、かつタグのそれぞれの意味や用途がはっきりしているところだ。 詳細はリファレンスを見ればわかるが、非常に多くの種類のタグがある。 これらそれぞれに、単語の意味や文書構造が割り当てられている。

XML 形式であるから、同じ XML である MathML も使うことができる。 数式の表現も安心だ。

HTML も文書構造用のタグはあるが(特に HTML5 からは)、そもそもが web ページ用なのでそこまで詳細ではない。 一方、 DocBook は書籍等も想定されており、 colophon 要素book 要素といったものまで用意されている。 なんでも天下の O'Reilly使っている(いた?)という話。

しかし、この形式の欠点は、やはりタグの種類が多いことである。 リファレンスを眺めてどのようなタグがあるか把握すれば、あとは HTML などと同じくタグを付けるだけだが、慣れないうちは似たようなタグのどれを使うかなど迷うことだろう。 また、スキーマも厳格に定められているため、窮屈に感じるかもしれない[0]

DocBook から他形式への変換に使う XSLT スタイルシートが大規模で複雑であり、自由度が高いとはいえカスタマイズに少々苦労するというのも欠点のひとつだ。 一応これは自分で書くこともできるのだが、さすがに私は FO や PDF の仕様までは知らないため、そこまでする気はなかなか起きない[1]

SVG

SVG はベクタ画像形式の一種で、 Scalable Vector Graphics の略である。 他にもベクタ画像形式は沢山あるのだろうが、 SVG は XML ベースであるため、アプリケーションから使いやすい(というより、正しくは扱うアプリケーションを書きやすい)。 また、 XML ベースであるがゆえ、テキストデータを扱ったり、他の形式中に埋め込んだりといった用途と相性が良い。

LaTeX

みんな[誰?]大好き[要出典] LaTeX である。

組版の美しさには定評があり、また PDF 出力にも実績がある。 数式を表現できるフォーマットとしても有名であり、理系(情報系?)の多数が使っていると思われる。 また、多数のパッケージによる機能拡張も魅力のひとつだ。

しかし TeX の歴史は長く、そのぶん派生した処理系も多いため、環境を揃えるのが面倒である。 TeX Live なる処理系セットも存在するが、誰もがそれを使っているとも限らない[2]。 最近でこそ Unicode 対応の処理系(uplatex 等)もあるが、それでもフォントの扱いなどに面倒があることも多く、また画像の扱いも大昔の慣習を引き摺っている場合があったりと、面倒なことがある。

HTML / CSS

HTML は、 Web ページとかを書くためのフォーマット。 いわゆるリッチテキストをテキスト形式で記述できる。 XML の親戚みたいなやつ。 超有名。

CSS は、 HTML のスタイルを記述するための言語。 HTML が主に文書構造とその内容を記述するのに対し、 CSS は見た目を記述することで、本質的に重要な情報と飾りの情報をできるだけ分離している。

HTML と CSS の自由度はそれなりに高いので、この技術で本を書こうというのは多くの人が考えるところで、現時点で幾つかの技術がある。

htmlbook (日本語訳)は、またもや天下の O'Reilly が策定しようとしている規格である。 HTML のサブセットで、 data-type 属性によるメタ情報を活用することで、文書構造を本の作成に使えるレベルで明確にしよう、というものだ。 CSS について規定はないので、印刷用やブラウザ用のスタイルは自分で書くことになる。 この規格は EPUB や DocBook を参考にしているところが大きく、それなら最初から DocBook 書けば良くね? と思ったのは私だけだろうか……。

もうひとつ、これとは別に CSS 組版というものもあり、こちらは文書構造というより見た目を本として印刷可能にする技術の総称である。 最近の CSS は高機能なので、文字やテキストの配置がかなり細かく制御できるようになっているのである。

しかしこの方式の問題は、しっかりした処理系がないことにある。 WebKit 系や Google Chrome や Firefox など、それぞれ微妙に表示が違ったり、そもそもブラウザを起動してPDF出力しなければならなかったり、或いは良い処理系があっても有料だったりする。

ちなみに電子書籍のフォーマットである EPUB も HTML (というか、 XHTML と呼ばれる XML 形式)や CSS ベースの形式である。

AsciiDoc

AsciiDoc は markdown と似た、文書を記述するための非マークアップ言語である。 markdown は多様な方言や表現力のなさ(そして「困ったことがあれば HTML 直書きしてね!」という仕様)のせいで、可搬性の欠片もない地獄フォーマットとなっているが、 AsciiDoc はある程度明確に仕様が定められており、不安が少ない。

また、 AsciiDoc は DocBook と同様の文書構造を簡潔に表現できることを目指したフォーマットのため、書籍を記述することもできる。 またまた天下の O'Reilly もこの形式の原稿を扱っているようだ。

AsciiDoc には数式を表現するための TeX 記法でもなく MathML でもない記法が用意されているため、意地でもマークアップしたくない人でも安心して数式を書ける。

さて上のような選択肢のいずれかを選ぶことになる。

DocBook は個人的には好きだが、 HTML 直書きすら人間のやることではないという意見の強いなか、原稿を XML で書けというのは流石に横暴である(というか原稿集まらなそうな気がする)ため却下した。 私は今時 LaTeX を書く方がよほど人間に向いていないと思うのだが……。

そして実質 XML のようなところのある HTML も却下となった。 数式も MathML で書けるし良いと思ったのだが残念だ。

SVG はテキストデータを持てるし画像も持てるし、それなら組版の出力として使えるのではないか、と思ったわけであるが、現実はそんなに甘くなかった。 あくまで SVG は画像形式だからか、文字の位置を決める作業(禁則処理とか)は自力でやらねばならない部分があるようだった。

いかんせんSVG 1.1SEではテキストの自動折り返しができない上、仮にtextPath要素で代用しても禁則処理も行われないなど、文字周りは依然として使いどころが難しいのが現状ですね。
2015年08月19日のSVG - 週刊SVG, 2016/12/22 閲覧

まあ画像形式であるからこれは当然といえば当然なのだが、結局 SVG は本を作るという用途では成果物寄りの形式であり、 SVG を生成するためにはテキストレイアウト等を行うエンジンが必要になる。 私はそのようなアプリケーションを知らなかったが、かといって作るのも面倒そう(TeX エンジンを再発明するようなものである)だったので、残念ながら SVG を経由する方式も却下だ。

残る AsciiDoc と LaTeX であるが、やはり部員に浸透しているのは LaTeX である。 AsciiDoc も推してはいるしユーザもちらほら見掛けるのだが、 vim のように部員皆が使っているというわけでもない。

また、 AsciiDoc は HTML か DocBook (FO) 経由でしか変換できないというのが痛い。 スタイルの細かな調整や自動化された PDF 生成が確実ではないのだ。 よって、部誌には LaTeX を使うことにした。 それしか選択肢が残らなかったのである。

TeX

latexmk が解決してくれる[3]から、 .latexmkrc ファイルをテンプレートとして提供することで執筆者間での環境の差異の吸収を試みた。

TeX の環境

日本人のための LaTeX タブー集 ~画像読込編~ - Qiita でも読んでほしいが、 bb というのは人間が原稿に直書きするようなパラメータではない。 しかも最近の TeX 処理系(TeX Live 2015 以降)はそもそも extractbb コマンドを自動で実行するため、 もはやユーザが bb を指定したり .xbb ファイルを作成する必要はない[4]。 そして、必要がないファイルを原稿リポジトリに含めるべきではない。 よって、私が回収した TeX ファイルからは、 bb オプションや .xbb ファイルは消去した。

したのだが、 TeX Live を使っていない環境ではそれだと駄目だったようで、 bb 関係のエラーでローカルでコンパイルできなかったという執筆者があった。 ひどい話だ。 (とはいえ、だからといって xbb ファイル等を git リポジトリに追加することはなかったが。)

空白文字の扱い

[5] KMC の kmcclasses.dtx がどう考えても保守できなくなるタイプのクソデカファイルだった[6]ので、素直に環境とプリアンブルを共通化することでどうにかしようということになった。

さて、記事毎の .tex ファイルにプリアンブルが(ほとんど)必要ない方法というと、 subfiles パッケージを使う方法と、 \input\include を使う方法があるが、今回は本の生成意外にも記事単独コンパイルをできるようにしたいと考えていたので、 subfiles パッケージを使うことにした。

記事

\ssrarticle コマンドである。 これを \ssrarticle{ぽよぽよを作ってみた}{ぽぽぽ学科 3年}{ぽよ太郎}{ニックネーム的なやつとかtwitter} のように使うだけで記事ヘッダになるため、執筆者が無駄にいろいろ書く必要がなくなった。

ここで「タイトルと著者情報は同じコマンドで指定する必要はなかったのでは?」と思った方もいるかもしれない。 本を書くだけであれば、その通りであるし、実際著者情報は \localauthor によって出力されているため、分離は可能である。

では何故一緒にしたかといえば、それは記事個別でのコンパイルを簡単にするためである。 このテンプレートにおいては、個別の記事をひとつの article としてコンパイルし PDF 出力することが可能であり、その場合タイトルは \title 、著者情報は \author で指定し、ついでに \maketitle してやる必要がある。 このような手順の違いがあるため、執筆者には、記事が article なのか chapter なのかを意識してもらっては困るのである。 これらの手順をひとまとめにして抽象化し、単に「記事のヘッダ」としてまとめる意図で、タイトル指定と著者指定が単一のコマンドで行うことになった。

プリアンブル

sty/ ディレクトリ以下にある sty ファイル群である。

10-setup.sty は、主に \usepackage{} を行うファイルである。 本当は \usepackage もその意味や用途毎に各ファイルへ分散させたかったが、パッケージ間で依存関係があったり、連携に余計なオプション指定が必要だったりと、パッケージの直交性[7]が低かったため、一箇所にまとめざるを得なかった。

他にもいろいろファイルはあるが、まあおおよそタイトルの通りだし、見ればわかる。 黒魔術っぽい奴らにはだいたい参考 URL を書いてあるので、よくわからない記述があっても、すぐに元情報を参照できる。 コメントは大事。

フォント

日本語の斜体

日本語だけ使っているとあまり意識しないが、斜体には2種類ある。 italicslant だ。 italic 筆記体のようなというか、最初から斜めでデザインされているもので、 slant は普通の文字を安直に斜めに倒したものである。 日本語は斜め文字専用書体のようなものがないから、普通 slant で対応することになる。

そこで何が起きるかというと、英字を斜めにしようとして italic 指定すると、同じ方法では日本語の文字が倒れない(そのようなフォントがない)のである。 よって、日本語の斜体のための slant を行うマクロを発見し、導入した。

日本語と英字の強調

英語における強調は斜体(italic)で行うことになっている(更に強い強調は太字(bold)で行う)が、日本語の斜体は見辛い。 正確には、 italic はフォントが変わるので普通の文字との違いを判別しやすいが、日本語は斜体にしても slant なので、文字そのものの特徴があまり変わらず、違いが判りづらいのである。 そこで、 \em\emph による強調で、 italic でなく bold を使うよう記述を追加した。

日本語と英字の等幅フォント

TeX では英字で等幅フォントを使おうとすると typewriter 体を使うことになる。 ソースコードの表示とかで使うアレだ。

しかし日本語のタイプライター体はないため、他の等幅フォントで代用する必要があるが、実のところゴシック体の日本語文字(というより全角文字)は等幅であるから、これをそのまま利用できる。 よって、等幅フォントを指定されたとき、英字ではそのまま typewriter 、日本語等であれば gothic を使わせるようにした。

serif と gothic

英字には serif と sans-serif という書体がある。 文字に「ひげ」のあるのが serif 、ないのが sans-serif だ。 日本語でいうと serif は明朝、 sans-serif はゴシックに相当する。

このような対応関係があるから、日本語と英数字交じりの文やブロックに \sf を使ったとき、英字は serif 、日本語は gothic になってほしいのだが、残念ながら LaTeX ではそうはならない。 \sf では英字だけが sans-serif となり、 \gt では日本語だけが gothic となる。 \textsf\textgt は両方同時に使うと日本語と英数字両方がゴシックになるが、 \sf\gt は同時に使っても最後の一方しか反映されないのである。

そこで、これらのマクロの根本にある \sffamily\gtfamily を再定義し、どちらのコマンドを使っても日本語と英数字両方がゴシックになるようにした。

個別の問題

\raggedright を使って、右側に余白が大き目に空いてしまうことを許すことでどうにかした。

listing の長い行のはみ出し

これはコンマやイコール等、演算子や記号の前後で空白を入れなかった場合に発生しやすい。 対処としては、ソースコード中に空白を入れてもらうことになる。 (とはいえ、普通のコードでは空白は沢山入れようという規約で書いている人が多いので、そうそう起きない問題だが。)

メソッドチェーンなど、普通に書いていれば空白が入らない行などもあるが、こういう場合は元のソースコードで明示的に改行と行継続を使ってもらうしかない。

数式のはみ出し

こいつが相当厄介で、単に項が多いだけならまだしも、∫やらΣやらの中の式が長かったりすると、迂闊に改行もできない。 いや、できないことはないのだろうが、本人以外が勝手に改行を入れるというのは難しい。 このケースの対応策はいくつかある。

  • 改行を入れる
  • \resizebox\scalebox で式を縮小する
  • 文字間隔を狭める

今回の部誌では文字を詰めた。 \!\mathalpha{+}{ を手作業で並べていったのである。 一律でやると文字が詰まりすぎて可読性を損ねることもあるので、 PDF を目視確認しつつ調整していく。 おかげで、手作業の温かみのある数式が出来上がった。

どうも TeX は、見た目をどうにか良くしようとする割には、守ってほしいはずのルールをカジュアルに破りにくるので油断ならない。 PDF を生成するごとにじっくり眺めてはみ出しを確認する必要があるだろう。 (実は私は慌てていて大きなはみ出しを一箇所見逃してしまったのだが、まあここだけの話だ。)

それから、はみ出しとは紙面の外へ突き抜けることだけでなく、本来文字のないべき余白部分へ飛び出すのも指すのだというのが、意外と知られていなかった。 (要するに本文が版面から出るべきでないというだけの話なのだが。)

日本語

翻訳コラム 34: こんな日本語原稿が困ります(段落とパラグラフについて))。 しかしこれがネットになると話は別で、たとえばメールや掲示板など様々な場面で、文章は改行で区切り、また文章の途中であっても適宜改行を入れるのが読み易い文章とされる[8]

この辺りの書き方は個性と見ることもできそうな気もするし、ネットぽさを出したければそういう書き方をすることになるので、あまり細かく指定しなければ執筆者が勝手にいい感じにするだろうからあまり縛りたくないと最初は思っていた。 しかし、どうもそういうお作法を単に知らないだけで書いていると思わしき文章などがあり、結局確認をとったうえで修正することになった。

まあ普通に生活していれば本を書くような機会なんてそうそうない[9]から、最初にこういったことはまとめて資料を作っておくべきだったと反省している。

約物

[10]でもない同人誌でそこまで拘る読者がいるものか、私にはわからない。

誤字脱字

ispell のようなツールが使えるが、日本語の校正ソフトは正直よく知らない。 一応 RedPen のようなものは存在は知っていたが、使ったことがないしどこまで柔軟なのか知らなかった [11] ので、導入に踏み切れなかったのだ。 締切の短さが悪い!

その他の問題

ちなみにロ技研は 1日目(木曜日) 西地区 ほ41b だそうだ。