2018/03/05

技術書のレビューの経験則

出版される前の本の内容は、通常は著者や編集者に代表される「制作サイド」の人間にしか読まれない。 専門性の高い本であれば査読とか監修といったプロセスを有識者にお願いすることはあるけど、そうしたお願いをするときには有償だったりカバーや袖に名前を出したりすることが多いので、これも「制作サイド」の一部とみなしていいだろう。

一方、基本的に無償で、完成した書籍の献本と謝辞への掲載くらいを前提に、あくまでもベストエフォートで発行前の本の内容を見てくださいというお願いを第三者にすることもある。 この場合の第三者というのは、制作中の書籍の想定読者だったり、出版後の書籍を対象読者へ紹介してくれそうな立場の人だったりする。 このようなプロセスを制作に取り入れる習慣は、とくにここ数年のIT系の出版社ではめずらしくなくて、界隈では「レビュー」などと呼ばれている。

というわけで、技術書の制作における「レビュー」について、自分の経験をもとに知見を整理しておきたい。 自分の経験をもとにはしているけど、たぶん日本で技術書のレビューをまわしてきた経験数では上位にいるはずなので、独りよがりではあるかもだけど意味がなくはないはず。

余談だけど、たぶんこういう出版前の状態を有志にボランティアでレビューしてもらうという文化を技術書界隈で積極的に始めたのはアスキーなんじゃないかなと思う。 少なくともぼくが最初にこういうプロセスの存在を知ったのは、アスキーの256本とかで執筆兼レビューのためにメーリングリストを使っているのを見たときだった。 彼らがどこまで意識的にこれをプロセス化していたのかは知らないけれど、この記事は、彼らがやっていたプロセスをぼくの前職のチームの先輩だった森田さんが取り込み、いろいろな著者、訳者に協力してもらいながら発達させてきた手法がベースになっている。

技術書のレビューのパターン

まず、レビューと一口にいっても王道のプロセスがあるわけではなくて、依頼方法およびレビュアーどうしのインタラクションの有無によっていくつかの形に分類できる。

レビュー内容は制作サイドだけが見たいレビュー内容が他のレビュアーにも見えてよい
制作サイドで知己がある人に依頼
制作サイドで知己がない人に依頼
不特定多数

上記の表のいずれのパターンに該当するかによって、レビューの具体的な手法やツールがだいたい決まる。

技術書のレビューの手法

とはいえ、実際にはレビューの具体的な手法やツールがまずあり、その結果として上記の表のいずれかに当てはまるという状況が多いだろう。 いずれにしても、誰にどういう方法でレビューをしてもらうかは、レビューに使うツールやプロセスに依存する。 そこで、次はツールという観点から上記の表の各セルとの適正について整理してみよう。

バグトラッキングシステムを利用する方法

②と④の場合は、プライベートなバグトラッキングシステムを使うことが多い。自分がかかわるプロジェクトだと、一昔前はTracのチケット、いまではGitHubのissueとしてフィードバックをもらっている。 もちろん、TracやGitHubなどのシステム側で不特定多数の参加を許可するようにすれば、⑥の場合にも使える。

バグトラッキングシステムを使うメリットとしては、あるレビュアーが見つけた問題を制作サイドやレビュー陣営全体で共有しやすいことが挙げられる。原稿のバージョン管理をしている場合にはリポジトリに関連付けられたバグトラッキングシステムを使えるので、フィードバックへの対応履歴を管理しやすいというのも魅力。ひとことでいえば、レビュアーとレビューを受ける側のトータルでの負担が最小化される方法だといえる。

レビュアーどうしでチケットやissueで議論ができるので、著者や編集者だけ、つまり制作サイドだけでは思いつかないような解決策が出たり、特定のレビュアーの偏った意見なのかそうでないのかを客観的に判断する材料ができたりするというメリットもある。

デメリットは、レビュアーが見つけた問題をチケットやissueにするときに、指摘したい場所を一意に伝えにくいこと。ほとんどの場合、レビュアーが見る対象というのは、原稿ソースに技術的にアクセスができる場合でも、組版されたPDFである。そのため、一般には「mページのk行め」のような指示方法になるしかないのだけれど、これには次の難点がある。

  • レビューを受け取る側ではPDFでなく原稿ソースのほうを見ているので、「mページのk行め」という情報は使わず、指摘内容からキーワードをgrepして該当箇所を探している。つまり、「mページのk行め」まで粒度が細かい情報は無駄になってしまうことが多い。原稿ソースが頻繁に更新される環境だと、レビュー対象のPDFと制作進行中のPDFとで場所の乖離がさらに激しくなる
  • 「mページのk行め」のような指摘は、他のレビュアーにとっても優しくないので、指摘のダブりが意外と発生しやすい。ダブりを防ぐために修正ずみの問題をすぐにクローズしないといった運用をしても、なおダブる。そもそも修正ずみの問題をクローズできないのでは、バグトラッキングシステムを使う利点が半減してしまう

場所の指示がめんどうであることに加えて、バグトラッキングシステムを利用することには、レビュアーが他のレビュアーの意見を読めてしまうことによるデメリットもある。

  • うまく回ればレビュアーどうしの議論によって問題の文脈がはっきりするのだが、ときには議論の発散という形でデメリットになる場合もある
  • 声が大きい有名人がレビュアーにいることで他のレビュアーが委縮してしまい指摘しづらい雰囲気ができたり、そのようなレビュアーの意見に流される可能性がある

まとめると、バグトラッキングシステムを使った技術書のレビューには、手軽に問題を管理できる一方で、指摘箇所を一意に特定するのが困難であり、他のレビュアーとのインタラクションが不可避であるというデメリットがある。 そのため、冒頭の表における②のような著者や編集者が議論をコントロールしやすいレビュアーの集合である場合に向いた手法だといえる。 ④の場合には、レビューの要件を具体的に明文化しておく必要があるだろう(もちろん②のケースでも明文化したほうがいいんだろうけど)。 一方、レビュアーが他のレビュアーの意見によってバイアスを受けるのを避けたい場合(①、③、⑤)、自転車小屋の屋根の色をめぐる議論に巻き込まれたくないという場合(⑥)には、使えない。

問題点を個別に直接送ってもらう方法

複数のレビュアーがバグトラッキングシステムで相互に意見を交わしながら技術書のクオリティを上げていく作業は、うまく回ると本当に楽しい。それ自体がエンターテインメントだったと感じることも少なくない。 しかし、そういう場が醸成されるまでには時間がかかるし、そもそも成功するとは限らない。オープンソースプロジェクトに慣れている著者かどうかという文化的な違いによる困難もある。 前述したように、レビュアーが他のレビュアーの意見によってバイアスを受けることを避けたい場合もある。

そこで、著者 and/or 編集者が個別にレビューを依頼し、一対一でフィードバックを返してもらうというケースもかなり多い。 その場合には、メールで指摘をもらったり、PDFのコメント機能を使ってもらったり、最近だとDropboxのコメント機能を使うこともある(Google Driveにも同様の機能はあるので使えるかもしれない)。

