AsciiDoc入門

AsciiDocとは

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

利用例

• Pro Git book - Github
• オライリーの書籍
  • Clojure Cookbook - Github
  • Programming Scala
  • Mastering Bitcoin - Github
  • Open Government - Github
• O’Reilly Atlas
• Neo4j documentation - Github
• Git User's Manual

なぜAsciiDocを使うのか

表現力と可読性

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

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

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

言語	用途
XML	技術文書(DocBook, DITA)
HTML	Web・電子書籍(EPUB,HTMLBook)
AsciiDoc	メモ・技術文書
GitHub Flavored Markdown	メモ(プログラマー)
Markdown	メモ

Markdownの欠点

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

AsciiDocの利点

• Markdownと同等の可読性で、表現力が高い。
• 記法を拡張する方法が言語仕様に定められている。

AsciiDocの欠点

• Markdownに比べ普及していない。

記法

ここではAsciiDocの記法の一部を紹介する。
より詳しく知るにはAsciiDoc cheatsheetや公式サイトを参照。

セクションタイトル

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

line1 +
line2

line1
line2

テキスト修飾

書式	表示
*bold*	bold
_italic_	italic
`monospace`	monospace
X^2^	X2
X~2~	X2
[red]#赤色#	赤色
[underline]#下線#
[line-through]#取り消し線#	取り消し線
// コメント

リンク

asciidoc

http://asciidoctor.org/[リンク]

リンク

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

asciidoc

ホニャララ http://asciidoctor.org/[Asciidoctor]
ホニャララlink:http://asciidoctor.org/[Asciidoctor]

ホニャララ Asciidoctor
ホニャララAsciidoctor

画像

asciidoc

image::https://via.placeholder.com/350x150[代替テキスト]

リスト

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

. Step 1
. Step 2
.. Step 2a
.. Step 2b
. Step 3

1. Step 1
2. Step 2
   a. Step 2a
   b. Step 2b
3. Step 3

asciidoc

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

CPU

コンピューターの中心的な処理装置

RAM

読み書き可能な主記憶装置

SSD

フラッシュメモリを使用した補助記憶装置

キーボード

キーを押すことで信号を送信する入力装置

マウス

コンピューターのポインティングデバイス

モニター

映像を表示する出力装置

コードブロック

asciidoc

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

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

引用

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）は、人間がシンプルなテキストエディタを使っての入力が容易になるように設計された、簡潔な文法をもつマークアップ言語である。
____

テーブル

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

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

1	2	3	4
a	b	c	d
A	B	C	D

パススルー

asciidoc

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

亜米利加（アメリカ）

外部ファイルの読み込み

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

asciidoc

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

test.py

num1 = 1.1
num2 = 3.9

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

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

エディター

名前	種類	備考
Asciidoc FX	オフライン	HTML,PDF,Mobi,Epub,DocBookの出力が可能
AsciiDoc	オフライン	VS Code のプラグイン
AsciiDoc Tiny Editor	オンライン
DocGist	オンライン	ネットに公開可能
AsciiDocLIVE	オンライン
Coding Ground	オンライン

参考文献

• 軽量マークアップ言語記法の比較
• Wikipedia:Lightweight markup language
• Atlas:AsciiDoc 101