asciidoctor-pdfで社内ドキュメントを書こう

  • 81
    Like
  • 7
    Comment

この投稿は Fujitsu Advent Calender 2016 の 12日目の記事です。
この記事に書かれた見識は個人のものであり、所属する会社・組織を代表するものではありません🐸。

12/12修正:

  • asciidoctor-pdfインストールコマンドに誤りがありました。
  • サンプルのスタイルファイル名を confidential_style.yaml から public_style.ymlに変更し、機密区分表記をPublicにしました(不適当だったため)。
    • 合わせてサンプルPDFドキュメントの画像を差し替えています。
  • その他タイポを修正しました。

背景・動機🐸

技術職にかぎらず、仕事をする上でドキュメントを書く機会はたくさんありますが、大なり小なり組織に所属している以上、好き勝手にオレオレフォーマットを作って、「これがオフィシャルです」・というのはなかなか難しく、組織の内で用意されている(出廻っている?)Word, PowerPoint, Excel(誉れ高い方眼紙もあるよ!)など既成のフォーマットを転用してドキュメンテーションするのが一般的かと思います。

ただ、このフォーマットというのが必ずしも使いやすいとは言えないなぁ・と...

  • Wordのスタイル定義の作り込みがイマイチ
  • PowerPointで自由すぎるレイアウトされたドキュメントとかもう
  • 方眼紙ドキュメントのメンテつらい、したくない
  • 構成管理がつらい

こんな背景からか、僕の所属組織でもMarkdownとかTextileといった軽量マークアップ言語を使ってドキュメントを書く方が少しづつ増えている気がします(世の流れからみたら随分遅い・というツッコミはあるでしょうが)。

ただ、軽量マークアップ言語でドキュメントを書くときに問題になるのが、オフィシャルなドキュメントとしての体裁を整えにくいことでしょう。

例えば、組織の文書管理規定に沿った機密区分、公開範囲に関する情報の表示、権利情報の表記、企業ロゴの貼付、配布形式(PDFが望ましい)などなど、ある程度まっとうななドキュメントの体裁を整えようと思うと、Markdown単体ではなかなか実現が難しいですよね。

このあたりの問題を何とかするのに、AsciiDoc を使ってみよう・というのが本記事の内容です。

目指すところ🐸

ここからの記事では、以下の内容を目指していきます。

  • AsciiDocを使って、それらしい社内ドキュメントを書けるようになる
    • コーポレートカラーに沿ったスタイル・テーマになっている
    • 企業ロゴ、ブランドロゴが入っている
    • 機密区分、コピーライトなどメタ情報もちゃんと含めている
    • PDFでドキュメントを配布できるようする

それでは行ってみましょう。なお、本記事の内容は、Windows10(64bit)環境で確認しています(OSX, Linuxでも問題ないとは思います)。

また、本記事では、筆者の体力的な問題から、AsciiDocのマークアップ記法については特に触れません(すみません)。

AsciiDocで社内ドキュメントを書こう🐸

なぜAsciiDoc?

軽量マークアップ言語の中には、AsciiDoc以外にも、リッチなドキュメントの作成が可能なものはいくつかあります。例えば、Sphinxなどが有名で、ぼくも随分利用させてもらっています( blockdiagが大スキ )。でも今回は、AsciiDocです。これは何故かというと、一重にドキュメントをビルドする環境を整えるのが(比較的)楽だからです。

※ SphinxからPDFを出力しようと思うと、TexLiveが必要だったりちょっと敷居が高かった。

基本的にドキュメントは一人で書くものではないので、自分以外の方にもある程度導入してもらいやすいことを重視すべきだと思っています。もっと言えば、ドキュメントを書く・という立場では、どんなツールなのか?どんなビルド方法なのか?・とかはあまり興味がなくて、できるだけスッとドキュメントを書ける状況に入ることの方がずっと大切なわけです。

※だからこそMS Officeは今でもデファクトなのでしょう。

