AsciiDocで表を使って図を表現するのに困ったことを纏めみた

# はじめに #
- AsciiDocを使ってドキュメントを書く作業を担当するようになり、初めてAsciiDocに触れたので、書き方、表現の仕方に困った内容を纏めておきたく、投稿しております。
- 基本的な導入手順や設定などについては、ほかに投稿されている記事など有用な記載の情報が多いので、ここでは触れません。
- ここでは、私がこんな表現をしたい！を必要に駆られ、Qiitaをはじめサイト検索してたどり着いた結果を残していきます。

---
さっそくですが、Wordで書かれたマニュアルドキュメントをAsciiDocに置き換える作業をしていました。
Word → AsciiDocにするコマンドもあるようですが、今回は画像の差し替えや、文章の見直し込みだったので、移植できるところをちまちまコピーしながら実施していました。
その中で、表現に困った内容を纏めておきたいと思います。

# 困っていたこと #
- 表の中に複数の画像を挿入すること
- 一つのセルに複数の画像を入れること

# 解決方法 #
- 表の中に複数の画像を挿入すること
<br>Wordでは、こんな感じの図を含めた表で表現されていました。
<br>　　<img width="40%" alt="代替テキスト" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2518581/ca7fc31e-cad8-2264-895f-46d64618bb1a.png">
<br>実際、こんな感じの図表であれば、
<br>　　<img width="40%" alt="代替テキスト" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2518581/c742dd70-db76-640d-ffbb-22c86f01a21c.png">
<br>`cols`の対象の列に`a`を指定して書いてみると

```
[cols="1,2a", width=70%]
|===
^|地方名 ^|地図 
^|東北地方 ^|image::tohoku.png["東北地方","30%"]
^|関東地方 ^|image::kanto.png["関東地方","30%"]
|===
```

<br>　こんな感じでうまくいった。（ググって出てきた表で画像を扱う方法の通りだった。）
<br>　　　<img width="40%" alt="代替テキスト" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2518581/9cb4e74b-cad8-a814-efd9-0cbc7aeed6ce.png">
<br>　同じように、書けるんじゃないか？ということで、
　こう書いてみた

```
[cols="1,2a", width=70%]
|===
^|地方名 ^|地図 
^|東北地方 ^|image::tohoku.png["東北地方","30%"]
^|関東地方 ^|image::kanto.png["関東地方","30%"]
|===
```

<br>　結果は、解釈してくれず、下図のようになった。
　　<img width="40%" alt="代替テキスト" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2518581/e09d4943-dd04-d5f2-931a-a5bee5806ebc.png">
<br>　で、思った。
　セルに対してAsciiDocの画像を表現したいという命令が聞いていないのかなと・・・。
　そこで、改めてセルに対して、`a`を付与してみた。

```
[cols="2,2,3a", width=70%]
|===
^|地方 ^|都道府県 ^|地図 
.3+|関東地方 ^|埼玉県 ^|image::tohoku.png["埼玉県","30%"]
^|東京都 ^a|image::kanto.png["東京都","30%"]
^|神奈川県 ^a|image::kanto.png["神奈川県","30%"]
|===
```

<br>　と書いてみたら、あら不思議。表現できた。 完成！！！
<br>　　　<img width="40%" alt="代替テキスト" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2518581/b0c0de10-b6b6-753c-1235-08c5838a92bc.png">  


- 一つのセルに複数の画像を入れること
<br>　次に出てきたのが、こんな感じの図表だった。
<br>　　　<img width="40%" alt="代替テキスト" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2518581/777500f8-9b55-6d18-0ea9-d107ceba50ff.png">
<br>　素直に、セルの中に画像を2つ入れられるんじゃないか？と、ここはひとつ、素直に書いてみた。

```
[cols="1,5a", width=75%]
|===
^|季節 ^|季節を代表する野菜
^|春 |キャベツ： +
image::cabbage.png["キャベツ", 20%] +
|===
```

<br>　が、画像一つを入れたが、こうなった。
　どうやら、文字列が画像より前にあるとうまく画像を差し込めないらしい😓
<br>　　　<img width="40%" alt="代替テキスト" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2518581/9cf8a3e0-f347-42e1-4b1c-c847b2898e2a.png">
<br>　どうするか、思案して思いついた。
<br>　表の中、表を作った表の中に入れれば、入るんじゃ…💦 やってみよう！ 
　・・・ そもそも、表の中に表を入れる？
　`|`(パイプ)ではなく、`!`(エクステンション)で表現すると書けるらしい。

```
[cols="1,5a",width=75%]
|===
^|季節 ^|季節を代表する野菜
^|春|キャベツ：
[cols="1"]
!===
!
!===
|===
```

<br>　セルの中に表を作成することができた。
　　<img width="40%" alt="代替テキスト" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2518581/ccc7ba01-35f6-b2b7-b9ee-ce39b56f5f60.png">
<br>　「キャベツ：」をセル内の表の外に書いたけど、これも全部セル内の表に入れてしまえば、バランスよくなる？と思いつつ、画像を入れてみようと、こう書いた。

```
[cols="1,5a",width=75%]
|===
^|季節 ^|季節を代表する野菜
^|春| //キャベツ：
[cols="a"]
!===
!キャベツ：
!image::cabbage.png["キャベツ", 20%]
!アスパラガス：
!image::asparagus.png["アスパラガス", 20%]
!===
|===
```

　いい感じに表現できた。
　　<img width="40%" alt="" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2518581/8a1a72c8-152f-c604-4e30-d28e310cbf0a.png">
　あとは、罫線がなければ、それっぽくなるな！
　ということで、`frame`と`grid`を`none`に指定すれば、こんな感じで書いて

```
[cols="1,5a",width=75%]
|===
^|季節 ^|季節を代表する野菜
^|春| //キャベツ：
[cols="a", frame="none", grid="none"]
!===
!キャベツ：
!image::cabbage.png["キャベツ", 20%]
!アスパラガス：
!image::asparagus.png["アスパラガス", 20%]
!===
|===
```

　最終形態は、こんな感じになりました。
　　<img width="40%" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2518581/d5a82743-c045-3654-3e23-58e8403903d9.png">


#最後に#
今まで、ググるとQiitaの記事にたどり着くことが多い。
ここに自分でも何か投稿できないかな？と思い、初めて投稿してみました。
実現した方法以外にも実現方法はあるのかもしれませんが、調べた結果をメモ的な感じで残したものになります。
拙い表現かもしれませんがご容赦を
今後も、自分のメモ的な感じで投稿していきたいと思いますが、
残すための文章を書くのがこれほどに大変とは。。