この方法は、フィードバックをもらうという一点に特化すればもっとも優れている。 Acrobatのレビュー機能やDropboxのコメント機能を使えば、バグトラッキングシステムでは不可避だった指摘箇所を一意に特定する難しさがある程度は解消できるという利点もある。

難しいのは、なんといっても人選。 バグトラッキングシステムを利用すれば十数人規模になってもハンドリング可能だけど、個別にやり取りをする負荷を考えると、数人に抑えたいところ。となると、ピンポイントで適切な人に依頼するのが現実的だといえるだろう。 そういうわけで、冒頭の表における①や③に向いた方法だといえる。 ⑤でも使えなくはないけれど、というか⑤をやりたいときはこの方法しかないんだけど、制作サイドが個別のやり取りの負荷を覚悟する必要がある。

クラウド上で共有したPDFにコメントを付けてもらう方法

DropboxにPDFを置くと、閲覧できる人が誰でも文字列をハイライトしてコメントをつけられるようになる。 この機能は、個別に指摘をもらう場合だけでなく、複数のレビュアーから同時に指摘を受ける場合にも使える。 Dropboxによる方法のメリットは、実施前の手間が最小であること。なにしろ、Dropboxに置いてリンクを伝えるだけでいい。 モダンブラウザがあれば説明不要で直観的に指摘箇所を一意に特定できるのもお手軽さにつながる。

デメリットは、DropboxのPDFビューアーはPDFの仕様に準拠していない独自の拡張で、次のような不自由があること。

  • 書籍全体の検索ができない場合がある。検索対象になるのはブラウザが描画ツリーを構築した部分だけ
  • コメントのステータスが未解決と解決済みの2つしかないので、複数のレビュアーからの指摘がダブらないようにするにはすべて未解決にしておくしかない。そのため、レビューを締め切るまで取り込み作業がしにくい
  • 個々のコメントにURLが付かないので、議論が始まったコメントや見逃したコメントを通知をたどって追いかけるしかない
  • PDFデータにはコメントが埋め込まれないので、ダウンロードしてPDFリーダーでコメントを管理することも、PDFデータからコメントを抜き出すこともできない

このような制約があるので、DropboxでPDFにコメントをもらう方法をうまくまわすには、PDFのページ範囲を小さく章単位などに絞ったり、レビューの締め切りまではコメントを解決済みステータスにしないようにしたり、少し工夫がいる。 それでも、指摘箇所を一意に特定しやすいというメリットは大きいので、Slackなどの他メディアでレビュアーと制作サイドが気軽に議論ができる②のような状況であれば、かなり魅力的だと思う。

もうひとつ、Dropboxに代表される共有PDFへのコメント書き込みには、指摘がミクロに偏りがちになってしまうという見過ごせない欠点がある。 この欠点を補うにも、レビュアーと制作サイドとが雑談できる場の用意が重要な気がしている。

なお、この方法で技術書のレビューが可能なのはDropboxだけではない。 Google Docsにも指摘が行単位になるけど同様の機能はあるし、Adobe Readerにも共有レビューという機能がある。 PDFの仕様にそったアノテーション機能であるAdobe Readerの共有レビューが使えるのがベストなんだけど、Adobe ReaderがLinuxベースの環境で事実上使えなかったり、macOSでもインストールしてない人がいたりするから、つらい。

技術書のレビューをする側の心得

ここまでは、技術書のレビューを受ける側に向けた話だった。 ここでは、レビューをするときにどんなことを意識したらいいかについてざっくり書いてみる。 ただし、ぼく自身はレビューを受ける側の立場に立つことが多いので、主にレビューを受ける側の視点が多分に混ざります。

レビューでがんばって探しちゃだめな問題

レビューで何を見るべきかを要約するのは難しいけど、がんばって見てはいけない問題というのはある。 建前としては「気づいたことを何でも指摘してほしい」なんだけど、何に気付くかは「何に気付こうと思って読んでいるか」に多分に影響されるので、「この点については意識的に探す必要がない」を意識するのはけっこう重要。

  • 誤字脱字など、日本語上のミス
  • 漢字や送り仮名などの表記ゆれ
  • レイアウトの不備

これらは、「気づいたなら指摘しておく」という態度で読めば十分で、レビューというプロセスでがんばって探すべき問題ではない。 逆に言うと、制作サイドの心得として、これらの問題をなるべくつぶした状態でレビューを開始すべきともいえる。

なんだけど、時間的な制約もあるので、現実にはそうでない原稿をレビューすることになる機会もある。 そういう問題が多く残っている状態でレビューをすることになった場合には、上記のような問題を一生懸命に探してあげるのではなく、「この章は誤字脱字が目立つけどあとで修正されるのですよね?」といった大局的なコメントを残すのがよい。 技術書のレビューの主眼は、あくまでも第三者の目を取り入れることであり、校正作業のボランティアではないのだから。

レイアウトについても同様で、完成途中のPDFを見るとどうしてもアラが目立つけど、それはやはりレビュアーが気を配る部分ではない。 「レイアウトの不備で有意義なレビューが困難である」といった指摘に留めよう。

ミクロな指摘より、マクロな指摘を

誤字やレイアウトの不備にも関係するけれど、第三者であるレビュアーがミクロに指摘したくなるような原稿の問題は、もっと広いスコープでの問題という場合が少なくない。 なんか日本語がわかりにくいなあと思って、語の位置を変えたり読点を追加したりしたミクロな修正案を出すのは、実は解決になっていないことが多い。 レビュアーがミクロな指摘で解消を試みた問題の根本的な原因は、より広いスコープで原稿の問題を解消できる人、つまり制作サイドでないと対処できないことが多い。

レビュアーとしては、なんか日本語がわかりにくいなあと感じる箇所があったら、「〇〇ということが言いたいんだと思うんだけど、なんか日本語がわかりにくいなあ」と指摘するのがベター。 〇〇すらわからないなら、「文意が不明」といったコメントでも十分。

自分にとって理想的な本にする機会ではない

技術書のレビューは、校正作業のボランティア募集にならないためにも、制作プロセスではかなり後の工程になる。 つまり、レビュアーとしては、本のコンセプトや表現方法、近日中の出版については了解しているということが前提になる。 したがって、内容に間違いがあると考えられるなら指摘すべきだけど、本の表現に対して調整を要求する場ではないという自覚は必要である。

文章に対するレビューというのは、センシティブなプロセスだ。指摘者以外にとってどちらでもいい話であることも少なくない。 どちらでもいい話に「どちらでもいい」というのは精神力がいるものなので、はじめから不採用前提くらいの気持ちだとみんなが楽になる。 たとえば、同じ内容ならこっちを説明すべきとか、説明の日本語表現はこっちのほうがいいとか、そういう指摘についての最終的な決定権は制作サイドにゆだねる。 制作サイドもまじえて議論になり、最終的な文章表現をなにか決定しないといけなくなったところで、代替案の作文をするくらいが双方の負担にならず、ちょうどいい。

逆に、著者や編集者には、無慈悲な独裁者となる覚悟が必要だといえる。 そういう意味ではオープンソースのコミッターと同じなのかも。 報われないかもしれない指摘であるという点について双方が納得していないと、レビューは回らない。