AsciiDocとその関連ツールは、比較的容易に導入ができるので、ノンプログラマーな方(僕もそうですが)であっても導入で躓かないかなーというラインだと思っています(ある程度のハードルがあることは否定できませんが)。

まずは導入🐸

Windows環境で、AsciiDocドキュメントからPDFドキュメントを出力するには、最低限以下の作業を実施する必要があります。

  • Rubyランタイムのインストール
  • asciidoctor のインストール( rubygem
  • asciidoctor-pdf のインストール( rubygem
  • 依存パッケージ prawn へのパッチ適応
  • PDFスタイルファイル、アセットのコピー
  • 作業ディレクトリの作成

Rubyランタイムのインストール

chocolatery が入っている場合は, rubyパッケージをインストールします。

> choco install ruby

chocolatery が入っていない場合は、ActiveScriptRubyを利用すると良いでしょう。

僕の環境では, ruby v2.2.2p95を使っています。

asciidoctorのインストール

asciidoctor は、AsciiDocフォートで記述されたテキストドキュメントを、HTMLなど別のフォーマットに変換するコンバータで、gemパッケージとして提供されています。以下のコマンドでインストールします。

> gem install asciidoctor

僕の環境では, asciidoctor v1.5.4 を使っています。

asciidoctor-pdfのインストール

asciidoctor-pdf は、AsciiDocフォートで記述されたテキストドキュメントを、PDFフォーマットに変換するコンバータで、gemパッケージとして提供されています。以下のコマンドでインストールします。

> gem install --pre asciidoctor-pdf

※ 12/12誤りを修正しました(ログオプション)

僕の環境では, asciidoctor-pdf v1.5.0.alpha.11 を使っています。

依存パッケージ prawn へのパッチ適応

asciidoctor-pdfで CJKドキュメントを扱う場合、テキスト行の折り返し( line-wrap )の動作に問題があることがわかっており、Issue 上では、 prawn-2.1.0 のソース( ${RUBY_ROOT}\lib\ruby\gems\2.2.0\gems\prawn-2.1.0\lib\prawn\text\formatted\line_wrap.rb )に修正パッチを当てることで改善するという記述がありますので対応しておきましょう。

@@ -118,7 +118,8 @@
         # The pattern used to determine chunks of text to place on a given line

         #
         def scan_pattern
-          pattern = "[^#{break_chars}]+#{soft_hyphen}|" +
+          pattern = "\\p{Han}|\\p{Hiragana}|\\p{Katakana}|\\p{Common}|" + # <-break all CJ chars
+            "[^#{break_chars}]+#{soft_hyphen}|" +
             "[^#{break_chars}]+#{hyphen}+|" +
             "[^#{break_chars}]+|" +
             "[#{whitespace}]+|" +

作業ディレクトリの作成

Asciidoctorドキュメントを作成するための作業ディレクトリを掘っておきます。

C:.
├─dist      // PDFの出力先とする
├─fonts    // フォントファイルを格納
├─images   // イメージファイルを格納
│  └─theme // スタイルから参照するイメージファイルを格納
└─style    // スタイルファイルを格納する

Gitを利用している場合は、この作業ディレクトリ上で, git init しておき構成管理対象にすると良いです。

PDFスタイルファイルとアセットを作業ディレクトリにコピー

asciidoctor-pdfは、スタイルファイル( YAMLフォーマット )を利用することで、体裁をカスタマイズすることができます。イチからスタイルファイルを書くこともできますが、デフォルトテーマをカスタマイズする方が楽なので、以下のPATHにあるデフォルトテーマファイルと、フォントファイルを作業ディレクトリにコピーしておきます。

  • スタイルファイル
${RUBY_ROOT}\lib\ruby\gems\2.2.0\gems\asciidoctor-pdf-1.5.0.alpha.11\data\themes\default-theme.yml
  • フォントファイル
${RUBY_ROOT}\lib\ruby\gems\2.2.0\gems\asciidoctor-pdf-1.5.0.alpha.11\data\fonts\*

作業フォルダはこんな感じになります。

C:.
├─dist      // PDFの出力先とする
├─fonts    // フォントファイルを格納
│  ├─ LICENSE-mplus-testflight-58
│  ├─ LICENSE-noto-2015-06-05
│  ├─ mplus1mn-bold_italic-ascii.ttf
│  ├─ mplus1mn-bold-ascii.ttf
│  ├─ mplus1mn-italic-ascii.ttf
│  ├─ mplus1mn-regular-ascii-conums.ttf
│  ├─ mplus1p-regular-fallback.ttf
│  ├─ notoserif-bold_italic-subset.ttf
│  ├─ notoserif-bold-subset.ttf
│  ├─ notoserif-italic-subset.ttf
│  └─ notoserif-regular-subset.ttf
├─images   // イメージファイルを格納
│  └─theme // スタイルから参照するイメージファイルを格納
└─style    // スタイルファイルを格納する
   └─default-theme.yml

スタイルファイルを構築しよう🐸

ここまでで AsciidoctorドキュメントをPDFフォーマットにビルドする環境が整ったので、本題のPDFドキュメントの体裁を調整していきます。

事前準備

スタイルファイルを設計する前に、組織のコーポレートカラーにあった配色パターンや、企業ロゴのイメージファイルなどを事前に収集しておくと良いです。今回はFujitsu Advent Calenderなので富士通スタイルっぽくしてみようと思います。

配色パターン

例えばこんな感じで配色を決めてみました。

項目 10進カラーコード 16進カラーコード
本文フォント(基調色) rgb(51, 51, 51) #333333
本文フォント(明るい強調色) rgb(231, 52, 64) #e73440
本文フォント(暗い強調色) rgb(163, 11, 26) #a30b1a
見出しフォント(基調色) rgb(51, 51, 51) #333333
見出しフォント(強調色) rgb(122, 30, 28) #7a1e1c
背景色(基調) rgb(255, 255, 255) #ffffff
背景色(コードブロック) rgb(237,237,236) #ededec
背景色(テーブルヘッダ) rgb(135,134,126) #87867e
背景色(テーブル奇数行) rgb(237,237,236) #ededec
背景色(テーブル偶数行) rgb(255, 255, 255) #ffffff
区切り線の色 rgb(87, 86, 79) #57564f

スタイル用イメージファイル

Google先生からの拾い物を加工してこんな感じに

  • 表紙背景イメージ(titlepage_fujitsu_background_gray.png)

  • ロゴイメージ(titlepage_fujitsu_logo_red.png)

作業フォルダの images\theme フォルダに保存しておきます。

C:.
├─dist   
├─fonts
.. 中略 ..
├─images
│  └─theme
|     ├─titlepage_fujitsu_logo_red.png     // 表紙背景イメージファイル
|     └─titlepage_fujitsu_background_gray.png // 表紙ロゴイメージファイル
└─style
   └─default-theme.yml

asciidoctor-pdfのスタイルの設計

asciidoctor-pdfのスタイル設定項目は多岐に渡るため、詳細は公式オンラインマニュアルか、参考資料を見てもらえればと思います。

ここでは、次のようなスタイルを設定することを考えていきます。

  • ドキュメント基本設計
  • 表紙
  • ヘッダー・フッター
  • 特殊な書式設定
  • その他(ブロック要素など)

スタイルファイルの実装は、デフォルトのスタイルファイルを参考に、作業ディレクトリの style 配下に public_style.yml を作成して、各セクションの設計内容を落とし込んでいきます。

C:.
├─dist
├─fonts
.. 中略 ..
├─images
│  └─theme
|     ├─titlepage_fujitsu_logo_red.png
|     └─titlepage_fujitsu_background_gray.png
└─style
   ├─public_style.yml  // オリジナルスタイルファイル
   └─default-theme.yml

ドキュメント基本設計

  • 用紙はA4縦
  • ページは「背景色(基調)」で塗りつぶし
  • 日本語フォントファミリは、Noto Serif を使う
    • オリジナルフォントがあればそれを使うのも良いかも🐸
  • 基本フォントサイズは 10.5pxとする
  • 字揃えは左揃えとする
  • 行の高さ(line-height) はゆったりめに18ポイント
public_style.yml
#------
# Font Section
#------
font:
  catalog:
    # Noto Serif supports Latin, Latin-1 Supplement, Latin Extended-A, Greek, Cyrillic, Vietnamese & an assortment of symbols
    Noto Serif:
      normal: notoserif-regular-subset.ttf
      bold: notoserif-bold-subset.ttf
      italic: notoserif-italic-subset.ttf
      bold_italic: notoserif-bold_italic-subset.ttf
    # M+ 1mn supports ASCII and the circled numbers used for conums
    M+ 1mn:
      normal: mplus1mn-regular-ascii-conums.ttf
      bold: mplus1mn-bold-ascii.ttf
      italic: mplus1mn-italic-ascii.ttf
      bold_italic: mplus1mn-bold_italic-ascii.ttf
    # M+ 1p supports Latin, Latin-1 Supplement, Latin Extended, Greek, Cyrillic, Vietnamese, Japanese & an assortment of symbols
    # It also provides arrows for ->, <-, => and <= replacements in case these glyphs are missing from font
    M+ 1p Fallback:
      normal: mplus1p-regular-fallback.ttf
      bold: mplus1p-regular-fallback.ttf
      italic: mplus1p-regular-fallback.ttf
      bold_italic: mplus1p-regular-fallback.ttf
  fallbacks:
    - M+ 1p Fallback
#------
# Page Section
#------
page:
  background_color: ffffff
  layout: portrait
  margin: [0.7in, 1in, 0.7in, 1in]
  size: A4
#------
# Base Section
#------
base:
  align: left
  font_color: 333333
  font_family: Noto Serif
  font_size: 10.5
  line_height_length: 14
  line_height: $base_line_height_length / $base_font_size
  font_size_large: round($base_font_size * 1.25)
  font_size_small: round($base_font_size * 0.85)
  font_size_min: $base_font_size * 0.75
  font_style: normal
  border_color: [87,86,79]
  border_radius: 2
  border_width: 0.5
# FIXME vertical_rhythm is weird; we should think in terms of ems
#vertical_rhythm: $base_line_height_length * 2 / 3
# correct line height for Noto Serif metrics (comes with built-in line height)
vertical_rhythm: $base_line_height_length
horizontal_rhythm: $base_line_height_length
# QUESTION should vertical_spacing be block_spacing instead?
vertical_spacing: $vertical_rhythm
#------

タイトルページ(表紙)の設定

  • 背景
    • 企業ブランドイメージ画像を背景に設定する
  • ロゴ
    • 紙面上部10%の位置に右寄せで企業ロゴを配置
      • 企業ロゴではなく「社外秘」などの機密区分のロゴをつくって埋め込んでも良いかも🐸
  • タイトル
    • 紙面上部45%の位置に左寄せで配置
    • フォントカラーは「見出しフォント(強調色)」にする
    • 書体は太字にする
  • サブタイトル
    • 見出しレベル3と同じ文字サイズ
    • 書体は太字
    • フォントカラーは「見出しフォント(基調色)」にする
    • 書体はノーマルにする
  • 著者ブロック、版数ブロック
    • 文字サイズは基本文字サイズの1.25倍にする
    • フォントカラーは「見出しフォント(基調色)」にする
    • 書体はノーマルにする

背景画像とロゴイメージファイルの指定は、Asciidocソース側で行いますので、ここでは割愛し、スタイルの設定を confidential_style.yaml に追記していきます。

public_style.yml
#------
# Title Page Section
#------
title_page:
  align: left
  logo:                                      # ロゴ
    top: 5%                                  # <-- 紙面上部から5%の位置にロゴを置く
    align: right                             # <-- 右寄せ
  title:                                     # タイトル
    top: 45%                                 # <-- 紙面上部から45%の位置にタイトルを置く
    font_size: $heading_h1_font_size         # <-- 見出しレベル1
    font_stye: bold                          # <-- 太字
    font_color: [122,30,28]                  # <-- 見出しフォント(強調色)
    line_height: 0.9
  subtitle:                                  # サブタイトル
    font_size: $heading_h3_font_size     # <-- 見出しレベル3相当のフォントサイズ
    font_style: bold                         # <-- 太字
    font_color: [122,30,28]                  # <-- 見出しフォント(強調色)
    line_height: 1
  authors:                                   # 作者
    font_color: [51,51,51]                   # <-- 見出しフォント(基調色)
    margin_top: $base_font_size * 1.25
    font_size: $base_font_size_large
  revision:                           # 版数
    font_color: [51,51,51]                   # <-- 見出しフォント(基調色)
    margin_top: $base_font_size * 1.25

ヘッダーとフッターの設定

  • ドキュメントヘッダー
    • フォントカラーは「本文フォント(基調色)」に合わせる
    • ヘッダーエリアの高さは基本フォントサイズの1.25倍とする
    • ヘッダーエリアの文字サイズは基本フォントサイズの0.75倍とする
    • ヘッダーエリアの境界は区切り二重線を表示する
    • ヘッダー(左)には 「ドキュメントタイトル」を表示する
    • ヘッダー(中央)は何も表示しない
    • ヘッダー(右)には「版数」を表示する
    • 偶数ページ/奇数ページを区別しない
public_style.yml
#------
# Header Section
#------
header:
  font_size: $base_font_size_small          # <-- 本文フォントより小さく  
  font_color: $base_font_color
  border_style: double                             # 二重線
  border_color: $base_border_color
  border_width: 0.25
  height: $base_line_height_length * 2.5
  vertical_align: bottom
  padding: [$base_line_height_length / 2, 1, 0, 1]
  recto_content:                           # 右見開きページ
    left: '{document-title}'               # <-- ドキュメントタイトル
    right: 'v{revnumber}'                  # <-- ドキュメント版数
  verso_content:                           # 左見開きページ
    left: '{document-title}'               # <-- ドキュメントタイトル
    right: 'v{revnumber}'                  # <-- ドキュメント版数
  • ドキュメントフッター
    • フォントカラーは「本文フォント(基調色)」に合わせる
    • フッターエリアの高さは基本フォントサイズの1.25倍とする
    • フッターエリアの文字サイズは基本フォントサイズの0.75倍とする
    • フッター(左)には 「機密区分」を表示する
    • フッター(中央)は段組みにし、上に「ページ番号」、下に「コピーライト」を表示する
    • フッター(右)には何も表示しない
    • 偶数ページ/奇数ページを区別しない
public_style.yml
#------
# Footer Section
#------
footer:
  font_size: $base_font_size_min
  font_color: $base_font_color
  # NOTE if background_color is set, background and border will span width of page
  border_color: $base_border_color
  border_style: solid
  border_width: 0.25
  height: $base_line_height_length * 3.5
  line_height: 1
  padding: [$base_line_height_length / 2, 1, 0, 1]
  vertical_align: top
  recto_content:
    left: Public                                      # <-- フッダー(左)に機密区分表記(Public)
    center: |                                                  # <-- フッダー(中央)
      {page-number} +                                          # <-- ... ページ番号
      Copyright &#169; HogeHoge CO.,LTD. All right reserved.  # <-- ... コピーライト
  verso_content:
    left: Internal Use Only                           # <-- フッダー(左)に機密区分表記(Public)
    center: |                                                  # <-- フッダー(中央)
      {page-number} +                                          # <-- ページ番号
      Copyright &#169; HogeHoge CO.,LTD. All right reserved.  # <-- コピーライト

特殊な書式設定

  • 見出し
    • 見出しレベルは4まで利用する
    • 見出しのフォントサイズは上のレベルから基準フォントサイズの 2.4倍, 2.0倍, 1.5倍、1.25倍とする
    • 見出しのフォントカラーは「見出しフォント(暗い強調色)」にする
public_style.yml
#------
# Heading Section
#------
heading:
  font_family: $base_font_family             # <-- 本文と同じフォントファミリを使う
  font_style: bold                           # <-- 太字
  font_color: [122,30,28]                    # <-- 見出しフォント(強調色)
  # ... h1 is used for part titles
  h1_font_size: floor($base_font_size * 2.4) # <-- 本文フォントの2.4倍のサイズ
  # ... h2 is used for chapter titles
  h2_font_size: floor($base_font_size * 2.0) # <-- 本文フォントの2倍のサイズ
  h3_font_size: round($base_font_size * 1.5) # <-- 本文フォントの1.5倍のサイズ
  h4_font_size: $base_font_size_large        # <-- 使わない想定
  h5_font_size: $base_font_size              # <-- 使わない想定
  h6_font_size: $base_font_size_small        # <-- 使わない想定
  line_height: 1
  margin_top: $vertical_rhythm * 0.4
  margin_bottom: $vertical_rhythm * 0.9
  • リンク
    • フォントカラーは「本文フォント(明るい強調色)」にする
    • 下線はつけない
public_style.yml
#------
# Link Section
#------
link:
  font_color: [231,52,64]
  • リテラル
    • フォントは「M+ 1mn」を使う
    • フォントサイズは、基本サイズより小さく10pxとする。
public_style.yml
#------
# literal is currently used for inline monospaced in prose and table cells
#------
literal:
  font_color: [163,11,26]
  font_family: M+ 1mn

その他

  • コードブロック
    • 背景は「背景色(コードブロック)」にする
    • コードブロックの枠は角丸にする
public_style.yml
#------
# Code section
# ... code is used for source blocks (perhaps change to source or listing?)
#------
code:
  font_color: $base_font_color
  font_family: $literal_font_family
  font_size: ceil($base_font_size)
  padding: $code_font_size
  line_height: 1.25
  background_color: [237,237,236]     # <-- 「背景色(コードブロック」
  border_color: $base_border_color    # <-- Base sectionで設定
  border_radius: $base_border_radius  # <-- Base Sectionで 2ポイントに設定
  border_width: 0.75
  • テーブル
    • テーブルヘッダ、フッターの背景書は「背景色(テーブルヘッダ)」にする
    • 偶数行は背景色を「背景色(テーブル奇数行)」にする
    • 奇数行は背景色を「背景色(テーブル偶数行)」にする
public_style.yml
#------
# Table section
#------
table:
  background_color: $page_background_color
  head_font_color: $base_font_color
  head_font_style: bold
  head_background_color: [135,134,126]             # <-- ヘッダー行
  foot_background_color: [135,134,126]           # <-- フッター行
  even_row_background_color: [237,237,236]         # 偶数行
  odd_row_background_color: $page_background_color # 奇数行
  border_color: [87, 86, 79]
  border_width: $base_border_width
  # HACK accounting for line-height
  cell_padding: [3, 3, 6, 3]
  • 定義リスト, アウトライン, 例示ブロック, etc...

Asciidocソースファイル(テンプレート部分)の作成🐸

ここまでで、最終的に出力するPDFドキュメントの体裁が概ね整ったので、次にAsciiDocドキュメントのソースファイルの作成に入ります。ここでは、AsciiDocソースファイル名を main.adocとして編集していきます。

作業フォルダはこんな感じになります。

C:.
├─main.adoc // AsciiDocソースファイル
├─dist
├─fonts
.. 中略 ..
├─images
│  └─theme
|     ├─titlepage_fujitsu_logo_red.png
|     └─titlepage_fujitsu_background_gray.png
└─style
   ├─confidential_style.yaml
   └─default-theme.yml

ドキュメントのメタ情報の設定

ソースファイルの先頭に、作成するドキュメントのメタ情報として、タイトル、著者、版数情報を書きます。

main.adoc
= ドキュメントタイトル        // タイトル
株式会社 かえるさん           // 著者
v0.1(Draft) 2016/12/12      // 版数情報

スタイルファイル、アセットとの関連付け

ここまでで作成してきたスタイルファイルを使ってAsciiDocドキュメントをPDFドキュメントビルドするため、Asciidoctor-pdfの、アトリビュート という仕組みを利用します。アトリビュートはビルド実行時に引数として渡すこともできますが、Asciidocソースファイルに直接記述してしまった方が良いと考えます。

main.adoc
...中略...
//==============================================================
// Attribute / アトリビュート
//==============================================================
:lang: ja                                 // 日本語ドキュメント
:doctype: book                            // 文書タイプは book にする
:description:                             // ドキュメントに関する説明 
:docname: ドキュメント名                   // ドキュメント名、ヘッダーに入る
:imagesdir: ./images                      // イメージファイルを置くフォルダ(相対PATH)
:icons: font                              // アイコンフォントを利用するフラグ
:iconsdir: ./images/icons                 // アイコンファイルの保管場所(未使用)
:pdf-fontsdir: fonts                      // フォントファイルを置くフォルダ(相対PATH)
:pdf-style: style/public_style.yml        // スタイルファイルを指定(相対PATH)
:title-logo-image: image:theme/titlepage_fujitsu_logo_red.png[] // ロゴ画像ファイルを指定(相対PATH)
:title-page-background-image: image:theme/titlepage_fujitsu_background_gray.png[] // 表紙背景画像ファイルを指定(相対PATH)

その他の設定

見出しの設定

:sectnums アトリビュートをつけることで、章見出し番号が出力されるようになります。ただ、デフォルトだと、Chapter.xx という表示になるため、日本語ドキュメントでは、:chapter-label アトリビュートをブランクに設定して、Chapter. が表示されないように明示的に設定する必要があります。

main.adoc
:sectnums:
:chapter-label: 

※ 余談ですが、第x章 のような見出しフォーマットには対応できないようです(残念)。

目次の設定

:tocアトリビュートをつけると、ビルド時に自動的に目次リスト(Index)を生成してくれるようになります。また、:toclevels アトリビュートによって、第何レベルまでの見出しリストを目次に出力するかを制御できます。

main.adoc
...中略...
:toc:
:toclevels: 3

コードブロックのシンタックス・ハイライト

asciidoctor-pdfでは、coderay を利用することで、コードブロックのシンタックスハイライトにも対応可能です。

main.adoc
...中略...
:source-highlighter: coderay

なお、このオプションを有効化する場合は、gem install coderay しておく必要があります。

ビルトインメッセージの日本語化

デフォルトでは欧文スタイルのメッセージになってしまい、体裁がチグハグな印象になるので、以下のアトリビュートを追加してちゃんとラベルが日本語で表示されるようにします。

main.adoc
...中略...
:toc-title: 目次
:preface-title: はじめに
:appendix-caption: 付録
:caution-caption: 注意
:example-caption: 例
:figure-caption: 図
:important-caption: 重要
:last-update-label: 最終更新
:listing-caption: リスト
:manname-title: 名前
:note-caption: 注記
:preface-title: まえがき
:table-caption: 表
:tip-caption: ヒント
:toc-title: 目次
:untitled-label: 無題
:version-label: バージョン
:warning-caption: 警告

ビルドスクリプトの作成

最後に、いちいちビルドコマンドを叩くのが面倒なので、ビルドスクリプトを作っておきます(Windowsなので手抜きでbatファイル)。実際の作業のことを考えると、PDF出力は少々時間がかかる(5秒くらいですが)ため、執筆中のビルドは、HTMLで行っておき、最終的な成果物を出すときに PDFにビルドするようにするとリズムが良いと思います。

このため、HTMLビルド用のスクリプト( make_html.bat )と、PDFビルド用のスクリプト( make_pdf.bat )を用意しておきます。

make_html.bat
@echo off
asciidoctor -b html5 -o dist/build.html main.adoc 
make_pdf.bat
@echo off
asciidoctor-pdf -o dist/build.pdf main.adoc 

作業フォルダはこんな感じになります。

C:.
├─main.adoc
├─make_html.bat //ビルド実行ファイル
├─make_pdf.bat //ビルド実行ファイル
├─dist
├─fonts
.. 中略 ..
├─images
│  └─theme
|     ├─titlepage_fujitsu_logo_red.png
|     └─titlepage_fujitsu_background_gray.png
└─style
   ├─public_style.yml
   └─default-theme.yml

テンプレート化しよう🐸

ここまでで、スタイルファイルと、Asciidoctor-PDFのソース・ファイルとビルド用のスクリプトが完成しました。ここから先は、目的のドキュメントを、Asciidocのフォーマットに従って作成していけばいいだけですね。

ここまでの作業フォルダを文書のテンプレートとして、レポジトリに登録しておき、何らかのドキュメントを書こう・となったときに clone して使うようにするとドキュメントの書き出しがとてもスムーズになります。

(応用)ドキュメントの種別ごとにテンプレートを作ってみる

仕事上でドキュメントを書く場合、ドキュメントの公開範囲や、機密区分など、ドキュメントのメタな分類に十分気を使う必要があります。このため、ここまでに作成したテンプレートをベースに、基調色、ロゴ、フッターの情報分類表記などを変更したテンプレートファイルを複数用意しておくと、視覚的にドキュメントの管理レベルが理解でき、より安全にドキュメントを運用していくことができるかなと考えます。

実際にビルドしてみた🐸

ここまでで作成したテンプレートをベースに、自作のAsciidocチートシートのソースをインクルードして、実際にPDFファイルに出力した結果の一部を掲載します(画像を切り出すのが面倒だったので手抜きです。ごめんなさいorz)

PDF表紙

結構それっぽいですね(´ω`)。

目次

なかなか良い感じです(´ω`)

ドキュメントコンテンツ

基本的なタイポグラフィは全く不自由しませんね(´ω`)。ヘッダー、フッターにもメタ情報がきちんと入っています。

  • コンテンツ例(1)

Asciidoctorは、Markdownに比べると表現力が高いのがいいですね。例(2)にあるような、IMPORTANTパラグラフ などは、運用手順書などでの重要な注意書きを書くのに重宝します。

  • コンテンツ例(2)

テーブルもMarkdownより幾分は書きやすいですね(でもつらいときはある)。

  • コンテンツ例(3)

まとめ🐸

良かったところ:

  • asciidoctor-pdfを使えば、それっぽいドキュメントの体裁を整えることができる。

    • カスタマイズ性は Texには及ばないけど、十分といえば十分。個人的には SphinxからのPDF出力と同等以上の自由度だと思う。
  • 構成管理ツールとの相性がよい

    • gitのsubmoduleを使えば、テンプレートと実際のドキュメント内容を分けて管理できるかも
  • ドキュメント種別毎にテンプレート化しておくと運用しやすい。

    • 公開文書パターンと、機密文書パターンでテンプレートを分けて運用すると成果物に統一感がでる

イマイチなところ:

  • 日本語(CJK)の扱いでパッチを当てないと厳しい(意図しない行落ちが多発)

    • これからのバージョンに期待?
  • sphinxみたいに、blockdiagやgraphvizのコードスニペットをインラインで書きたい

    • 画像ファイル化してインクルードするしかない

あとがき🐸

軽量マークアップ言語を使って、組織で通じるPDFドキュメントを作ろう、という取り組みは, Tex、Sphinx、Pandocなど色々なツールを使って試してきた経緯がありますが、総合的に見て、今のところasciidoctor-pdfが一番手応えがあります。また alpha の位置づけですが、もっと盛り上がって行けたらいいなぁ・と思っています。

また、今回のソースはまだコードホスティングサービスにアップはしていませんが、ご要望をいただければどこかにアップしたいと思います(一部ロゴなどを変更するかもしれません)。