AsciiDocで文章作成して、PDF化

# はじめに

`Markdown` は手軽に文書を書くことができる言語である。しかし、目次やセクション番号、クロスリファレンス(例えば、詳細は Section 3.4.5参照。のような書き方)をしたいと思っても、`Markdown`の標準の記法ではサポートされておらず、`Markdown拡張`と`Pandoc`で頑張ればある程度はできるが、標準ではないので、VSCodeのプレビューやGitHubでのプレビューだと期待通り表示されない。
そこで、`Markdown`よりも表現能力の高い`AsciiDoc`を使う。

`asciidoc` 自体の書き方は、参考文献を参照してもらうとして、作成に必要な次のことがらについて述べる。

* `AsciiDoctor`のインストール。
* `VSCode`でプレビューする。
* PDFに変換する。
* Docker image で PDFに変換する。

## 作成する文章

以下の特徴を持つ `sample.adoc` 文章を対象とする。

* 表紙
* 目次
* セクション番号
* `mermaid`記載したUMLを図として埋め込む
* `PNG`画像を埋め込む
* 図番号
* クロスリファレンス


```adoc:sample.adoc
= サンプルドキュメント
:doctype: book  # 表紙
:toc:           # 目次
:toclevels: 5 
:sectnums:      # セクション番号
:author: Ken
:revdate: 2022/07/05
:revnumber: 1.0.0
:lang: ja
:imagesdir: images   # 画像を置くフォルダ
:xrefstyle: short    # クロスリファレンスの表記


== 最初のセクション

hello

**bold hello**

こんにちは

**太字のこんにちは**

== mermaid画像セクション

mermaidでUML図を書く。

[#img-mermaid] 
.mermaid画像
[mermaid]
....
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
....

== PNG画像セクション

[#img-png] 
.PNG画像
image::onepiece01_luffy.png[, 400]


== クロスリファレンスセクション

mermaid で記述した画像は、<<img-mermaid>> 参照。

PNG画像は、 <<img-png>> 参照。
```

フォルダ構造

```
.
├── images
│   └── notification_to_capp.md
└── sample.adoc
```

## AsciiDoctorのインストール

`AsciiDoctor`をローカルPCにインストールする。

1. rubyのインストール
2. asciidoctorのインストール

   ```sh
      gem install asciidoctor asciidoctor-diagram asciidoctor-pdf
   ```

3. node のインストール
4. `mermaid`を画像に変換するツールである`mermaid-cli`のインストール。

   ```sh
   npm install -g @mermaid-js/mermaid-cli
   ```

今回インストールしたバージョン

* asciidoctor (2.0.17)
* asciidoctor-diagram (2.2.3)
* asciidoctor-pdf (2.1.4)
* @mermaid-js/mermaid-cli (9.1.3)

### mermaid-cli の 動作確認

インストール後、`mermaid-cli`（コマンド名 `mmdc`）が動作するか確認する。

test.mmd を作成する。

```mmd:test.mmd
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

svgに変換する。

```sh
mmdc -i test.mmd -o test.svg
```

`test.svg`が次のように出力されることを確認する。

## `VSCode`でプレビュー

`VSCode`の`AsciiDoc`拡張を使うと、プレビューしながら編集することができる。

インストール＆設定方法

1. [VSCode拡張 AsciiDoc](https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode) をインストール。
2. `VSCode拡張 AsciiDoc`の設定。
`AsciiDoc`中の `mermaid` で記載したUML図を プレビューに表示するために、VSCodeの `settings.json` に次の設定をする。

  ```json:settings.json
  "asciidoc.asciidoctor_command": "asciidoctor -r asciidoctor-diagram",
  "asciidoc.use_asciidoctorpdf": true,
  "asciidoc.use_asciidoctor_js": false,
  ```


## PDFに変換

VSCodeプレビューでは、太字に設定した日本語が、期待通りに太字で表示されるが、
`asciidoctor-pdf`でPDF化すると、日本語が太字にならない。
太字のある日本語フォントを用意し、それを使うように設定をする。

### フォントの取得

TrueType (TTF) or OpenType (OTF)  が利用できる。

[ここに、](https://waku-take-a.github.io/asciidoctor-pdf%25E3%2581%25AB%25E3%2582%2588%25E3%2582%258BPDF%25E5%2587%25BA%25E5%258A%259B(%25E3%2583%2595%25E3%2582%25A9%25E3%2583%25B3%25E3%2583%2588).html) 利用可能なフォントリストがある。その中から、[懐源ゴシック](https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic/releases)を利用する。リンク先から日本語フォント `KaiGenGothicJP-*.ttf` をダウンロードし、`resources/fonts`以下に置く。

### テーマファイルの作成

ダウンロードしたフォントを利用するためにはテーマファイルを作成する必要がある。
テーマファイルは`yml`フォーマットで記述する。

`resources/theme/basic-theme.yml` を作成する。

```yml:resources/theme/basic-theme.yml
extends: default-with-font-fallbacks # asciidoctor-pdfの標準テーマ "default-with-font-fallbacks-theme.yml" を継承する。
font:
  catalog:
    merge: true
    # ダウンロードしたフォントをKaiGenGothicJPとして登録する。
    KaiGenGothicJP:
      normal: KaiGenGothicJP-Regular.ttf
      bold: KaiGenGothicJP-Bold.ttf
      italic: KaiGenGothicJP-Regular-Italic.ttf
      bold_italic: KaiGenGothicJP-Bold-Italic.ttf
