はじめに

前回までの記事でGitHub Actionsを利用したAsciiDoc出力の全体の流れについて仕組みを交えて説明してきました。
今回からは再びAsciiDocの利用方法に目を向け、より便利に利用できるような使い方の紹介として「PDF出力」について解説します。
PDF出力については複数回の構成になり、最初の今回は「HTMLとPDFの大きな違い」と「Asciidoctorで変わること」を解説します。
次回以降では具体的にPDF出力方法と仕組みを解説します。

前回までの記事について

これまでの記事はこちらにあります。こちらも合わせてお読みいただけると嬉しいです。

• AsciiDocを利用してエンジニアのナレッジを上手に集約しよう
• GitHub Actionsを使って気軽にAsciiDocを出力しよう(1)
• GitHub Actionsを使って気軽にAsciiDocを出力しよう(2)
• GitHub ActionsのAsciiDoc用アクションの仕組み(1)
• GitHub ActionsのAsciiDoc用アクションの仕組み(2)
• GitHub Actionsで利用したいAsciidoctorの環境
• GitHub Actionsで利用したいDockerコンテナの基礎

本ページで利用するサンプルについて

出力サンプル用のリポジトリは僕の個人的なプロジェクトの一環で公開しています。前回までのものよりPDF出力可能になるなどバージョンアップしています。(以前の記事とはタグでURLを分けています)

このサンプルではPDF出力でつまづきやすい部分の多くを解決しているので、このサンプルを元にしてご自身の環境を構築すると簡単にPDF出力を行うことができます。

• Analog-inc/asciidoctor-action-sample

HTMLとPDFの大きな違い

HTMLもPDFも見慣れたファイルです。普段意識しないその二つのファイルの違いを理解することが、日本語PDFを思った通りに出力することの手助けになります。

マークアップ言語ではなくページ記述言語

HTMLとPDFはその利用目的などによって内部構造が大きく構造が変わります。
それぞれのファイルについての特徴は以下のとおりです。

HTMLについて

HTMLはHyperText Markup Language（ハイパーテキスト マークアップ ランゲージ）の略で、複数の文書（テキスト）を相互に関連付けたり結び付けるハイパーテキストを記述するためのマークアップ言語です。略してHTML（エイチティーエムエル）と呼ばれています。ハイパーリンクや画像等を埋め込む機能、見出しや段落といった文書の抽象構造といった機能があります。
AsciiDocのような高い可読性はありませんが、テキストエディタで内容を確認・編集することは可能です。

PDFについて

PDFはPortable Document Format（ポータブル・ドキュメント・フォーマット）の略でAdobe Systemsが開発および提唱しています。
特定の環境に左右されずに全ての環境でほぼ同様の状態で文章や画像等を閲覧できる特性を持った標準化されたファイルフォーマットで、どんな環境にファイルがあっても製作者が意図した表示や印刷ができるように、PostScriptの技術を元に発展させた規格として生まれています。
図形描画等を行うPostScriptも読みやすいものではありませんが、PDFでは圧縮などの機能も持つため可読性はありません。
またレイアウトを詳細に維持するため文書構造のため、マークアップ言語のような見出しや段落といった文書の抽象構造を維持する事もありません。

画像が埋め込みになる

PDFは印刷用の技術から発展しているため、外部のサーバー等からリンクしたファイルを表示できるHTMLと違い、画像の自体のデータや位置、表示方法まで内部に記録しています。
このため、AsciiDocで利用している画像ファイル自体をPDFファイル内に埋め込む必要があります。

フォントが埋め込みになる

PDFはプリンタやPCにインストールされたフォントに依存していたPostScriptと異なり、どこでも同じ見た目で文章が表示できるようにフォントの埋め込みを行います。
これは、マークアップされたテキストを表示する前提として閲覧環境のフォントに頼るHTMLと大きく異なります。
このためAsciiDocをPDF出力する際は表示したいフォントをPDFファイル内に必ず埋め込む必要があります。

※ 編集のためのPDFとしてフォントを埋め込まない場合や、ブランディングやユーザーエクスペリエンスのためにフォントを埋め込むHTMLもあります。

Asciidoctorで変わること

ここまではファイルフォーマットに関わる部分を説明しましたが、今度は実際にAsciidoctorを利用して出力するために何か変わるか見ていきましょう。

コマンド(出力するアプリケーション)が変わる

これまでの解説では以下のリンクのページで解説したように、HTMLでは『asciidoctor』コマンドを利用してHTML出力を行なっていました。
これに対して、PDF出力では『asciidoctor-pdf』コマンドを利用して出力します。

• GitHub ActionsのAsciiDoc用アクションの仕組み(1)

フォントや画像の埋め込みに関わる設定が必要になる

これまでの解説では単純な.adocファイルを引数として渡すだけで、HTMLを出力できましたがPDFではフォント等の指定が必要になります。
実際にはフォント等の指定がなくても出力できる場合もありますが、それは日本語を含まないラテン系文字の場合に限定されてしまいますし、標準で用意されている日本語も表示可能なテンプレートはボールドなどの表現なども行えません。
これ以外にも細かく指定しないと思ったような出力ができない場合があります。
この辺りの解説は次回以降の記事で行なっていきたいと思います。

まとめ

今回はHTML出力からPDF出力での主な変更点を中心に簡単に解説しました。
次回からは実際のPDF出力方法を説明したいと思います。