実践例

いままさに進行中の本の大規模レビューは、冒頭の表だと④、もしくは⑥に近いプロジェクトである。 そこで、指摘箇所を一意に特定する部分の困難さを回避しつつ、指摘の重複回避や原稿(他のプライベートリポジトリ)への取り込み状況の管理を可能するために、次のようなレビュー方法を採用した。

  • フィードバックはPDFのページ単位で受ける。そのために、各ページ用のGitHub issueをあらかじめ全ページぶん用意しておく
  • 指摘をするときの負荷を下げるために、PDFの各ページに、各ページ用GitHub issueへのリンクを埋め込んでおく。そこをクリックすれば、そのページに対するコメントを書き込めるページがブラウザで開くしくみ
さらに、上で紹介した経験則を踏まえて、レビュアーには下記のようなお願いをしている。

PDFを読んでページごとのissueに指摘を追記していってください。代案は不要です。なお、マンパワーの都合でissue上では無反応の可能性が高いです。ごめんなさい。

  • 具体的に指摘をいただきたいポイント
    • 内容の間違い
    • 解説がほしいトピック
    • 意味が取れない段落
  • 下記の指摘も歓迎です(grepをかけるので存在の指摘だけで十分です)
    • 技術用語の不統一
    • スペルミス、誤字、脱字
  • 下記については、指摘は不要です(最終までには自然に直ります)
    • 日本語表記(漢字や送り仮名)の不統一
    • レイアウトの不備
    • その他、局所的な日本語の問題

前半で述べたように、そもそも適切なレビューの手法は要求事項によって変わってくるので、これがベストな技術書のレビュー手法というわけではない。 最大で十数人くらい、著者が中心になってSNSなどで直接連絡がつく範囲に依頼するなら、いまのところDropboxへのコメントはかなり手軽に思える。 ピンポイントでお願いする人がいる場合も、DropboxへのコメントやPDFへのアノテーションがベストだろう。 一方、ある程度の議論が予測されたり、原稿のバージョン管理との親和性が優先されるなら、これからもGitHubのissueを使うと思う。

そしていずれにせよ、レビュアーに何を見てもらいたいか(見る必要がないのか)、レビューにあたって最終決定権は制作サイドの独断的な判断になることについては、何らかの形でレビュアーと制作サイドとで意識共有ができているべき。

2018/01/12

RubyでつくるRuby発売中

カート埋め込みのテスト。デフォルトだと書籍ページへのリンクにはならないのかな。カートに入れてしまったときに画面に常駐するカートボタンは、数をゼロにすると消えるようです。

2017/12/31

2018年賀状

年賀状書いた。

%!
<< /PageSize [285 420] >> setpagedevice

% excerpt from Bill Casselman's 
% "Mathematical Illustrations - a manual of geometry and PostScript"
/ctransform { load
    1 dict begin
    /f exch def
    [{[3 1 roll f {moveto}]}
     {[3 1 roll f {lineto}]}
     {[7 1 roll
       f 6 2 roll
       f 6 2 roll
       f 6 2 roll
       {curveto}]}
     {[{closepath}]}
     pathforall]
    newpath
    {aload pop exec} forall
    end
} def

/f {/y exch def
    /x exch def
    x y fsub 5 y mul cos mul
    y x fsub 3 y mul cos mul
} def

/fsub { % u = sin (a √(30 - (b^2 / 10))) * 460 
    /b exch def
    /a exch def
    a 30 b dup mul 10 div sub sqrt mul sin 460 mul
} def

/setrandcolor { % def
    /r1 {rand 5 mod 3 div} def
    /r2 {rand 7 mod 6 div} def
    /r3 {rand 5 mod 6 div} def
    r1 r2 r3 setrgbcolor
} def

1 1 20 { % for

    /n exch def

    newpath
    /ShowcardGothic-Reg findfont 4 scalefont setfont
    -0.4 9 moveto (2018) true charpath
    -0.1 6 moveto (1820) true charpath
     0   3 moveto (2018) true charpath
    -0.1 0 moveto (1820) true charpath
    /f ctransform
    gsave

    clip
    newpath
    /j {
        /x exch def
        rand x mod x div 30 mul
    } def

    0 5 400 {
        /i exch def
        10 j setlinewidth
         setrandcolor
         0 i moveto
         300 i lineto
         stroke
     } for
 
     grestore
     currentlinewidth 2 mul setlinewidth
     0.1 0 0 setrgbcolor 
     stroke
 
     3 410 moveto
     /Georgia-Bold findfont 5 scalefont setfont
     0.3 0.2 0.2 setrgbcolor
     n =string cvs show
     (/20) show
 
     showpage
 } for
 

2018 by Keiichiro Shikano on Scribd

今年は球体を作ってみたいなと思って、はじめはエッシャーふうの非ユークリッド空間の円盤への写像を「2018」のパターンで埋めようと思ったのだけど、ちょっと調べたら、それをやるには3つか5つの頂点を持つような「2018」をデザインしてそれを中心から外周へと再帰的に貼り付けていくことになりそうで、デザイン力が要求されるし、コードを書く時間もないから、やめ。 正方形を円へと等角写像で膨らませて輪郭を作りつつ、sinをとって膨らみ感を強調し、x軸で多少オフセットして、全体にそれっぽく見せることでごまかしています。

フォントはShowCard Gothicというボリューム感のあるフォントを選びました。

にしても、はじめてPostScript手書きで年賀状を作ってからもう10年になるのかあ。 ということで、これを機に過去のぶんもすべてGitHubにまとめておきました。

もともとPostScriptしばりというわけでもなく、なんとなく西暦の文字列を使って世界で1枚だけの年賀状をアルゴリズミックに生成するつもりしかなくて、2009年はPostScriptじゃないしコードも残っていなかった(Gaucheで書き捨てた)。 まあでも、よく10年続いたなと思う。

10年続きはしたけれど、年に一回しか書かないこともあり、PostScript力にはたいした進歩が感じられませんね。

2017/12/24

TeXでつくるMarkdownパーサ

この記事はTeX & LaTeX Advent Calendar 2017の24日めのために書きました。

TeXの中でMarkdownを書ける

先月のことなんですが、TeXの、TeXによる、TeXのためのMarkdownパーサをつくました。

TeXで実装されてるので、当然、TeXで書く文書のなかで、シームレスにMarkdownを使えます。 具体的には、こんな感じに、\begin{markdown}から\end{markdown}のなかにMarkdown記法が書けます。

\documentclass{article}
\usepackage{md}

\begin{document}
\begin{markdown}

# markdown-tex

markdown processor in TeX. 
As inline styles, `tt`, *italic*, and **bold** are available. 

## subsection

Here is a enumerate list.

1. enumerate
1. in 
1. the markdown way

This is an itemize list. 

* this block
* will be
* itemized

And a quotation. 

> Quote Somethin
> Really **Awesome**!

\end{markdown}
\end{document}

これをふつうにTeXで処理すると、記法から期待されるようなPDFができるわけです。