base:
  font_family: KaiGenGothicJP  # KaiGenGothicJPを基本フォントとして利用する。
```

`asciidoctor-pdf`の標準テーマファイル(`default-with-font-fallbacks-theme.yml`など)は、`asciidoctor-pdf` のインストールフォルダ下の `data/themes` にある。

### フォルダ構造

この段階でのフォルダ構造は次のようになる。

```
.
├── images
│   └── notification_to_capp.md
├── resources
│   ├── fonts
│   │   ├── KaiGenGothicJP-Bold-Italic.ttf
│   │   ├── KaiGenGothicJP-Bold.ttf
│   │   ├── KaiGenGothicJP-Regular-Italic.ttf
│   │   └── KaiGenGothicJP-Regular.ttf
│   └── themes
│       └── basic-theme.yml
└── sample.adoc
```

## PDFに変換

`asciidoctor-pdf`コマンドでPDFに変換する。

```sh
asciidoctor-pdf \
    -a scripts=cjk \
    -a pdf-theme=resources/themes/basic-theme.yml \
    -a pdf-fontsdir=resources/fonts \
    -r asciidoctor-diagram \
    sample.adoc
```

このコマンドで、 `sample.pdf` が作成sれる。

## docker image で、PDF化

誰でも簡単にPDF化できるように、docker imageを用意する。

TODO

## さいごに

利用したファイル、及び、作成したPDFは、以下においておく。

https://github.com/kenmasumitsu/asciidoc-sample 



## 参考文献

* [Asciidoctor 文法クイックリファレンス(日本語訳)]([aaa](https://takumon.github.io/asciidoc-syntax-quick-reference-japanese-translation/))
* [AsciiDoc入門](https://qiita.com/xmeta/items/de667a8b8a0f982e123a)
* [AsciiDocチートシート](http://www.venus.dti.ne.jp/~iisaka/DocSys/cheatsheet-ja/asciidoc-869/asciidoc-869.html)
* [AsciiDoc vs Markdown 比較チートシート](https://ryuta46.com/344#:~:text=AsciiDoc%20%E3%81%AF%20Markdown%20%E3%82%88%E3%82%8A%E8%A1%A8%E7%8F%BE,%E5%AE%9F%E7%B8%BE%E3%81%AE%E3%81%82%E3%82%8B%E8%A8%80%E8%AA%9E%E3%81%A7%E3%81%99%E3%80%82)
* [脱Word、脱Markdown、asciidocでドキュメント作成する際のアレコレ](https://qiita.com/tamikura@github/items/5d3f62dae55617ee42bb)
* [asciidoctor-pdfによるPDF出力(フォント)](https://waku-take-a.github.io/asciidoctor-pdf%25E3%2581%25AB%25E3%2582%2588%25E3%2582%258BPDF%25E5%2587%25BA%25E5%258A%259B(%25E3%2583%2595%25E3%2582%25A9%25E3%2583%25B3%25E3%2583%2588).html)