// :experimental:
// :lang: ja
// :icons: font
// :sectnums:
// :sectnumlevels: 5
// :experimental:
// :figure-caption: 図


:lang: ja
include::config.adoc[]
:toc: left

// マクロ
// :image-root-dir: ./
// :image-root-dir: ..\
:imagesdir: Images

= AsciiDocのインストールまとめ rev3 [small]#[2020/12/25]#

.[big]#概要#
[%hardbreaks]
AsciiDocの編集及びプレビュー表示を可能にする環境の構築方法について記述する。
情報は、2020/5/18現在のものとする。

== Visual Studio Code上での編集/プレビュー環境構築

=== VSCode自身のインストール

https://code.visualstudio.com/download/[ココ] (VSCodeのサイト) からダウンロード、インストールする。

[title="",caption="",cols="a,2a",frame="none",grid="all"]
|====
|
// 左
image::UserOrSystem.png[VSCode Installer, 58%]
|
// 右
ダウンロードページには、User InstallerとSystem Installerとが用意されているが、それぞれ以下の通り。

- User Installer：そのユーザーのみにインストール

- System Installer：全ユーザーにインストール(管理者権限が必要) 

どちらを選んでもアプリケーションそのものの違いはない。
|====

=== 拡張機能のインストール

==== AsciiDoc
VSCodeにAsciiDoc拡張機能をインストールする。

. kbd:[Control+Shift+X] を押下 (または下図左下のアイコンをクリック)
. 拡張機能の検索窓に *AsciiDoc* と入力
. 下図のアイコンのAsciiDocを選択して *Install* をクリック


image::instAsciiDocExtend.JPG[instExtADoc,title=AsciiDoc拡張, 50%]

==== VSCodeの日本語化 (※任意)
VSCodeのメニューを日本語にする。AsciiDocに直接の関係はないので任意。

. kbd:[Control+Shift+X] を押下
. 拡張機能の検索窓に *Japanese* と入力
. "Japanese Language Pack for Visual Studio Code"(発行者:Microsoft) を選択して *Install* をクリック


=== 初期設定の変更箇所
[%hardbreaks]
AsciiDocの初期パラメータを調整する。
※日本語化していたら、適宜読み替えのこと。

* kbd:[Control + ,] を押下 (または、メニューからmenu:File[Preference,Setting]を選択)
* `Search Strings` に `AsciiDoc` と入力。AsciiDoc関連のパラメータが表示されるので以下のパラメータを変更
. menu:asciidoc[preview: Use Editor Style]: チェックOFF (プレビューの背景を白)
. menu:asciidoc[Use_kroki]: チェックON（UML図が描画できる、ただし外部サーバーに接続される)
. menu:asciidoc[Use_asciidoctor_js]: チェックON
. menu:asciidoc[Use_asciidoctorpdf]: チェックOFF

* 本設定を行ったタブを閉じた後、VSCodeを再起動

[[check_vs]]
=== 確認方法 

添付の `SampleADocAndUML.adoc` のプレビュー表示結果が `SampleADocAndUML.html` の表示出力結果と(ほぼ)同じかどうか確認する。 +
プレビューは、VSCodeで``SampleADocAndUML.adoc``を開いた後、『kbd:[Cntl+K]、 kbd:[Cntl]を離してkbd:[V]』または『ウインドウ右上のアイコンimage:IconPreview.png[IconPreview]を押下』すると、右側に表示される。

== Chrome上でのプレビュー環境構築

=== 拡張機能のインストール

ChromeにAsciiDoc拡張機能(Asciidoctor.js Live Preview)をインストールする。

. https://chrome.google.com/webstore/detail/asciidoctorjs-live-previe/iaalpfgpbocpdfblpnhhgllgbdbchmia[Asciidoctor.js Live Preview] を開く

. btn:[chromeに追加] ボタンを選択
. menu:Chromeのウィンドウ[その他のツール(右上の縦3点リーダ),拡張機能]を選択
. btn:[Asciidoctor.js Live Preview]の kbd:[詳細]を選択。OFFならONに変更
. ファイルURLへのアクセスを許可するをkbd:[有効]に
+
image::instChromeAsciiDoc.JPG[a,align=center, 50%]

. kbd:[拡張機能のオプション]を選択して以下を設定
[number]
	.. toc=left	(目次を右につける)
	.. Enable the diagrams extension	(UMLを使う)
+
image::ex1.JPG[a, align=center, 50%]
image::ex2.JPG[a, align=center, 50%]

=== 確認方法 

添付の `SampleADocAndUML.adoc` をChrome上にドラッグ&ドロップして表示されるプレビュー結果が `SampleADocAndUML.html` の表示出力結果と(ほぼ)同じかどうか確認する。

== 別形式でのファイル出力

=== HTML出力

開いている$$.$$adocファイルと同じフォルダに、同名の$$.$$htmlファイルとして保存する。上書き保存されるので注意。

. $$.$$adocファイルを開く
. kbd:[Control+Shift+p]を押下
. $$>$$ の横に "AsciiDoc: Save HTML document" と入力、kbd:[Enter]を押下

== その他

詳細は割愛した事項を以下に記す。

=== PDF出力

AsciiDoctorが必要。また、AsciiDoctorをインストールするには、Rubyが必要 (gemパッケージとして配布されているため)。

- AsciiDoctorをインストールするには、Rubyをインストールした後、以下のコマンドでOK。 +

    gem install asciidoctor
    gem install asciidoctor-pdf

- 出力するには、VSCodeの設定で menu:asciidoc[Use_asciidoctorpdf]: false とした後、kbd:[Control+Shift+p] → "AsciiDoc: Export document as PDF" とすれば保存できる。

ただし、日本語が化けるので、default-themes.yml にフォントの情報を追記しなければならない。

=== PlantUML

VSCodeの拡張機能における設定で、menu:asciidoc[use_kroki]: true とした場合、
PlantUMLの記述を行うと、レンダリングのため https://kroki.io にアクセスしてしまう。そのため、外部に漏れてはいけないUML図を記述できない。

ローカルでレンダリングする(外部に接続しないようにする)には、次のようにすればよい。

- asciidoctor-diagramをインストール。

    gem install asciidoctor-diagram

- VSCodeの設定を次のように変更。

    "asciidoc.asciidoctor_command":"asciidoctor -r asciidoctor-diagram"
    "asciidoc.use_asciidoctor_js": false

ただし、これだと$$.adoc$$と同じ場所に画像ファイルが沢山できてしまうので、

[source,json]
....
"asciidoctor -r asciidoctor-diagram -a outdir=.asciidoctor -a imagesdir=.asciidoctor -a imagesoutdir=.asciidoctor" 
....
のようにしておくとよい。

また、諸々のUML図を描画するなら、おそらく Graphviz のインストールも必要。

以上