とはいっても、先月の時点でサポートしていた記法はそんなに多くなくて、これくらい。

  • 行頭の「#」の個数に応じた見出し化
  • 行頭の「*」で箇条書き
  • 行頭の「<」でインデント
  • 行頭の数字で連番箇条書き
  • 行頭スペース4個でインデントするとコードブロック化
  • `..`で囲むとインライン等幅
  • *..*で囲むとインラインイタリック
  • **..**で囲むとインライン強調

これ以外の要素を書きたかったら、いったん\end{markdown}して、生のTeXを書いてください。TeXなので、組版に関することなら、なんでもできます。

Markdownの中でTeXを書ける

この記事を読んでいる人はみんなTeX Conf 2017に参加しているので既知だと思いますが、念のため補足すると、このMarkdownパーサはTeX Conf 2017で発表した「TeXは軽量マークアップ言語の夢を見るか」のために作ったものです。 この発表では、Markdownをはじめとするマークアップ記法と、TeX(LaTeX)によって得られる表現力との関係について考察しました。 「Markdownについて話すのにMarkdownパーサの実装経験がなければ刺されるかも」という強迫観念から取り組んだ、概念実証のための実装です。

で、TeXのなかでMarkdownを使えるからといってうれしいことはあまりないし、それで済ませるつもりだったですが、せっかくTeXなので、先日ちょっと手を入れて\TeXくらいは生で書けるようにしました。 その副作用で、コントロールシーケンスや数式も入れられるようになりました!

# markdown-tex

markdown processor in TeX. 
As inline styles, `tt`, *italic*, and **bold** are available. 
Inline equation in \TeX notation $\int_0^1\frac{1}{x}dx = \infty$.

\hfill December 24 2017

## subsection

Here is a enumerate list.

1. enumerate
1. in 
…

しかし、実はこれは誇大広告で、厳密にいうと2つの条件を満たすマクロやコマンドだけがMarkdown記法の中で使えます。

1つめの制約は、完全展開できる必要があるという点です。 たとえば、\sqrtは使えません。 これは、latex.ltxにおける\sqrtの定義では\@ifnextcharが利用されていて、そのなかでは展開されない\futureletが使われているからです。

なんで完全展開可能性が必要かというと、Markdown記法の構文解析を簡単にするために、対象となるトークンリストをいったん「完全展開された文字列」へと変換しているからです。 これにはexpl3の\tl_set_rescan:Nnxを使っています。 その際、TeXの入力を完全展開すると空白文字が集約されてしまってMarkdown記法として構文解析できなくなるので、これらは文字列とみなして完全展開しています。

\tl_set_rescan:Nnx \md_tokens
  {
    \char_set_catcode_letter:n {  32 }% SPACE
  } { \BODY }

これで\md_tokens変数に「完全展開された文字列」が入るので、それを構文解析し、それをTeXの胃袋に送ってPDFを作らせる、というのが先月までの実装でした。 そんなわけで、この状態でMarkdown記法の中に\TeXと書くと、このマクロが完全展開されたT\kern -..5ex\hbox E\kern -.\@mがそのままPDFに出てきてしまう状態でした。

では、Markdown記法の中に\TeXと書いて期待する出力結果を得るにはどうすればいいでしょうか? 完全展開をやめればよさそうですが、前述したようにスペースの扱いの都合があるので、文字列にしてからパースするという方針は変えがたい。 となると、完全展開された文字列をパースするときにTeXのプリミティブをパースしてコントロールシーケンスに変換し直し、それをTeXの胃袋に送ればいいのではないか?

というわけで、そんなようなコードを追加して、無事に\TeXのようなマクロがMarkdown記法のなかに埋め込めるようになりました。

