技術同人誌をMarkdownで書いて得た学びと、しくじったお話

IT技術的なお話

まえがき

2020年、あけましておめでとうございます。

初めましての方、はじめまして。そうでない方はお久しぶりにお目にかかります。 そらまめです。月2で更新するとか言ったな、あれは嘘だ

前回の更新から随分と日が経ちました。ゲームクライアントのエンジニアになるつもりがPHPerコーダーになってしまってました。人生って難しいですね。
PHP、言語仕様とか標準ライブラリに悪戦苦闘しています。 PHPマジで絶対許さんからな(中指立てながら)

さて、なぜこの時期に筆を取ったのかと言うと………
2019/12/28〜31開催 コミックマーケット97にて、まんてら( @manntera )さん(便宜上、本文ではサークル主さんと記すことにします)主催のサークル?(というかDiscordサーバー)「まんてらスタジオ」さんより頒布されます(といっても電子書籍なのですが)、『新しい挑戦をしたいときに読む本』(一応2冊めなのでvol.2とでもしましょう)に寄稿したからです。

…寄稿したにはしたのですが、2019年の夏冬コミにて「まんてらスタジオ」から頒布されました「新しい挑戦をしたいときに読む本」(既刊2冊)の、原稿の取りまとめから校正(これは流石に複数人で行いました)・PDF化を執り行う、編集?的なポジションを(いつの間にか)担当していました。 どうしてこうなった！

今回の投稿では、2冊の同人技術誌の編集的な何かをして得た学びとしくじり、それと今後の自分を含めた、この先技術同人誌を書く人に向けた知見?を共有していきます。

ということで、まずはC96のときのお話から。

夏コミの同人技術誌の編集的な何かをしたお話

時期は遡ること2019年夏のことです。 記事をしたため、PDFに起こして納品、終わりーーーと思っていたら、サークル主さんがPDFのデザインをえらく気に入ったらしく、「全員分の記事をPDFに起こして欲しい、あと文章読みやすかったのでぜひ校正を手伝って欲しい」という旨の依頼が飛んできました。

(このときは Quiver というアプリを用いてMarkdownで記事を書き、CSSを書くことでスタイリングできる機能があったので、雑に拾ったCSSを改造してよしなにスタイリングし、PDFにエクスポートしていました。)

ということで校正のお手伝いをし(流石にこれは複数人で行いましたが)、私が各執筆者の記事をWord(というよりはGoogle Document)からMarkdownに起こし、Quiverに転記してPDFに変換といった感じで作業していました。

このときは記事の本数も一人でQuiverでポチポチ変換できる範疇に収まっていたので、私一人でなんとかなりました。

そしてC96当日、無事「新しい挑戦をしたいときに読む本」(Vol.1)を頒布することができました。

C96にて頒布した「新しい挑戦をしたいときに読む本」は こちらのBOOTHページ から。
無料で入手いただけます。
また、執筆者に金銭的支援ができる「支援枠」で投げ銭的なこともできますので、ぜひぜひ。

冬コミの技術同人誌の編集以下略

さて、時は進み2019年11月。
再び寄稿することになり、自分も記事をしたためて提出、これで終わりーーーと言っていたら再び校正・編集・簡易的な製本を再びサークル主さんから依頼されました。 (サークル主さんから個別連絡が来てある程度察したのは内緒)

C96の回では時間もなかったことも有り、手持ちのアプリにコピペを繰り返して出力作業をしていたのですが(とはいえ、C97のときも依頼時点で3-4週間前だったのですが...)、記事の本数と分量を考慮し、ある程度自動化したいと思ったので、何らかの手法でMarkdownからPDFに起こす方法がないかというのを模索しました。(大前提、Markdownで執筆することは決まっていたのでそれに救われた感じではあります)

で、ざっくりと以下の作戦を立てました。

  1. 執筆者はMarkdownで執筆し、Githubで管理しているので、よしなにローカルにソースを引っ張ってくる
  2. MarkdownからHTMLに変換
  3. HTMLをCSSでスタイリングしてPDFに出力

で、「何らかの手法でPDFに変換する」具体的な手順ですが、以下の作戦で行いました。

といった感じでMarkdownをPDFに変換しました。

markdown-it で変換する際に markdown-it のプラグインを色々突っ込んで mathjax 記法に対応したりはしましたが...
package.json 含めた変換プログラムはそのうち晒そうかなと思っています。

