ドキュメント(主に、仕様書)作成をする時に、少し問題に感じたのが、プログラミングと同じで
・同じ用語を、何度も書いていて、それが変更されると全て変更する必要がある
・画像を参照して表示していないので、差し替えが手間
このような問題を解決しようとして、定数定義が使えるマークアップ言語やドキュメント環境が無いか調べていた所、Asciidocが使えそうだったので、試してみた。
ここの人の手順を丸パクリ参考にした。
1. 環境構築
1-1.Rubyのインストール
ruby(2.2以上)をインストール(らしい)
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
というプレーンテキストを用意して、それを操作すればおk
2. 実際にHTMLを作成してみる
ここの人の、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