\cs_new:Npn \inside_cs:Nnnn #1#2#3#4 {
  \tl_set:Nn \car_line { \tl_head:n { #4 } }
  \tl_set:Nn \cdr_line { \tl_tail:n { #4 } }
  
  \tl_if_head_eq_charcode:nNTF { #4 } { \sp_letter }
     {
       \tl_put_right:Nn #2 { 
         \cs:w #3 \cs_end:
       }
       \exp_args:NNnff \parse_to_end_line_with:Nnnn { #1 } { #2 } { } { \cdr_line }
     }
     {
       \tl_set:Nx \so_far { #3\car_line }
       \exp_args:NNnff \inside_cs:Nnnn { #1 } { #2 } { \so_far } { \cdr_line }
     }
}

ただし、実装をサボっているので、非標準的(?)な利用方法のコントロールシーケンスはパースできません。 たとえば、\hbot{foo}はいいけど、\hbox to 10pt{foo}とかはだめ。 これがもう1つの制約です。

今回のオチ

にしても、ここまでにやったことを振り返ると、事実上TeXでTeXをパースしているわけで、むだなことをした感が半端ない……。

  1. TeX記法の入力をTeXでパースし、トークンリストが作られた(TeXの仕事)
  2. トークンリストをMarkdown記法としてパースするために、完全展開して文字列化した(\tl_set_rescan:Nnx
  3. その文字列からコントロールシーケンスを取り出すのに、あらためてTeX記法のパーサを実装に追加した(\cs_new:Npn \inside_cs:Nnnn

2017/12/23

なぜ原稿をテキストで書かなければいけないのか

これは編集とライティングにまつわるアレコレ Advent Calendar 2017の23日めの記事です。

原稿をどういう形式・記法で書くべきなのか、という質問をときどき受けます。 一瞬だけ悩むけど、だいたい答えはこうなります。

「記法はなんでもいいけど、できればテキスト形式で」

今日は、この答えの背景を話します。

まずは「なんでもいい」の部分から。

記法はなんでもいい

出版社や編集者によっては細かく原稿の記法を指定しているようですが、ぼくは特に原稿の記法を決めていません。 これは、そういう記法を決めることができずにここまできた、というのが正直な理由です。 つまり、ぼくの怠慢なんですが、なにも考えずに怠慢であったというよりは、積極的に怠慢になろうと考えた結果なので、そのへんを少し吐露してみます。

原稿の記法を決めるということは、執筆者の脳内にあるものを吐き出してもらうための形を決めるということです。 脳内にあるものを他者に見せるための形を決めるわけではありません。

しかし、書き手が脳内を吐き出すという行為には、「どう見せたいか」という書き手自身の気持ちがどうしても混ざります。 この、「どう見せたいか」っていうのは、書く内容に合わせて思いつくものだったり、文章化が難しいから逃げるという側面もあったりするので、書く前から全パターンを網羅しきれるものでもありません。

で、脳内にあるものを吐き出した原稿と呼ばれる何かを、読者向けの見せ方を意識しながら整理する、そんな専門職があります。 編集者っていうんですけど、編集者によっては「あるドメインの読者にとってうれしい見せ方」から「適切な吐き出し記法」を逆算し、それを自分のキャリアのどこかの時点できちんと整備して、知見として執筆者と共有できている人がいます。 ぼくはそれをサボってきたので、そういう知見をとくに提供できず、「なんでもいいです」という頼りない返事になってしまうというわけでした。

ただし、ここからが重要なんですが、考えなしに「なんでもいいです」といっているわけでもありません。 言い訳っぽいですが、吐き出し記法に付随する見え方のほうを意識して見え方に頼った書き方をしてしまったり、汎用のブロック要素を利用した見せ方に依存する書き方が生み出されたり、そういうのを繰り返した結果として、「原稿の記法はあらかじめ決定しないほうがうまくいく」となって現在に至っています。 適切な吐き出し記法をいろいろ考えた結果、適切な吐き出し記法を汎用化すると(少なくともぼくには)うまくいかない、というジレンマに陥ったわけです。 ポジティブにいうと、好きな記法で吐き出してもらうのが執筆者とぼくにとって楽なケースが多いと判断したということです。

できればテキスト形式で

すでに結論めいたものを書いてしまってますが、どう見せるかの検討に移ってよいのは、脳内にある概念をとりあえず文字列として吐き出し、それを文章にして、さらに段落としてしっかり構成したあとです。 もうちょっと正確にいうと、段落の構成を試行錯誤するのと並行して、ようやく見せ方を考えられるようになります。

こんなふうに言うと、「はじめに構成をかっちり固めてから書くんじゃ」という声が聞こえてきそうですが、怒られを恐れずにいえば、それは幻想です。 文章を書く前から段落の構成をかっちり固めるには、相当の訓練とあきらめが必要です。 むしろ、文字列をダンプしたものから段落を試行錯誤して練り上げることこそが、文章作成の王道だといえるでしょう。

原稿がテキストであることが重要なのは、これが主な理由です。 文字列、文章、段落を行ったり来たりするイテレーションを、コンピュータを使って回しまくるには、テキストデータがいちばん好都合なのです。 だから、テキストで書いてください。

さらに、テキストとして吐き出されていれば、編集者が文章や段落をつくる手伝いができます。 テキストであればどの環境でもエディタで編集できるから、という面もありますが、もっと大きいのは、テキストであれば差分をとったりバージョン管理システムを利用したりすることで、編集者の作業を執筆者から見て透明にできるからです。

脳内にある情報を原稿として吐き出すのは、たいへんです。それをさらに文章や段落にするのも、けっこうたいへんです。 だから、後者のほうを手伝う職業として、編集がいるわけです。 しかし、原稿から文章や段落にする過程で、原稿のポイントが失われたり、もともとの執筆者が意図していない情報が紛れ込んだりするのは問題です。 この過程では、「編集者がやったこと」がつまびらかになっている必要があります。 つまり、編集者の作業が執筆者にとって透明である必要があります。 それがコンピュータで不自由なくできるのも、いまのところテキスト形式だけなので、その点でも原稿はテキストにしたいという結論になります。

原稿はソースコード、組版結果はバイナリコード

前述したように、原稿をテキスト形式で書き出し、テキスト形式のまま編集することは、編集者の作業の透明性を高めます。 編集者の作業が透明であるということは、作業結果がすべて執筆者の手元で再現できるということでもあります。 しかも、バージョン管理システムを使えば、元の原稿に対する差分(の積み重ね)という形で再現できます。

これは、執筆者が自身の吐き出した原稿をソースコードとして保持し、そのゆくすえを終始自分の管理下におけるという意味でもあります。 わりと見逃されてる点だと感じてるんですが、「原稿を人に見せる形にまで加工するプロセスが、原稿に責任がある本人にとってアンタッチャブルな状態」って、書き手にとっても編集する側にとっても、けっこう怖くないですか? データとしてアクセスできなければ、どこがどう変わったかをgrepしたり、あとで気づいた用語の間違いを全体にわたって機械的に変換したり、そういう作業が死ぬほどめんどくさくなります。 気に喰わない文章や段落を試行錯誤して手直しすることも、気軽にできなくなってしまいます。 少なくとも、あとは版面に情報を適切に固定するだけという状態になるまでは、編集者はいうまでもなく執筆者自身も原稿にアクセスできるほうがいいはずです。

原稿に責任がある人が、原稿への計算機によるアクセスを奪われないためには、そもそも原稿がそれにかなった形式である必要があります。 その形式として妥当なのは、テキストでしょう。 執筆者にもDTPアプリケーションを執筆に使ってもらう、もしくは、執筆者が利用できるワープロソフトで組版もするという可能性もありえなくはないですが、こうした方法は先に言及した「適切な吐き出し形式」に似たジレンマに陥ります。 「こう見えてほしい」という気持ちを前提にして吐き出しをすると、しっかりした文章や段落を構成するのが困難になるのです。 書いている最中に見せ方を工夫したくなってしまうのは、早すぎる最適化の罠だといってもいいでしょう。 まして、WYSIWYG環境で書くのは、バイナリコードを直接いじっているようなものです。 (そもそも、見た目の先にある組版という専門性が要求されるプロセスに、非専門家が手軽に介入できる状態はどうなのかという問題もあります。 原稿がどう見えてほしいかと、その要求をどう実装するかには、さらに一段階ギャップがあるのです。)

なんだか、ドキュメントにおける構造とスタイルの分離という、よくある話に収斂しているような気もしますね。 実際、気のせいじゃありません。 この記事で言いたかったことを、構造とスタイルの分離という話に翻訳すると、次のように要約できます。

  • ドキュメントの構造となる部分の試行錯誤では、テキスト形式を使うのが作業面でもっとも理にかなっている
  • ドキュメントの構造となる部分は、原稿に責任がある人から最後までアクセスを取り上げるべきでない部分でもあり、それに都合がいいのはテキスト形式である

なお、この記事の趣旨は「執筆や編集にはテキストエディタが最高」ではないので、べつにWordとかGoogle Docs、あるいはIDEなどを執筆や編集に使ってもぜんぜん問題ないです。 ただし注意が必要なのは、それらツールにネイティブな形式(.docとか)をソースにしてしまうと、ここに挙げたようなテキストであることの利点が生かせないということです。 なので、どんなツールで書くにしろ、どこかの時点ではテキスト形式にして、それを最終的なソース原稿とするのが無難だとおもいます。

記法が決まらないと前に進めないならMarkdown的なやつで

というわけで、文章を書くときは、「とにかく脳内をダンプし、試行錯誤して段落を組み立てる」のが基本です。 繰り返しになりますが、脳内を吐き出すときの記法は、どう見えてほしいかという気持ちに無意識に依存してしまいます。 その依存を断ち切り、どう見えてほしいかはいったん忘れて文と段落の構成に集中するというのが、一次脱稿でいい状態にもっていくコツ(はやく脱稿するコツではない)です。 「段落だけを書く」という覚悟で望みましょう。 どんな本にも適用できる決定版の見せ方はないけど、万能の書き方というのは実はあるので、パラグラフライティングをしっかりやってください

とはいえ、そうはいっても脳内を吐き出すときの記法に何かしら制約があるほうがいいっていう人も少なくないと思います。 段落だけとかストイックすぎて無理、見出しの指定方法やインラインの強調方法とか決まってないと書けない、とくに技術書ではコードブロックや図も入れたい、という要求は当然ありますよね。

そんなときは、とりあえず、Markdownふうの記法を使っておきましょう。 ここで、CommonMarkか、それともGitHubFlavoredか、といったことを気にする必要はありません。 見ためを確認したり、そこからワンパスでHTMLやPDFを生成することが目的ではないからです。 ちょっとしたブログ記事ならともかく、どんなMarkdown方言であれ、どのみちMarkdownだけをソースにして本は作れません。 Markdownだけで本が作れたら、XMLとかLaTeXとかとっくに滅んでますね。

まとめ

この記事では、なぜ自由な記法のテキスト形式が原稿の執筆と編集で優位性があるかについて、下記の2点に注目して主張しました。

  • どう見せるかは考えず、段落の書き込みに集中するためには、見せ方と表裏一体な記法には惑わされないほうがよい
  • 内容に責任をもつ著者や編集者が、自分たちには手が出せない状態になる直前まで計算機を使って原稿を操作するには、データ形式としてテキストが好都合

そのうえで、これらの要求を満足するならツールはテキストエディタでなくてもよいこと、シンプルな段落以外の要素として脳内をダンプする手法としてのMarkdownふう記法の可能性について考えました。

Markdownについては、また明日なにか書くかもしれません。

2017/12/06

英語圏のIT系技術書ブランドについての雑感

この記事はpyspa Advent Calendar 2017の6日めのために書きましたが、アマゾンアソシエイト目的です。

『退屈なことはPythonにやらせよう』が出た

2017年にブレイクしたPythonの本といえば、オライリー・ジャパンから発行された『退屈なことはPythonにやらせよう』ですよね。

実はこの本、そのむかし、自分でも翻訳発行をひそかに検討していたのです。 当時の翻訳者候補の方とのDMをさかのぼってみたら、少なくとも2015年7月以前の話でした。 「非プログラマーでもプログラミングしようぜ」という趣旨で著された本書は、わたし自身の書籍企画の方向性によくマッチしていました。 それで本書に目を付けたのですが、いかんせん分量は多いし、Pythonは日本だと入門者向け言語としていまいち盛り上がらないし(当時の話です)、なにより例題があんまりぐっとこないねという話で、そのときは企画化をパスするという結論を出しました。 これは余談にして重要なポイントでもあるんですが、それから起きた出来事を思うと、このとき本書を自分が企画化しなかったのは別の意味でも正解でした。

それから数年たち、Pythonブームという絶好のタイミングで本書が日本語化され、たくさんの人に読まれるに至ったのは、掛け値なしにとてもうれしいことです(ほんとだよ)。 逃がした魚は大きい的な気持ちもないではないですが、ぶっちゃけると、オライリーという看板で出たことが本書の日本での普及にとってとても大きなことだったと思います。

さて、ここで「アレ?」と思う人がいるかもしれません。 「この本はオライリーなのに、オライリーの編集者じゃないおまえが企画を検討してたって、いったいどういうこと?」

オライリーの本はO'Reillyの本とは限らない

『退屈なことはPythonにやらせよう』の原書は、O'Reilly Mediaではなく、No Starch Pressという北米の出版社による発行です。

https://www.nostarch.com/

この出版社の名前を聞くのは初めてという人でも、コンピュータ書に関する情報を気にしている方なら、その発行タイトルのなかには知っているものが少なからずあるでしょう。 No Starch Press発行の本で翻訳されているものを、思いつく限りざっと並べてみます(もちろん全部ではありません(たぶん))。

そうそうたるラインナップですよね。 さらに面白いことに、No Starch Pressは『マンガでわかる統計学』などの英語版の出版社でもあります。

いまではこんなにすごいNo Starch Pressですが、もとはBill Pollockという人が立ち上げた小さな出版社でした。 2006年にBillさんに会ったころもまだまだ小さい出版社でしたが、この10年くらいで一気に魅力的なラインナップを増やし、いまではIT系技術書界隈でかなりの存在感を示しています。 ここでまた余談だけど重要なポイントとして、2006年にBillさんに『マンガでわかる統計学』の版権買ってよという話をするとき、「エディターです」と自己紹介したら、「おれはパブリッシャーだぜ」と冗談で返されたのが自分のなかではものすごい衝撃で、いつかおれもパブリッシャーって名乗るぞとぼんやり思ったのでした (もっともBillさんはぼくのことさえ覚えてない気がする)。

話をもどすと、上記のNo Starch Pressの翻訳書のなかには、『退屈なことはPythonにやらせよう』以外にも、いくつかオライリー・ジャパン発行のものが含まれています。 つまりオライリー・ジャパンから発行されている翻訳書は、必ずしも世界的な技術書ブランドであるO'Reilly Mediaのタイトルだけではないのです。 オライリー・ジャパンの中の人は、No Starch Pressをはじめ、さまざまな海外の出版社からこれはと思う良タイトルをO'Reilly Mediaに限らず探してきて翻訳発行しているわけです。 これぞO'Reillyというカバーだけど動物の版画でない本がけっこうあるのは(宇宙人までいる)、そういうわけなのです。

No Starch Press以外で、日本ではO'Reillyブランドの技術書として誤認されてるんじゃないかなと感じてる本としては、たとえばこんな例があります。

上記6点は、すべて原書出版社がちがいます。当ててみよう。Hayao(-ε-δ)‏ さんに教えていただいたのでアソシエイト効果がありそうなほうを追記しました。Hayao(-ε-δ)‏ さんありがとうございます!)

なお、逆のパターンである「O'Reillyの本がオライリーから出ているとは限らない」も真です。 ただし、最近はO'Reilly Mediaのラインナップの魅力が落ちてるのと、O'Reillyブランドで魅力的なのはオライリー・ジャパンがしっかり出してくるので、ほぼオライリー・ジャパンから出てきているように見えます。

動物だけではない英語圏の技術書ブランド

ここまで長々とアマゾンアソシエイトを張りまくってきましたが、ここからが本記事のタイトルでもある「雑感」です。

2017年現在の英語圏におけるIT系出版社のブランド地図は、たとえば2000年代前半のそれとはかなり変動しています。 2000年代前半は、その当時で創業20年くらいのイケイケO'Reilly Mediaに圧倒的なブランド力がありました。 しかし現在は、この記事でも一押しのNo Starch Pressはじめ、やはり中堅どころのManning Publicationsなど、現時点で創業20年前後を迎えている中小の出版社のほうがむしろ精力的に面白い書籍を生み出している印象があります。 彗星のごとく登場してあっというまに手堅い出版社となったPragmatic Bookshelfも、これから創業20年前後にかけて、もうひと化けするかもしれません。

そうした出版社に比べると、すでに40年近い歴史を持つO'Reilly Mediaは、経営規模で見ても大手出版社として網羅的なラインナップを擁し、中小出版社の書籍の発売元として流通を支える存在にまで成長していますが、発行書籍の面白さとかクオリティという点では最近ぱっとしないなというのが率直な感想です。 それに呼応するように、いま企画が好調なオライリー・ジャパンが、少なくとも翻訳書についてO'Reillyタイトル依存でなくなっているというのは感慨深いところです。 そういえばオライリー・ジャパンも、いまちょうど創業20年ちょっとですね。

一方、O'Reilly Mediaよりさらに老舗のPearsonや、そのハイエンドコンピュータ書籍のレーベルとしてのAddison-Wesleyは、タイトル数こそ多くないですが、IT系技術書出版社としての信頼感はいまなお顕在だなあと感じることがわりとあります。 タイトルに対する信頼感という意味では、The MIT PressやCambridge University Pressなどの大学出版系も依然として強くて、これからも日本語で読めるようにしていくべきだと思えるような本はこのへんの老舗出版社のものがますます多くなるのかも、と思っています。

精力的といえば、英国を拠点に爆発的にラインナップを増やして一気に存在感を増したPacktという出版社もあります。 Packtの特徴は、とにかく最速であらゆるIT系のトピックについて書籍の形をしたものをそろえるという戦略です。 そうしたラインナップ網羅主義は、ある意味ではO'Reilly Mediaが目指してきたところだとも思います。 ラインナップ網羅主義には、個別のタイトルの出来不出来をケアできないという面があるので、個人的には避けていきたい方向性ですが、いかんせん展開が速いので、Packtの傾向にも注目だけはしていこうと思っています。

今回のオチ

日本語圏におけるIT系技術書の状況については、あまり大きなことを言える立場にないですが、いろんな人たちの紆余曲折とか踏ん張りとか地道な出版活動とかあって、いろんなブランドが盛り上がったり、消えたり、地に落ちたり、新しく誕生したりしています。

そんななかで、この記事をここまで読んでアマゾンアソシエイトを踏まなかった方には、2017年に4つのタイトルを発売して始動したラムダノートというIT系技術書出版社の名前を覚えてもらえるとうれしいです。

2017/12/03

TeXでつくる『RubyでつくるRuby』

この記事はTeX & LaTeX Advent Calendar 2017の3日めのために書きましたが、宣伝目的です。

TeX & LaTeX Advent Calendar 2017の重点テーマは「TeXでつくるアレ」とのことですが、偶然にも2017年、よく似たタイトルの『RubyでつくるRuby』(遠藤侑介著)という本が出ました。 プログラミング言語を学ぶときの例題としてプログラミング言語をつくる以上に格好のネタはない、という趣旨の本です。

プログラミング言語をつくるというと、なにやら難しく聞こえるかもしれませんが、『RubyでつくるRuby』では、わずか150ページのなかにそのエッセンスを凝縮しています。 本文の理解を助けるかわいらしいイラストもフルカラーでふんだんに用意されているので、はじめてプログラムを書いてみようかなという人でも、おそらく(願わくば)読み通せる内容です。 電子書籍はなく、古き良き紙の本のみですが、電子版がいいという人はAscii.jpでもとになった連載が読めるので、そちらをどうぞ!

プログラミング言語の処理系が扱うデータは「木」

『RubyでつくるRuby』では、プログラミング言語Rubyで書かれたプログラムを処理して実行するプログラミング言語を、プログラミング言語Rubyでつくります。 つまり、本書の読者が書くことになるプログラムが処理するのは、Rubyのプログラムです。

Rubyに限りませんが、多くのプログラミング言語では、プログラマーが書いたプログラムを実行する前に、そのプログラムをまず「木」と呼ばれる種類のデータへと変換します。 この「木」は、その名のとおり樹木のような姿をしていて、「枝がのびる節」と「葉」があります。

このへんは、文章で説明するよりも、絵で見るほうがはやいでしょう。 たとえば、次のようなRubyのプログラム(四則演算だけですが)がどんな木になるかというと……

(1 + 2) / 3 * 4 * (56 / 7 + 8 + 9) 

こんな木になります。式で見るより、項どうしの演算の関係がわかりやすいですね。

本書の解説には「木」を扱う場面がたくさん出てくるので、説明文やコードに加えてこんな具合に木の絵をたくさん用意できれば、いま説明しているデータの姿がどんなようすなのか「ひとめ」でわかります。 なので、ぜひ木の絵はたくさん載せたい。

かといって、こういう木の絵をぜんぶイラストレーターさんに描いてもらうのもたいへんです。 描くほうだけでなく、間違ってないかチェックするほうもめんどくさい。 それなりの見た目で、なおかつ間違いなくプログラムの木を描くには、どうすればいいでしょうか?

そう、TeXを使えばいいのです。 実際、上に例として出した木もTeXで生成しています。

TeXで木を描く

というわけで、前置きが長くなりましたが、『RubyでつくるRuby』の木の絵をTeXでどう描いたかをちょっと紹介します。 書籍『RubyでつくるRuby』では、プログラムの木を、Rubyにおける配列表現からTeXで生成しました。 これなら手間もかからず、なにより作図にともなう間違いもありません。

tikz-qtreeパッケージの使い方

木は、プログラムに限らずいろいろな場面に出てくるデータ構造なので、関連するTeXパッケージがわりとたくさん出そろっています。 そのなかで『RubyでつくるRuby』の木を描くのに選んだのは、 tikz-qtree というTikZベースのパッケージです。

https://ctan.org/pkg/tikz-qtree

この tikz-qtree パッケージを選んだ理由のひとつは、上下逆向きの木構造を手軽に描けることです。 木構造を描くときは、根を上にする(つまり本物の樹木でいったら上下逆)ことが多いのですが、本書の場合にはイラストにある本物っぽい木の絵とシームレスに読み替えてもらいたいので、根を下にして木構造を描ける機能が重要だったのです。

tikz-qtree のミニマルな例を示します。これは 2 * 4 というRubyプログラムの「木」の例です。

\documentclass[tikz,convert={outext=.png}]{standalone} 
\usepackage{tikz-qtree}
\begin{document}

\begin{tikzpicture}
  \Tree [.*
          [2 
           \node[draw]{4};
          ]]
\end{tikzpicture}

\end{document} 

\Tree[ ] のなかに、木を描いてきます。 [ ] を入れ子にすると、その中に書いたものが子どもの要素になります。 要素としてスペース区切りで値を書き込めば、それが葉になります。 子を持つ要素には、値の前に「 . 」をつけます。 上の例では、根にあたる「 * 」に「 . 」が必要です。 さらに上の例では、TikZの \node 命令がそのまま使えることを示すために、「4」のほうだけ枠をつけてみました( \node 命令なので末尾に ; を忘れずに!)。

上記を tree.tex として保存し、以下のようにpdflatexで処理すれば……

$ pdflatex --shell-escape tree.tex 

こんな絵が得られます。

この木の上下をさかさまにするには、 tikzpicture 環境に [grow'=up] というオプションをつけるだけです。

\documentclass[tikz,convert={outext=.png}]{standalone} 
\usepackage{tikz-qtree}
\begin{document}

\begin{tikzpicture}[grow'=up]
  \Tree [.*
          [2 
           \node[draw]{4};
          ]]
\end{tikzpicture}

\end{document} 

このままだと絵として味気ないので、色をぬったり、枠の形を変えたり、線の幅を調整したりするわけですが、そのへんはTikZの \node をごにょごにょいじるというつまらない話なので割愛します。 TikZのマニュアル(むかしは400ページくらいでしたが、いまでは1000ページ超)を片手にがんばってみてください。

TikZソースを木のソースから生成する

木の見た目を整えたら、毎回TikZを手描きするのはばかばかしいので、プログラムで生成するようにします。 『RubyでつくるRuby』で描きたいのはプログラムを表す木で、その木はRubyコードとしてはこんなふうな姿をしています。

["*", 2, 4] 

本当は、 2 とか 4 が何ものであるかを表すために、もうちょっとメタ情報がついていますが、だいたいこんな感じです。 (そもそも、配列でプログラムの木を表すのはあくまでも『RubyでつくるRuby』の中に限定した話で、じっさいのRubyではまったくべつの表現方法です。)

これはどう見てもS式なので、カンマを削除してGaucheで直接読み込んで変換し、 tikz-qtree パッケージを使った木を描くTeXソースを吐くようにしましょう。

(use srfi-13)
(use text.tree)

(define (deco-b b)
  #"\\node[text=white,inner sep=4pt,drop shadow,fill={rgb:blue,5;white,1;green,1},draw,rounded corners]{\\small ~b};")
  
(define (deco-l l)
  #"\\node[text=white,inner sep=2pt,drop shadow,fill={rgb:green,6;white,1;black,4},draw,ellipse]{\\mystrut\\smash{~l}};")

(define *before-tikz* "\
\n\\begin{tikzpicture}[grow'=up] \
\n  \\tikzset{ \
\n    every tree node/.style={font=\\ttfamily\\large}, \
\n    edge from parent/.append style={very thick}} \
\n  \\Tree ")

(define *end-tikz* "\n\\end{tikzpicture}\n\\clearpage\n")

(define *before-doc* "\
\n\\documentclass[tikz,border=10pt,convert={outext=.png}]{standalone} \
\n\\def\\mystrut{\\rule{0pt}{1.3ex}} \
\n\\usepackage{tikz} \
\n\\usepackage{tikz-qtree} \
\n\\usetikzlibrary{shapes.geometric,shadows}% \
\n\\begin{document}\n")

(define *end-doc* "\n\\end{document}\n")

(define (tikzqtree ts)
  (list *before-tikz* (mkqtree ts) *end-tikz*))

(define (mkqtree ts)
  (cond ((null? ts) "")
        ((pair? ts) (mkbranch
                      (car ts)
                      (map mkqtree (cdr ts))))
        (else (mkleaf ts))))

(define (mkbranch b l)
  (list "[." (deco-b (x->string b)) "\n " l "]"))

(define (mkleaf l)
  (list (deco-l (x->string l)) " "))

(define (main args)
  (call-with-input-file (cadr args)
    (lambda (p)
      (print
       (tree->string
        (list
         *before-doc*
         (map tikzqtree (port->sexp-list p))
         *end-doc*)))))) 

カンマをプログラムで削除しないのは、カンマなしならS式としてそのままreadできるからです。この手のユーティリティはコーディングが簡単なほうに倒してガッっと書いてしまうのが肝要だと思います。

実行結果

最初に紹介した、わりと複雑なかっこうをしている次のようなRubyの計算式について、プログラムの木を描いてみましょう。

(1 + 2) / 3 * 4 * (56 / 7 + 8 + 9) 

この計算式は、『RubyでつくるRuby』ではこんな感じの木(配列の配列)として表されます。

["*", ["*", ["/", ["+", 1, 2], 3], 4], ["+", ["+", ["/", 56, 7], 8], 9]] 

この一行をファイルに保存して、カンマだけエディタで削除し、先ほどのGaucheスクリプトで読み込むと……

$ gosh mktree.scm temp.rb > temp.tex 

こんな気持ちの悪いLaTeXのソースができます。

\documentclass[tikz,border=10pt,convert={outext=.png}]{standalone}
\def\mystrut{\rule{0pt}{1.3ex}}
\usepackage{tikz}
\usepackage{tikz-qtree}
\usetikzlibrary{shapes.geometric,shadows}%
\begin{document}

\begin{tikzpicture}[grow'=up]
  \tikzset{
    every tree node/.style={font=\ttfamily\large},
    edge from parent/.append style={very thick}}
  \Tree [.\node[text=white,inner sep=4pt,drop shadow,fill={rgb:blue,5;white,1;green,1},draw,rounded corners]{\small *};
 [.\node[text=white,inner sep=4pt,drop shadow,fill={rgb:blue,5;white,1;green,1},draw,rounded corners]{\small *};
 [.\node[text=white,inner sep=4pt,drop shadow,fill={rgb:blue,5;white,1;green,1},draw,rounded corners]{\small /};
 [.\node[text=white,inner sep=4pt,drop shadow,fill={rgb:blue,5;white,1;green,1},draw,rounded corners]{\small +};
 \node[text=white,inner sep=2pt,drop shadow,fill={rgb:green,6;white,1;black,4},draw,ellipse]{\mystrut\smash{1}}; \node[text=white,inner sep=2pt,drop shadow,fill={rgb:green,6;white,1;black,4},draw,ellipse]{\mystrut\smash{2}}; ]\node[text=white,inner sep=2pt,drop shadow,fill={rgb:green,6;white,1;black,4},draw,ellipse]{\mystrut\smash{3}}; ]\node[text=white,inner sep=2pt,drop shadow,fill={rgb:green,6;white,1;black,4},draw,ellipse]{\mystrut\smash{4}}; ][.\node[text=white,inner sep=4pt,drop shadow,fill={rgb:blue,5;white,1;green,1},draw,rounded corners]{\small +};
 [.\node[text=white,inner sep=4pt,drop shadow,fill={rgb:blue,5;white,1;green,1},draw,rounded corners]{\small +};
 [.\node[text=white,inner sep=4pt,drop shadow,fill={rgb:blue,5;white,1;green,1},draw,rounded corners]{\small /};
 \node[text=white,inner sep=2pt,drop shadow,fill={rgb:green,6;white,1;black,4},draw,ellipse]{\mystrut\smash{56}}; \node[text=white,inner sep=2pt,drop shadow,fill={rgb:green,6;white,1;black,4},draw,ellipse]{\mystrut\smash{7}}; ]\node[text=white,inner sep=2pt,drop shadow,fill={rgb:green,6;white,1;black,4},draw,ellipse]{\mystrut\smash{8}}; ]\node[text=white,inner sep=2pt,drop shadow,fill={rgb:green,6;white,1;black,4},draw,ellipse]{\mystrut\smash{9}}; ]]
\end{tikzpicture}
\clearpage

\end{document} 

これをコンパイルすると……

$ pdflatex --shell-escape temp.tex 

冒頭に掲載したような、こんなきれいなpngファイルが得られるというわけでした。

まとめ

『RubyでつくるRuby』を読むと、このような「木」がプログラムそのものだということがわかります。 このように生成された図だけでなく、hirekoke画伯描きおろしカラーイラストも豊富に掲載された『RubyでつくるRuby』をいますぐ買おう!

繰り返しになりますが、電子版はラムダノートでは出版していないものの、Ascii.jpでもとになった連載が読めます。ぜんぶ無料!