C97にて配布しました「新しい挑戦をしたいときに読む本」(Vol.2)は こちらのBOOTHページ から。
こちらも無料で入手いただけ、支援枠もあります。

学びと反省

さて、2回の編集?業務を経て色々と学びと反省を得ました。

技術同人誌の編集をして得た学び

Markdownで書くのが良い

Markdownは原稿の管理・編集が楽ですので、Markdownでの執筆は維持できたらなぁと思います。可能なら。
Markdownファイルはテキストデータですので、Gitでバージョン管理することにより

  • 編集履歴を追跡することができる
  • リモートリポジトリにGitHubを利用することで、校正をPullRequest機能を用いて行える(これはGitというよりはGitHubを利用することで得られるアドですが...)

といったメリットがあります。

夏コミではGoogle Documentで編集・校正作業をしていました。
一応、Google Documentも版の管理はできますし、提案機能で校正作業はできたのですが...
(Google Documentと比較して)手元にソースを置けること、差分をコミットとしてある程度まとめたりまとめなかったりした単位で管理できること(Google Documentだと編集が即座にコミットされてしまうので...)が強みなのかなぁと思います。
WordファイルをGit管理とか気が狂う自信しかない

作る上で発覚したしくじりと反省

まぁ、全て順調に技術同人誌が作れたわけではないです。
ということでしくじりなんかも共有しようかなと。

HTMLをPDF化しただけでは本として出すのは厳しい?

詳しくは https://note.solarsolfa.net/n/n697389a6be3bをご覧いただければと...

少なくとも、「新しい挑戦をしたいときに読む本」シリーズは上記の記事にあるような、印刷所に納品できるような原稿は作れてないなぁ…という感じです。
まぁ、冬コミの本が出来上がってから読んだので手遅れ感ありますが…

組版環境を整えていない

また、そもそもの問題として、組版環境を整えていませんでした。
論文や本を書く際にLaTeXのような組版環境を使うのはごく自然の事のはずなのですが...
そもそも唐突な依頼ということもあり、PDFに出力することを最優先に取り組んでいたので頭の中から組版環境を構築することが飛んでいたのはあるなぁと。

で、LaTeXに代表される?組版環境には本を書くための便利な機能が備わっていることが多いんですよね... 例えば、HTMLでは改ページとかの概念がそもそもないので、そのままPDFに出力すると、うーん残念…という感じになる、といった具合ですね。 スタイルシートを駆使すれば文字や写真の配置等々はコントロールできるのでしょうけど...
まぁWebデザイナーでもないですので、そこは勘弁してほしいですね。うん。

しくじりの対策

で、しくじりを経て対策がないかちょいと調べてみたところ、それっぽそうなのが見つかりました。

組版環境を用意する

当然といえば当然なのですが、本を作っていく以上、組版環境を整えるのが良いなーと感じました。(というか、HTMLをPDFにそのまま起こして本にできたのなら、PCで組版できるようなミドルウェアがあふれるわけないですしおすし...) で、軽く調べてみたところ「Re:VIEW」「Vivliostyle.js」「Pandoc」というのがあるらしいです。 まだ詳しくは調べられていないのですが、これらを活用すればMarkdownからPDFにいい感じに出力できそうな感じがあります。

次回は組版環境構築もしっかりしていきたいですね。

属人化を防ぐ

とはいえ、最も根本的なところに問題が有りまして...
それが、現状で「まんてらスタジオ」にてPDF化できる人員が私しかいない状況、ということです。
なので、変換・組版環境の自動化・コード化を行ってサークル内外問わず、誰でもMarkdownからいい感じに本の形になるやつを組めたら良さそうかな、という感じはします。

どうやら、調べてみると組版環境を閉じ込めたDockerfileがネットに転がっているようですね。 Docker Engineをインストールできる環境であれば、どのPCであっても変換環境を用意できますし、統一的に環境も作れますし、環境構成もコードで共有できますしでいいことずくめですね。

あとがき

ということで、技術同人誌を作る過程で得た気付きやしくじりを簡単に綴ってみました。
とはいえ、この記事は今後の自分が思い返せるように覚書的な感じの扱いなのですが...
これから技術同人誌を書く方のヒントに少しでもなれば幸いです。

ではでは、また。