AsciiDoc入門

## AsciiDocとは

AsciiDocはMarkdownなどのような軽量マークアップ言語の一つです。

### 利用例

* [Pro Git book](http://git-scm.com/book/ja/v2) - [Github](https://github.com/progit/progit2-ja)
* オライリーの書籍
  * [Clojure Cookbook](http://clojure-cookbook.com/) - [Github](https://github.com/clojure-cookbook/clojure-cookbook)
  * [Programming Scala](http://shop.oreilly.com/product/9780596155964.do)
  * [Mastering Bitcoin](http://chimera.labs.oreilly.com/books/1234000001802) - [Github](https://github.com/aantonop/bitcoinbook)
  * [Open Government](http://chimera.labs.oreilly.com/books/1234000000774/index.html) - [Github](https://github.com/oreillymedia/open_government)
* [O’Reilly Atlas](http://docs.atlas.oreilly.com/writing_in_asciidoc.html)
* [Neo4j documentation](http://neo4j.com/docs/stable/) - [Github](https://github.com/neo4j/neo4j-documentation/tree/3.4/contents/src)
* [Git User's Manual](http://www.kernel.org/pub/software/scm/git/docs/user-manual.html)

## <i class="fa fa-question-circle"></i> なぜAsciiDocを使うのか

### <i class="fa fa-search"></i> 表現力と可読性

技術文書を書く場合HTMLは汎用性が高いが可読性が低い、一方Markdownは可読性が高いがテーブル記法がないなど表現力が乏しい。

AsciiDocは可読性が高く表現力もある程度高いので、技術文書等を書くには最適である。

- 表現力：HTML > AsciiDoc > Markdown
- 可読性：AsciiDoc ≒ Markdown > HTML

|言語|用途|
|:-----------------------:|:----------------:|
|XML|技術文書([DocBook](https://ja.wikipedia.org/wiki/DocBook), [DITA](https://dita-jp.org/webhelp-feedback/#preface.html))|
|HTML                     | Web・電子書籍([EPUB](http://imagedrive.github.io/spec/),[HTMLBook](http://oreillymedia.github.io/HTMLBook/)) |
|AsciiDoc                 | メモ・技術文書     |
|GitHub Flavored Markdown | メモ(プログラマー) |
|Markdown                 | メモ              |

### <i class="fa fa-thumbs-o-down"></i> Markdownの欠点

- 記法を拡張する方法が言語仕様に定められていないため、方言が乱立している。その結果、互換性のないものとなっている。
- HTMLのタグを使うことで拡張できるが、可読性が低くなる。

### <i class="fa fa-thumbs-o-up"></i> AsciiDocの利点
- Markdownと同等の可読性で、表現力が高い。
- 記法を拡張する方法が言語仕様に定められている。

### <i class="fa fa-thumbs-o-down"></i> AsciiDocの欠点
- Markdownに比べ普及していない。

## <i class="fa fa-pencil-square-o"></i> 記法
ここではAsciiDocの記法の一部を紹介する。
より詳しく知るには[AsciiDoc cheatsheet](https://powerman.name/doc/asciidoc)や[公式サイト](https://asciidoc-py.github.io/)を参照。

### セクションタイトル

```asciidoc:asciidoc
= Document Title (Level 0)

== Level 1 Section Title

=== Level 2 Section Title

==== Level 3 Section Title

===== Level 4 Section Title

```
> # Document Title (Level 0)
> ## Level 1 Section Title
> ### Level 2 Section Title
> #### Level 3 Section Title
> ##### Level 4 Section Title

### 改行

```asciidoc:asciidoc
line1 +
line2
```
> line1
> line2

### テキスト修飾

|書式|表示|
|:-----------------------:|:----------------:|
|`*bold*`                 |**bold**          |
|`_italic_`               |*italic*          |
|<code>\`monospace\`</code>| `monospace`     |
|X^2^ |X<sup>2</sup> |
|X~2~ |X<sub>2</sub> |
|[red]#赤色#| <font color='red'>赤色</font> |
|[underline]#下線# | ![21f89c157c6f08dcc86c881234dbaed6.png](https://qiita-image-store.s3.amazonaws.com/0/8757/a72c0861-9635-1f33-5a72-a5dd6050f3d0.png) |
|[line-through]#取り消し線# | <del>取り消し線</del> |
|// コメント| |

### リンク

```asciidoc:asciidoc
http://asciidoctor.org/[リンク]
```
> [リンク](http://asciidoctor.org/)

※ 行頭にリンクを書かない場合は、URLの前に空白文字または`link:`が必要です。

```asciidoc:asciidoc
ホニャララ http://asciidoctor.org/[Asciidoctor]
ホニャララlink:http://asciidoctor.org/[Asciidoctor]
```
> ホニャララ [Asciidoctor](http://asciidoctor.org/)
> ホニャララ[Asciidoctor](http://asciidoctor.org/)

### 画像

```asciidoc:asciidoc
image::https://via.placeholder.com/350x150[代替テキスト]
```
> ![代替テキスト](https://via.placeholder.com/350x150)

### リスト

```asciidoc:asciidoc
* level 1
** level 2
*** level 3
**** level 4
***** level 5
* level 1
```
> * level 1
>  * level 2
>      * level 3
>          * level 4
>              * level 5
> * level 1

```asciidoc:asciidoc
. Step 1
. Step 2
.. Step 2a
.. Step 2b
. Step 3
```

> 1. Step 1
> 2. Step 2  
> a. Step 2a  
> b. Step 2b  
> 5. Step 3

```asciidoc:asciidoc
CPU:: コンピューターの中心的な処理装置
RAM:: 読み書き可能な主記憶装置
SSD:: フラッシュメモリを使用した補助記憶装置
キーボード:: キーを押すことで信号を送信する入力装置
マウス:: コンピューターのポインティングデバイス
モニター:: 映像を表示する出力装置
```

>
<dl>
<dt>CPU</dt>
<dd>コンピューターの中心的な処理装置</dd>
<dt>RAM</dt>
<dd>読み書き可能な主記憶装置</dd>
<dt>SSD</dt>
<dd>フラッシュメモリを使用した補助記憶装置</dd>
<dt>キーボード</dt>
<dd>キーを押すことで信号を送信する入力装置</dd>
<dt>マウス</dt>
<dd>コンピューターのポインティングデバイス</dd>
<dt>モニター</dt>
<dd>映像を表示する出力装置</dd>
</dl>

### コードブロック

```asciidoc:asciidoc
[source, rust]
----
fn main() {
    println!("Hello World!");
}
----
```

> ```rust
>fn main() {
>    println!("Hello World!");
>}
> ```

### 引用

```asciidoc:asciidoc
[quote, 'https://ja.wikipedia.org/wiki/%E8%BB%BD%E9%87%8F%E3%83%9E%E3%83%BC%E3%82%AF%E3%82%A2%E3%83%83%E3%83%97%E8%A8%80%E8%AA%9E[Wikipedia:軽量マークアップ言語]']
____
軽量マークアップ言語（けいりょうマークアップげんご、英語: lightweight markup language）は、人間がシンプルなテキストエディタを使っての入力が容易になるように設計された、簡潔な文法をもつマークアップ言語である。
____
```
>![86cf04ffd67757cf173ebdaa891b4f9b.png](https://qiita-image-store.s3.amazonaws.com/0/8757/a1721b7c-ccad-353d-f7e4-1014996e45f2.png)

### テーブル

```asciidoc:asciidoc
.テーブルタイトル
[options="header"]
|=======================
|Col 1|Col 2      |Col 3
|1    |Item 1     |a
|2    |Item 2     |b
|3    |Item 3     |c
|=======================
```

> Table 1. テーブルタイトル

> |Col 1|Col 2|Col 3
> |:---:|:---:|:---:|
> |1    |Item 1 |a
> |2    |Item 2 |b
> |3    |Item 3 |c

```asciidoc:asciidoc
[format="csv"]
|======
1,2,3,4
a,b,c,d
A,B,C,D
|======
```

>
<table>
  <tr>
    <td>1</td>
    <td>2</td>
    <td>3</td>
    <td>4</td>
  </tr>
  <tr>
    <td>a</td>
    <td>b</td>
    <td>c</td>
    <td>d</td>
  </tr>
  <tr>
    <td>A</td>
    <td>B</td>
    <td>C</td>
    <td>D</td>
  </tr>
</table>

### パススルー

```asciidoc:asciidoc
++++
<ruby>
  <rb>亜米利加</rb>
  <rp>（</rp>
  <rt> アメリカ</rt>
  <rp> ）</rp>
</ruby>
++++
```

> <ruby><rb>亜米利加</rb><rp>（</rp><rt>アメリカ</rt><rp>）</rp></ruby>

### 外部ファイルの読み込み

外部ファイル`test.py`の4～5行目を読み込んで表示する

```asciidoc:asciidoc
[source, python]
----
include::test.py[lines=4..5]
----
```

```py3:test.py
num1 = 1.1
num2 = 3.9

sum = float(num1) + float(num2)
print('{0} + {1} = {2}'.format(num1, num2, sum))
```

> ```py3
> sum = float(num1) + float(num2)
> print('{0} + {1} = {2}'.format(num1, num2, sum))
> ```

## <i class="fa fa-cubes"></i> エディター

| 名前 | 種類 | 備考 |
|:---:|:---:|:---:|
| [Asciidoc FX](https://github.com/asciidocfx/AsciidocFX) | オフライン | HTML,PDF,Mobi,Epub,DocBookの出力が可能 |
|[AsciiDoc](https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode)| オフライン | [VS Code](https://code.visualstudio.com/) のプラグイン |
| [AsciiDoc Tiny Editor](https://yamanee.info/adt_editor/)  | オンライン | |
| [DocGist](http://gist.asciidoctor.org/) | オンライン | ネットに公開可能 |
| [AsciiDocLIVE](https://asciidoclive.com/) | オンライン | |
| [Coding Ground](http://www.tutorialspoint.com/try_asciidoc_online.php) | オンライン  |

## <i class="fa fa-book"></i> 参考文献

- [軽量マークアップ言語記法の比較](http://hyperpolyglot.org/lightweight-markup)
- [Wikipedia:Lightweight markup language](https://en.wikipedia.org/wiki/Lightweight_markup_language)
- [Atlas:AsciiDoc 101](http://chimera.labs.oreilly.com/books/1230000000065/ch04.html)