困った時の自分用メモ

読んだ本を考察してメモったり、自分でいじった物の感想をメモったりする場。週1更新を目指します。

ドキュメント作成の話～Asciidocを使えるようにする～

考察（技術）

ドキュメント（主に、仕様書）作成をする時に、少し問題に感じたのが、プログラミングと同じで

・同じ用語を、何度も書いていて、それが変更されると全て変更する必要がある
・画像を参照して表示していないので、差し替えが手間

このような問題を解決しようとして、定数定義が使えるマークアップ言語やドキュメント環境が無いか調べていた所、Asciidocが使えそうだったので、試してみた。

qiita.com

ここの人の手順を丸パクリ参考にした。

1. 環境構築
1-1．Rubyのインストール
ruby(2.2以上)をインストール（らしい）

rubyinstaller.org

1-2. コマンドプロンプトで必要なパッケージのインストール

gem install asciidoctor             # asciidoctorのインストール
gem install --pre asciidoctor-pdf   # asciidoctor-pdfのインストール
gem install coderay                 # コードのシンタックスハイライト用
gem install asciidoctor-pdf-cjk     # PDF変換のレイアウト崩れ対応
gem install asciidoctor-diagram     # PlantUMLなどの図を使用

インストールはこれで終わり。
後は、適当なディレクトリに、

hogehoge.adoc

というプレーンテキストを用意して、それを操作すればおｋ

2. 実際にHTMLを作成してみる

qiita.com

ここの人の、sample.adocを拝借。

asciidoctor test.adoc

これで、HTMLは作成される。

3. PDF作成時の注意点
PDF作成自体のコマンドは

asciidoctor-pdf test.adoc

もしくは

asciidoctor-pdf -r asciidoctor-pdf-cjk

シーケンス図使うのであれば、

asciidoctor-pdf -r asciidoctor-pdf-cjk -r asciidoctor-diagram test.adoc

これで、PDFのエクスポートは出来るのだが、
初期状態のままだと、日本語が含まれていないフォントが使用されているようで、
日本語が□になって表示されない。

これを解決するには、adoc内で、フォントディレクトリ指定と、フォント設定ファイルを指定する必要がある。

3-1. MSゴシックのファイル取得
C:\Windows\Fonts
この中に、MSゴシック.ttcがあると思うので、コピーし、
adocファイルがある階層に、fonts/msgothic.ttc
といった形で配置し、
adocファイルに

:pdf-fontsdir: ./fonts

を追加する。

※情報
// PDF変換時のフォント指定
// 指定しない場合、デフォルトでは↓が適用される（ruby2.4 + 64bitWindowsOS)
// C:\Ruby24-x64\lib\ruby\gems\2.4.0\gems\asciidoctor-pdf-1.5.0.alpha.16\data\fonts

3-1. 設定ファイルの修正

// PDF変換時のスタイル指定
// 指定しない場合、デフォルトでは↓が適用される（ruby2.4 + 64bitWindowsOS)
// C:\Ruby24-x64\lib\ruby\gems\2.4.0\gems\asciidoctor-pdf-1.5.0.alpha.16\data\themes\default-theme.yml
:pdf-style: ./_pdf_themes/default-theme.yml

とのことなので、とりあえずこの
default-theme.yml
をコピーし、adocと同じ階層において
custom-theme.yml
とでもリネームしておく。

custom-theme.ymlの中身を

    # 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
      normal: msgothic.ttc
      bold: msgothic.ttc
      italic: msgothic.ttc
      bold_italic: msgothic.ttc
    # + 1mn supports ASCII and the circled numbers used for conums
    #M+ 1mn:
    #  normal: mplus1mn-regular-subset.ttf
    #  bold: mplus1mn-bold-subset.ttf
    #  italic: mplus1mn-italic-subset.ttf
    #  bold_italic: mplus1mn-bold_italic-subset.ttf
    M+ 1mn:
      normal: msgothic.ttc
      bold: msgothic.ttc
      italic: msgothic.ttc
      bold_italic: msgothic.ttc

こんな感じに書き換えたら、
adocファイルの中に

:pdf-style: custom-theme.yml

を追加する。

これで、日本語表示ができるPDFが出力される。

4. 定数置換の方法

:const-string-1: 定数1
ここで{const-string-1}の表示
ここで{const-string-1}の表示2

こんな感じでOK