PDFのドキュメントを作るのはやめよう、asciidoctor-pdfをやめた理由

前回、脱Word、脱Markdown、asciidocでドキュメント作成する際のアレコレでasciidocをHTMLとPDFに変換する方法を紹介した。

• asciidoctor・・・asciidocファイルをHTMLファイルに変換するruby製ツール
• asciidoctor-pdf・・・asciidocファイルをPDFファイルに変換するruby製ツール

当初はドキュメントをHTMLとPDF両方のフォーマットで公開していた。
が、asciidoctor-pdfを使ったPDF変換はあまりにも面倒なので、メンテするのを止めた。
その理由を記載する。

理由1. 文字の色が変えられない

markdownと違って、asciidocでは文字色は変えられるが、asciidoctor-pdfのバグか、文字の色が変えられない。

理由2. レイアウトが崩れる

長い表の場合などレイアウトが崩れる。

理由3. HTML/PDF両方確認するのが面倒

理由1, 2などにより、HTMLとPDFでは全く同じ結果にならないので、両方確認する必要があり、すごい面倒。

理由4. GIFが使えない

ドキュメントで分かりにくい箇所はアニメーションGIFを使っているが、
PDFでアニメーションGIFが使えない。

image:animation.gif[アニメーションgifは表示されない]

↓ PDF変換

理由5. HTMLとPDFの分岐ロジックを書くのが面倒

「理由4. GIFが使えない」とかでHTMLとPDFの差異がある場合、asciidocで以下のように分岐処理を書かないといけない。

ifeval::["{backend}" != "pdf"]
image:animation.gif[]
endif::[]

理由6. 別文書へのリンクが切れる

文書内でも文書外でも別の場所へ飛ぶときにリンクを貼ることはPDFでも可能。

文書内リンクは意識する必要はないが、文書外のリンクは当然、そのファイルもダウンロードなどしておかないといけないし、相対パスもパスはちゃんとあっていないといけない。

でもぱっと見、リンクが文書内か文書外か、リンク先がちゃんとあるか、判別不能。

理由7. PDF変換が長い

adocファイルからPDFに変換する場合、HTMLと比べて10倍時間がかかる。
asciidocファイルをGithubで管理。プルリクエストがmasterにマージされたタイミングでJenkinsでhtml/pdf変換をかけているが、30ファイルくらいあるとジョブが20分以上かかる。

最後の理由. 頑張ってもみんなPDFを見ない

いつでも最新のHTMLと、最新かどうかわからないPDF、当たり前だが普通の人はみんなHTMLを見る。PDFで見る人はいない。

PDFにしたいと思われるケースとして、以下がある。

• ネットワークに繋がらない場所で見たい、ネットワーク障害発生
  • そんなレアケースのために頑張る？
• ファイルとして渡したい
  • ゼロではないが、HTMLをAWS S3にアップロードして、静的サイトで公開したほうがラクでは？（セキュリティが気になるならIP制限とかかければ？）

が、そこまでして頑張る気も起きず、「PDF止めます」と宣言しても、特に反対もなく、PDFをやめました。