前回、脱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をやめました。