（メモ）WindowsでAsciidocの編集環境を整える

# はじめに
- Asciidocでドキュメントを作成することになり、自分の端末上でVSCodeの環境を整えた際のメモ
- 参考にした情報（どれも丁寧な説明で以下を参照すれば基本的に対応できる）
    - [Asciidoctor Docs --Install Using Ruby Packaging](https://docs.asciidoctor.org/asciidoctor/latest/install/windows/)　`※asciidoctor(gem)のインストールまでの手順として参照`
    - [Windows上のVisual Studio Codeで、AsciiDocのプレビュー環境の構築](https://tech.synapse.jp/entry/2019/06/03/110000)　`※その他のツールの導入や設定、プレビューの確認の手順として参照`
    - [Windows上のVisual Studio Codeで、AsciiDocからPDF出力](https://tech.synapse.jp/entry/2020/04/01/120000) `※PDF出力のための設定手順を参照`
    - [Asciidoctor Docs --Custom Fonts](https://docs.asciidoctor.org/pdf-converter/latest/theme/custom-font/)  `※PDF出力のための設定手順を参照`
    - [asciidoctor-pdfでかっこいいPDFを作る(1)](https://qiita.com/kuboaki/items/67774c5ebd41467b83e2) `※PDF出力する際のフォント指定の手順として参照`
    - [AsciiDoc を PDF 化する時の日本語フォントを指定する](https://ryuta46.com/267) `※PDF出力する際のフォント指定の手順として参照`
- 環境
    - Windows 10（そろそろ11に上げる予定）


# 概要
## 手順
1. Chocolateyのインストール
1. rubyのインストール
1. asciidoctor (gem)のインストール
1. 各種アプリのインストール
1. rubyのモジュールインストール
1. VSCode拡張機能のインストール
1. Visual Studio Codeの設定
1. フォントの設定（PDF生成用）

## 導入したもの
- 各種アプリ
    - vscode
    - graphviz
    - correttojdk
- rubyモジュール　*[asciidoctor (gem)のインストール]で一括で導入してもよかったかも
    - asciidoctor-diagram
    - asciidoctor-pdf
    - ~~asciidoctor-pdf-cjk~~ `メンテナンス終了のため利用しないほうがいい` 
        - 参考：[asciidoctor-pdfで日本語を含むPDFの出力を行う](https://qiita.com/mitsu48/items/34875bbc8ba00760fe27#_reference-e1f72ce5e5f3d9cef664)
    - coderay
- VSCode拡張機能
    - joaompinto.asciidoctor-vscode
    - ms-ceintl.vscode-language-pack-ja

# ログ・メモ
`基本的には[はじめに]に記載した情報を参照すればできる。以下は自分が作業内容を記録・再利用できるようにメモに起こしたもの。`
## Chocolateyのインストール
- 以下のサイトにアクセスし、[Install Chocolatey for Individual Use:]セクションに記載されているコマンドをコピー
    - https://chocolatey.org/install#individual
- 自分の端末のPowerShellを管理者権限で起動し、コピーしたコマンドをペーストして実行
```powershell
PS C:\WINDOWS\system32> Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))                                                                     Forcing web requests to allow TLS v1.2 (Required for requests to Chocolatey.org)
Getting latest version of the Chocolatey package for download.
Not using proxy.
Getting Chocolatey from https://community.chocolatey.org/api/v2/package/chocolatey/1.1.0.
Downloading https://community.chocolatey.org/api/v2/package/chocolatey/1.1.0 to C:\Users\HANAKO~1\AppData\Local\Temp\chocolatey\chocoInstall\chocolatey.zip
Not using proxy.
Extracting C:\Users\HANAKO~1\AppData\Local\Temp\chocolatey\chocoInstall\chocolatey.zip to C:\Users\HANAKO~1\AppData\Local\Temp\chocolatey\chocoInstall
Installing Chocolatey on the local machine
Creating ChocolateyInstall as an environment variable (targeting 'Machine')
  Setting ChocolateyInstall to 'C:\ProgramData\chocolatey'
WARNING: It's very likely you will need to close and reopen your shell
  before you can use choco.
Restricting write permissions to Administrators
We are setting up the Chocolatey package repository.
The packages themselves go to 'C:\ProgramData\chocolatey\lib'
  (i.e. C:\ProgramData\chocolatey\lib\yourPackageName).
A shim file for the command line goes to 'C:\ProgramData\chocolatey\bin'
  and points to an executable in 'C:\ProgramData\chocolatey\lib\yourPackageName'.

Creating Chocolatey folders if they do not already exist.

WARNING: You can safely ignore errors related to missing log files when
  upgrading from a version of Chocolatey less than 0.9.9.
  'Batch file could not be found' is also safe to ignore.
  'The system cannot find the file specified' - also safe.
chocolatey.nupkg file not installed in lib.
 Attempting to locate it from bootstrapper.
PATH environment variable does not have C:\ProgramData\chocolatey\bin in it. Adding...
警告: Not setting tab completion: Profile file does not exist at
'C:\Users\HANAKOYAMADA\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1'.
Chocolatey (choco.exe) is now ready.
You can call choco from anywhere, command line or powershell by typing choco.
Run choco /? for a list of functions.
You may need to shut down and restart powershell and/or consoles
 first prior to using choco.
Ensuring Chocolatey commands are on the path
Ensuring chocolatey.nupkg is in the lib folder
PS C:\WINDOWS\system32>
```
## 必要なモジュールのインストール
- コマンドプロンプトを管理者権限で起動

### ruby
- rubyをインストールする
  - `choco install ruby`
  - `refreshenv`
  - `ruby -v`

```cmd
c:\>choco install ruby
Chocolatey v1.1.0
Installing the following packages:
ruby
By installing, you accept licenses for the packages.
Progress: Downloading ruby.install 3.1.2.1... 100%
Progress: Downloading ruby 3.1.2.1... 100%

ruby.install v3.1.2.1 [Approved]
ruby.install package files install completed. Performing other installation steps.
The package ruby.install wants to run 'chocolateyInstall.ps1'.
Note: If you don't run this script, the installation will fail.
Note: To confirm automatically next time, use '-y' or consider:
choco feature enable -n allowGlobalConfirmation
Do you want to run the script?([Y]es/[A]ll - yes to all/[N]o/[P]rint): Y

Ruby is going to be installed in 'C:\tools\ruby31'
Installing 64-bit ruby.install...
ruby.install has been installed.
  ruby.install can be automatically uninstalled.
Environment Vars (like PATH) have changed. Close/reopen your shell to
 see the changes (or in powershell/cmd.exe just type `refreshenv`).
 The install of ruby.install was successful.
  Software installed to 'C:\tools\ruby31\'

ruby v3.1.2.1 [Approved]
ruby package files install completed. Performing other installation steps.
 The install of ruby was successful.
  Software installed to 'C:\ProgramData\chocolatey\lib\ruby'

Chocolatey installed 2/2 packages.
 See the log for details (C:\ProgramData\chocolatey\logs\chocolatey.log).

c:\>
c:\>refreshenv
Refreshing environment variables from registry for cmd.exe. Please wait...Finished..

c:\>
c:\>ruby -v
ruby 3.1.2p20 (2022-04-12 revision 4491bb740a) [x64-mingw-ucrt]

c:\>
```

## asciidoctor (gem)のインストール

- Gemfileを用意し、適切なディレクトリに配置
    - https://docs.asciidoctor.org/asciidoctor/latest/install/ruby-packaging/#bundler
   
- Gemfileを配置したディレクトリに移動し、bundleコマンドを実行

```cmd
c:\>cd mywork
c:\mywork>bundle
Fetching gem metadata from https://rubygems.org/........
Resolving dependencies...
Using bundler 2.3.7
Fetching asciidoctor 2.0.17
Installing asciidoctor 2.0.17
Bundle complete! 1 Gemfile dependency, 2 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.

c:\mywork>
```

## 各種アプリのインストール
- 以下のブログで紹介されていたツールは入れておくことに
  - [Windows上のVisual Studio Codeで、AsciiDocのプレビュー環境の構築](https://tech.synapse.jp/entry/2019/06/03/110000)
- 各種アプリケーションのインストール（管理者権限で起動したコマンドプロンプト）
  - `choco install vscode -y`
  - `choco install graphviz -y`
  - `choco install correttojdk -y`


## rubyのモジュールインストール
- 以下のブログで紹介されていたモジュールは入れておくことに（最初のGemfileでまとめてしまってもよかったかも）
  - [Windows上のVisual Studio Codeで、AsciiDocのプレビュー環境の構築](https://tech.synapse.jp/entry/2019/06/03/110000)
- gemインストール（管理者権限で起動したコマンドプロンプト）
  - `gem install asciidoctor-diagram`
  - `gem install --pre asciidoctor-pdf`
  - ~~`gem install asciidoctor-pdf-cjk`~~
  - `gem install coderay`

## VSCode拡張機能のインストール
- 以下のブログで紹介されていたモジュールは入れておくことに
  - [Windows上のVisual Studio Codeで、AsciiDocのプレビュー環境の構築](https://tech.synapse.jp/entry/2019/06/03/110000)
- インストール（管理者権限で起動したコマンドプロンプト）
  - `code --install-extension joaompinto.asciidoctor-vscode`
  - `code --install-extension ms-ceintl.vscode-language-pack-ja`

## Visual Studio Codeの設定
### Asciidoc - Use_asciidoctor_jsのオフ、および、Use_asciidoctorpdfのオン
- 以下のブログの「Visual Studio Codeの設定」の対応を踏襲
  - [Windows上のVisual Studio Codeで、AsciiDocのプレビュー環境の構築](https://tech.synapse.jp/entry/2019/06/03/110000)
  - [Windows上のVisual Studio Codeで、AsciiDocからPDF出力](https://tech.synapse.jp/entry/2020/04/01/120000)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/270508/8a46f674-6b4e-5654-10cd-317ead3d0aa4.png)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/270508/e2037e74-aa38-ef0e-a8a2-0eb20febb222.png)


## Visual Studio Codeの動作確認
### プレビュー機能
- 以下のブログの「プレビュー」の対応を踏襲
  - [Windows上のVisual Studio Codeで、AsciiDocからPDF出力](https://tech.synapse.jp/entry/2020/04/01/120000) 
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/270508/f97b6077-8350-d90f-a9ea-390fd2e286bb.png)


## フォントの設定（PDF用）
カスタムフォントとして、今回はIBM Plexを利用します
  - https://www.ibm.com/plex/ 
  - https://www.itmedia.co.jp/news/articles/2107/30/news171.html

フォントの設定手順は以下が必要
  1. ttf のフォントを入手
  1. theme.ymlでフォントを指定
  1. asciidoctor-pdf の引数でスタイルファイルとフォントのディレクトリを指定しPDF生成

### ttfフォントの入手と配置
- 以下の「TrueType.zip」をダウンロードし、zipを展開
  - https://github.com/IBM/plex/releases/tag/v5.2.1
- 展開した「IBM-Plex-Sans-JP\hinted」フォルダーの中身を以下（2箇所）にコピー
  - C:\tools\ruby31\lib\ruby\gems\3.1.0\gems\asciidoctor-pdf-2.1.2\data\fonts 
  - 作業ディレクトリのサブディレクトリ（ `./IBMPlexSansJP` など）

### スタイルフォントでのフォント指定
- 下記の「default-theme.yml」ダウンロードしと作業ディレクトリへの配置
   - https://github.com/asciidoctor/asciidoctor-pdf/blob/main/data/themes/default-theme.yml
- 名前を「my-theme.yml」に編集
- ymlファイルを編集
    - [font]->[catalog]に追加のフォントを指定
        - [base]->[font_family]にcustom fontを指定

※[font]->[catalog]に追加のフォントを指定
```yml
font:
  catalog:
    # Noto Serif supports Latin, Latin-1 Supplement, Latin Extended-A, Greek, Cyrillic, Vietnamese & an assortment of symbols
    Noto Serif:
      normal: GEM_FONTS_DIR/notoserif-regular-subset.ttf
      bold: GEM_FONTS_DIR/notoserif-bold-subset.ttf
      italic: GEM_FONTS_DIR/notoserif-italic-subset.ttf
      bold_italic: GEM_FONTS_DIR/notoserif-bold_italic-subset.ttf
    # M+ 1mn supports ASCII and the circled numbers used for conums
    M+ 1mn:
      normal: GEM_FONTS_DIR/mplus1mn-regular-subset.ttf
      bold: GEM_FONTS_DIR/mplus1mn-bold-subset.ttf
      italic: GEM_FONTS_DIR/mplus1mn-italic-subset.ttf
      bold_italic: GEM_FONTS_DIR/mplus1mn-bold_italic-subset.ttf    
    # IBMPlexSansJP　-- custom font
    IBMPlexSansJP:
      normal: GEM_FONTS_DIR/IBMPlexSansJP-Regular.ttf
      bold: GEM_FONTS_DIR/IBMPlexSansJP-Bold.ttf
      italic: GEM_FONTS_DIR/IBMPlexSansJP-Light.ttf
      bold_italic: GEM_FONTS_DIR/IBMPlexSansJP-SemiBold.ttf
```

※[base]->[font_family]にcustom fontを指定


```yml
base:
  text_align: justify
  # color as hex string (leading # is optional)
  font_color: 333333
  # color as RGB array
  #font_color: [51, 51, 51]
  # color as CMYK array (approximated)
  #font_color: [0, 0, 0, 0.92]
  #font_color: [0, 0, 0, 92%]
#  font_family: Noto Serif
  font_family: IBMPlexSansJP
```

### PDF出力
- 作業ディレクトリで以下を実行（コマンドプロンプト）
  - このときのファイルの配置
    - `C:\mywork\faq.adoc`
    - `C:\mywork\my-theme.yml`
    - `C:\mywork\IBMPlexSansJP\IBMPlexSansJP-*.ttf`
 - コマンドについて
   - 参考：https://docs.asciidoctor.org/pdf-converter/latest/theme/custom-font/#configure-search-path
> asciidoctor-pdf -a pdf-theme=basic-theme.yml -a pdf-fontsdir=path/to/fonts document.adoc

※実行例
```cmd
C:\mywork> asciidoctor-pdf -a pdf-theme=my-theme.yml -a pdf-fontsdir=IBMPlexSansJP faq.adoc -o faq1.pdf

C:\mywork> 
```
- adocファイル
```adoc
# Asciidoc template

== はじめに

normal: ここに「はじめに」にあたる文章を書く。

// italicによる強調は「_」で囲む
italic: _ここに「はじめに」にあたる文章を書く。_

// boldによる強調は「*」で囲む
bold: *ここに「はじめに」にあたる文章を書く。*

// bold_italicによる強調は「*_」で囲む
bold_italic: *_ここに「はじめに」にあたる文章を書く。_*
```

- 生成されたPDF
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/270508/d5cb7b3b-7e7d-2b25-606c-95aff7818898.png)

- Italicになってない理由
    - 公式サイトに「ブラウザのようにフォントを動的にイタリック化できないため、テキストをイタリック化するにはイタリック体のスタイルが必要」とあります。
        - https://docs.asciidoctor.org/pdf-converter/latest/theme/custom-font/
>Asciidoctor PDF cannot italicize a font dynamically like a browser can, so the italic styles are required to italicize text. 

- IBM Plex SansのItalicはどこにある？？
  - 以下をみると、SansJPではなくてSansにはありそう 
    - https://fonts.adobe.com/fonts/ibm-plex-sans
 ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/270508/3b4008c3-1620-b947-6214-61716d44b31c.png)
 ![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/270508/3ea2bdc3-1baa-9d6f-03cc-f16cdaea3cdb.png)
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/270508/72a105a9-3152-e4c0-212e-2a514cfefd47.png)
 - 最近のリリースを参照し、v6.0.2のTrueType.zipをダウンロード
    - https://github.com/IBM/plex/releases
    - https://github.com/IBM/plex/releases/tag/v6.0.2
 - IBM-Plex-Sansには以下のファイルがあるが、IBM-Plex-SansJPには相当するものがない
    - IBMPlexSans-BoldItalic.ttf
    - IBMPlexSans-Italic.ttf
 - なので、、日本語でのItalic、BoldItalicは実装できないということになるのかな、、と理解。（上記のJPではないttfを指定してPDFを生成すると、日本語の場合は文字化けする）

# さいごに
とりあえずAsciidocを書けるように整えた状況ですが、本来の場合、チームでドキュメントを作成する場合、theme.ymlの設定や利用するttfファイルの統一など、もう少しルールの整備が必要になると理解しました。


以上。