はじめに
Asciidoc は簡単な書式で記述したテキストファイルを HTML など さまざまなフォーマットに整形することができるツールです。
Asciidoc はテキストを単に整形するだけでなく、 外部ファイルやシェルの実行結果を読み込んだり、 CSVの内容を取り込んで表にすることができるなど 多彩な機能を持っていてます。
この資料はAsciidocの使い方について説明したものです。
Asciidoc について
Asciidoc はニュージーランドのStuart Rackham氏により、 2002年から開発が始まったPython で動作する文書整形ツールです。[1] 10年以上の間いろいろな機能拡張されてきました。
私も2008年に Graphviz に対応するためのパッチを提供していて、 2009年の asciidoc-8.3.2 からマージされています。
Asciidoc が非常に便利なところは、 バックエンドの整形ツールを選ぶことで、 同じテキストを HTML, PDF, EPUB など多彩なフォーマットに変換できることです。
インストール
ソースコードやコンパイル済みのバイナリを それぞれのディストリビューション向けにパッケージしたものは、 次のURLから参照することができます。
RedHat Enterprise Linux 6 (RHEL6) や CentoS 6 の場合であれば、 次のようにインストールすることができます。
# BASEURL=http://pkgs.repoforge.org/asciidoc
# rpm -ivh ${BASEURL}/asciidoc-8.6.9-1.el6.rfx.noarch.rpm
Mac の場合でもコンパイル済みのバイナリが MacPorts [2]から配布されていますので、 次のようにインストールすることができます。
$ sudo port install asciidoc
Windows の場合は、Cygwin という Linux エミュレータを インストールすることで利用できるようになります。[3] 意外に知られていませんが、 Red Hat も Cygwin をリリースしていて無料で使うことができます。[4]
Asciidoc のインストールは Cygwin のセットアップツールから選ぶことで インストールすることがでいます。[5]
また、Cygwin に apt-cyg [6] をインストール設定済みであれば、 次のようにコマンドラインでインストールすることができます。
# apt-cyg install asciidoc
Asciidoc の使い方
詳細な使用方法は Asciidoc ユーザガイドを参照することになりますが、 簡単な使い方はチートシート(Cheatsheet)が公開されています。[9]
この中から一般的なテクニカルノートを記述するときに、 必要な機能について整理し説明することにします。
左側がAsciidocでの記述、 右側が整形したものを表示しています。
ヘッダ
日本語の扱い場合が多いため次のように記述するのが簡単です。
|
レベル 1Text. レベル 2Text. レベル 3Text. レベル 4Text. |
パラグラフ
|
タイトル(省略可) 通常の パラグラフ | ||
|
タイトル(省略可)
| ||
|
タイトル(省略可)
die 'connect: '.$dbh->errstr;
次のパラグラフにある文字列は、 コードとして処理されません。 | ||
|
| ||
|
| ||
|
| ||
|
| ||
|
| ||
|
|
ブロック
ブロックは4文字以上の区切り記号に挟まれたテキストで、 使う区切り記号により整形の仕方が変わります。
|
タイトル(省略可)
| ||
|
タイトル(省略可)
# *ソース(source)* ブロック
# 用途: ソースコードのハイライト表示
# (`source-highlight` もしくは `pygmentize` が必要です)
use DBI;
my $dbh = DBI->connect('...',$u,$p)
or die "connect: $dbh->errstr";
| ||
| |||
|
例 1. タイトル(省略可)
例示(Example) ブロック 用途: 例示 (^^; デフォルトのキャプションは"Example:"になります。 次のようにして変更できます。
これを例示ブロックの前に置きます。 | ||
|
| ||
| |||
|
パススルー ブロック 用途: バックエンドのマークアップの書式を記述する
| ||
|
タイトル(省略可)
| ||
|
タイトル(省略可)
引用 ブロック 用途: 誰かの著作を引用するとき
cite source — author |
テキスト
|
強制的に |
|
標準, イタリック, ボールド, 『ダブルクォート』, 「シングルクォート」. 標準, 上付き, 下付き. |
|
コマンド表示:
|
|
PATH表示: /some/filez.txt, .b |
|
赤いテキスト 黄色い背景 さらに文字を大きく そしてボールド(全部) |
|
文字単位で指定: nib |
| |
|
© ® ™ — … → ← ⇒ ⇐ ¶ |
|
|
|
エスケープ: _italic_, _italic_, t__e__st, t__e__st, bold, <b>normal</b> ¶ `not single quoted' ``not double quoted'' |
リスト
|
バレットリスト
| ||||||||||||||||||||||||
|
バレットリスト 2
| ||||||||||||||||||||||||
|
オーダーリスト
| ||||||||||||||||||||||||
|
オーダーリスト 2
| ||||||||||||||||||||||||
|
ラベルリスト
| ||||||||||||||||||||||||
|
ラベルリスト 2
| ||||||||||||||||||||||||
|
ラベルリスト(行単位)
| ||||||||||||||||||||||||
|
Q&A
| ||||||||||||||||||||||||
|
インデントはオプション
| ||||||||||||||||||||||||
|
リストの分割
はじめに出現するパラグラフはリストを分割します。
ヘッダもリストを分割します。
| ||||||||||||||||||||||||
|
継続(Continuation)
| ||||||||||||||||||||||||
|
リストブロックはサブリストを含むことができます。
|
表(テーブル)
|
| |||||||||||||||
|
|
図(画像)、リンク
|
はじめのホーム
![]() 図 1. ブロックイメージ
![]() |
| |
|