
:icons: font
= AsciiDocのインストールまとめ  [small]#2020/2/4#
:sectnums:
:sectnumlevels: 5
:experimental:
// // :module:    モジュール名
// :Author:    著者名
// :Email:     メールアドレス
// :Date:      日付(2020/01/20)
// :Revision:  Rev.1
// :lang: ja
// :doctype: book
// :description:
// :docname: ドキュメント名

// // 見出し設定
// :sectnums:
// :chapter-label: 
// // 目次作成
:toc: left
// :toclevels: 3
// // ラベルの日本語設定
// :toc-title: 目次
// :preface-title: はじめに/まえがき
// :appendix-caption: 付録
// :caution-caption: 注意
// :example-caption: 例
:figure-caption: 図
// :important-caption: 重要
// :last-update-label: 最終更新
// :listing-caption: リスト
// :manname-title: 名前
// :note-caption: 注記
// :table-caption: 表
// :tip-caption: ヒント
// :toc-title: 目次
// :untitled-label: 無題
// :version-label: バージョン
// :warning-caption: 警告
.[big]#概要#
[%hardbreaks]
もっとも簡単な方法を説明する。
Asciidocの記述およびPlantUML記述可能になります。
おそらくVisualStudioCodeのインストール含めて５分程度で完了するでしょう。
[IMPORTANT]
--
[%hardbreaks]
[yellow-background]## 外部に漏れてはいけないUML図を使用しないでください ##
PlantUMLの記述を行った場合に外部のサーバー  https://kroki.io へアクセスしてレンダリングされてしまいます。
(kiroki.io: 各種ダイアグラムをレンダリングするOSSサービスサイトです)
--

== VisualStudioCodeへのインストール

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

https://code.visualstudio.com[省略します]

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

. 拡張機能を開いて、[AsciiDoc]で検索
. 下図のアイコンのAsciiDocを選択して kbd:[Install]をクリックする （これだけ）

image::instAsciiDocExtend.JPG[instExtADoc,700,700,title=ADoc拡張]

=== 初期設定の変更箇所
[%hardbreaks]
AsciiDocの初期パラメータを調整

* メニューからmenu:File[Preference,Setting]を選択
* `Search Strings` に `AsciiDoc` と入力。AsciiDoc関連のパラメータが表示されるので以下のパラメータを変更する
1. menu:asciidoc[preview.useEditorStyle]:false (プレビューの背景を白)
2. menu:asciidoc[use_kroki]:  true （UML図が描画できる、ただし外部サーバー)
3. menu:asciidoc[use_asciidoctor_js]: true （ここは固定である）
4. menu:asciidoc[use_asciidoctorpdf]: false（ここは固定である）

★念のためvscodeを再起動


=== 確認方法 

* 添付の `SampleADocAndUML.adoc` の表示結果が `SampleADocAndUML.html` の表示出力結果と同じかどうか確認してください
（チェット違うけどね...)

* vscodeで``SampleADocAndUML.adoc``を開き、kbd:[Cntl+K]、 kbd:[Cntl]を離してkbd:[V] でプレビュー表示される

== Chromeブラウザへのインストール(ブラウズ専用)
ChromeにAsciiDoc拡張機能(Asciidoctor.js Live Preview)をインストールする

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

2. btn:[chromeに追加] ボタンを選択
3. menu:Chrome[その他ツール,拡張機能]を選択
4. btn:[Asciidoctor.js Live Preview]内の kbd:[詳細]を選択。OFFならONにする
5. ファイルURLへのアクセスを許可するをkbd:[有効]にします
+
image::instChromeAsciiDoc.jpg[a,600,100,align=center]

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

=== 確認方法 

* vscodeと同じデータで確認を。

== 以下古いもの （もうやらなくてよい。うまく動かない）

AsciiDocをPlantUML,Mermaid.jsを含めてインストールするものを説明する

. javaのインストール ( for PlantUML)
. node.jsのインストール  (v10.16.0 ok)
. rubyのインストール
+
....
https://rubyinstaller.org/downloads/
Ruby 2.6.3-1 (x64)
		1 - 'MSYS2 base installation'でインスト　に何度も失敗
		※１０回ぐらいで成功（msys2-x86_64-20180531.exe）
....

. asciidoctor/diagram/pahtomjs/mermaid/mermaid.cliのインストール 
+
....
コマンドラインで以下を実行する
	gem install asciidoctor
	gem install asciidoctor-diagram
	gem install --pre asciidoctor-pdf
	---
	npm install -g phantomjs
	npm install -g mermaid
	npm install -g mermaid.cli
....
. vs code  拡張機能:  `joaompinto.asciidoctor-vscode`

	.. インストール
+
	拡張機能タブから、"AsciiDoc"を検索してインストールする。
	以下でもよい:
	Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter:
	ext install joaompinto.asciidoctor-vscode
+
	.. ショートカット
+
	Toggle Preview - ctrl+shift+v (Mac: cmd+shift+v)
	Open Preview to the Side - ctrl+k v (Mac: cmd+k v)
	View symbols - go to symbol action - ctrl+shift+o, select a heading.

. vscodeの追加設定
+
PlantUML,mermaid.jsをプレビューするには以下の設定を行う
[source,json]
....
"asciidoc.asciidoctor_command":"asciidoctor -a outdir=tmp -a imagesdir=tmp -a imagesoutdir=tmp -r asciidoctor-diagram -o-"
"asciidoc.use_asciidoctor_js": false
....


CAUTION: ★ mermaidプレビュー不正の確認と修正

marmaidの表示でpantomjs(chronimun)を利用するが、描画できないときがある。以下のようなメッセージ：
----
Failed to generate image: C:\Users\<UserID>\AppData\Roaming\npm/mmdc.CMD failed: (node:6884) UnhandledPromiseRejectionWarning: Error: Failed to launch chrome!
TROUBLESHOOTING: https://github.com/GoogleChrome/puppeteer/blob/master/docs/troubleshooting.md
----

chromeとの非互換がある様子。
TROUBLESHOOTINGより、以下：
----
    const browser = await puppeteer.launch({
      ignoreDefaultArgs: ['--disable-extensions'],
    });
----

mermaidの起動を変更するには、mmdcコマンドに上記のオプションを追加して起動が必要。configファイルを作成して呼び出す(2step) +
C:\Users\<UserID>\AppData\Roaming\npm\node_modules\mermaid.cli\node_modules\puppeteer\readme.md を参考にmmdcの起動オプションを追加する

場所は、C:\Users\<UserID>\AppData\Roaming\npm　直下

. puppeteerのconfigファイルを作成 + 
p-config.json:
+
[source,json]
----
    {
      "ignoreDefaultArgs": ["--disable-extensions"]
    }
----

. mmdc.cmdファイルに追記
+
mmdc.cmd:
[source]
----
@SET CONF_OPT=-p "%~dp0\p-config.json" 
@IF EXIST "%~dp0\node.exe" (
  "%~dp0\node.exe"  "%~dp0\node_modules\mermaid.cli\index.bundle.js" %CONF_OPT% %*
) ELSE (
  @SETLOCAL
  @SET PATHEXT=%PATHEXT:;.JS;=;%
  node  "%~dp0\node_modules\mermaid.cli\index.bundle.js" %CONF_OPT% %*
)
----

. テスト
+
以下でpngファイルが作成できればOK +
mmdc -i <mmdファイル> -o test.png

== AsciiDocの使い方 ==

...

== もう一度インストール確認  [small]#2019/12/17#


https://qiita.com/shiro01/items/fb93e91a8424e1c4a556

https://qiita.com/shiro01/items/a300b6d5b572a314ce5e

https://qiita.com/hyt126/items/fdeff36f09bb221dfac0

asciidoctor-pdfで日本語が化ける件は以下です
https://qiita.com/hidao/items/f8a94a9ced332606c67f

C:\Ruby26-x64\lib\ruby\gems\2.6.0\gems\asciidoctor-pdf-1.5.0.beta.8\data\themes
default-with-fallback-font-theme.yml
の内容を
default-theme.yml
に転記すればよい。

■MacBookAirのバージョンを再インストールしたら動いた
★javaのネットワークアクセスが関係している様子。

>gem list ascii*
*** LOCAL GEMS ***
Ascii85 (1.0.3)
asciidoctor (2.0.10)
asciidoctor-diagram (1.5.18)
asciidoctor-pdf (1.5.0.alpha.18)
asciidoctor-pdf-cjk (0.1.3)

.gem unistall 管理者権限で
gem unistall asciidoctor -v '2.0.10'
のようにバージョンを指定してアンインストールする

.gem install 管理者権限でバージョンを指定する
gem install asciidoctor -v '2.0.10'
gem install asciidoctor-diagram -v '1.5.18'
gem install asciidoctor-pdf -v '1.5.0.alpha.18'
gem install asciidoctor-pdf-cjk -v '0.1.3'


.もう一度最新版をインストールする →　結局だめ、UMLがあるとなぜか止まる
	最新版は以下：
	asciidoctor (2.0.10)
	asciidoctor-diagram (2.0.0)
	asciidoctor-pdf (1.5.0.beta.8)
	asciidoctor-pdf-cjk (0.1.3)
　　おそらく「asciidoctor-pdf (1.5.0.beta.8)」がおかしい
　
→　MacbookAirと同じバージョンをインストールしておわり。

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


.Graphvizのインストールは必要です。パスの設定も

もうしんどいから、見ない。。。（END)



