Asciidoc

何のためのソフトか

対象者は、

1. テキストエディタだけだと、表とか表示できなくて不満。
2. かといって、ワードとかだと、テキストエディタで編集できなくて不満。
3. そこで、HTMLみたいに、テキストエディタで編集できて、なおかつwebブラウザなどで表示できるソフトが欲しい

と思う人向け。

なので、このasciidoc は、拡張子「adoc」のテキストファイルをHTMLに変換するソフトがついている。

なお、「だったら、じゃあHTMLを直接編集すれで十分では？ asciidocは不要では？」と思う人は、そうすればいい。

実際、今、あなたが読んでいるwikiでも、asciidocなど使わないで編集されている。

準備と基本の操作方法

インストール方法

Fedora の場合、コマンド

sudo dnf install asciidoc

をする必要がある。（これだけで十分かどうかは未確認。）

asciidoc とは別に、派生ソフトで asciidoctor というのがあるが、微妙に仕様の異なる別ソフトである。

本書では asciidoc のほうを説明する。

短い方の asciidoc は Python で実装されている。

長い方の asciidoctor は Ruby で実装されている。

出力方法

HTMLに出力したい場合、コマンド

asciidoc ファイル名.adoc

である。

何も出力形式を指定しない場合、HTMLファイルが新規に出力される。ソースのadocファイルはそのまま残る。

たとえば、ファイル名が拡張子込みで「sample.adoc」なら、コマンドは

asciidoc sample.adoc

となる。

なお、adocファイルそのものは、テキストエディタを使って、ユーザー個人で作成することになる。

ともかく上記コマンドでファイル「sample.html」が作成されるので、あとはこれを通常のwebブラウザで閲覧すれば、閲覧できる。

• 注意1

実行環境によって、表示が多少、違う可能性があります。

• 注意2

また、本wikiでの表示は、実際のasciidocの表示とは、微妙に異なります。

asciidocで作成されるHTMLファイルのソースコードが長いので、本wikiではソースの短縮のために（wikiサーバーの負担軽減のためです）、擬似的にwikiで似た表示を再現しているので、実際のasciidocとの表示とは差異があります。

文法

見出しの作りかた

文頭に「==」を加えると、見出しになる。

例えば、今、あなたの見ているwikiみたいな見出しをasciidocで表示したいなら、

== 文法

=== 見出しの作りかた

である。

もっとも、asciidoc は別に百科事典サイトを作るソフトではないので、表示結果に編集機能だとかは無く、結果は単に文字が大きく表示されるだけだが。

ともかく、上記ソースをHTML化すれば、おおむね

文法

見出しの作りかた

のような結果がブラウザ上で表示されるだろう。

== レベル1

=== レベル2

のように、対応している。

（wikiとはレベルの数え方が違うので、注意。asciidocは、「=」の数よりもレベルの値が 1 だけ小さい。）

asciidoc は、そのテキスト位置での見出しのレベルを数えている。なので、下記はエラーになる。

=== レベル2

== レベル1

いっぽう、

== レベル1

=== レベル2

は正常に動作するだろう。

つまり、高レベルの見出しを使うためには、レベル1から順番に使わないといけない。

一方、高いレベルから低いレベルに降りるぶんには、割と自由にできる。

ほか、レベル0（「=」が1個だけ）は、文頭の1行目で使用することで、見出しとしての機能に加えて、ドキュメントのタイトルになる。ブラウザのタブ欄にタイトルガ表示されるだろう。

たとえば

= 今日の予定
晩ご飯はカレーにしよう。

だったら、タブのタイトル欄に「今日の予定」と表示されるだろう。

さらに、（これから実行結果）

今日の予定

晩ご飯はカレーにしよう。

（ここまで実行結果）のように、表示されるはずである。

いっぽう、

これはエラーになるか、危険。

晩ご飯はカレーにしよう。
= 今日の予定

のように、1行目以外で、レベル0　を使うと、エラーになる。

もしエラーにならなくても、誤動作の原因になりかねないので、2行目以降でのレベル0の利用は避けるのが安全だろう。

見出しを作るさい、見出しの名前（「見出しの作りかた」や「レベル」1など）をつけておかないと、エラーになる場合がある。きちんと名前をつけておこう。

箇条書き

こめ印「 * 」 を使って、箇条書きを作れる。

* 箇条書きの出だし
** ああああ
*** いいい

実行結果

• 箇条書きの出だし

• ああああ

• いいい

このように、箇条書きは、Wiki文法とだいたい同じ。

エスケープシーケンス

もし、こめ印そのものを表示したいのに、箇条書きと認識して反応してしまう場合、エスケープシーケンス「\」を先頭につけくわえるなどすればいい。他の制御文字も、だいたい同様の対処法で上手く行くらしい。

つまり、

\*

で、こめ印だけが表示される。

なお、asciidoc のエスケープシーケンスは、バックスラッシュ「\」である。他の多くの言語でもエスケープシーケンスはバックスラッシュであるので、プログラマー基礎知識として覚えよう。

「エスケープシーケンス」とは何かについては、手短かに言うと、制御文字そのものを、制御文字としてではなく、単なる表示文字として出力させたい場合に使う特別な制御文字のことがエスケープシーケンスである。

「エスケープシーケンス」とは何かについては、これ以上は詳しくは説明しない。標準的なプログラム言語の入門書に書いてある。

なお、エスケープシーケンスそのものを表示したい場合、2つ続けて「//」のように入力することで、だいたい、どの言語でも上手く表示されるだろう。

コメント機能

一般のプログラム言語などのコメント機能と同様に、実行結果では表示しないテキストである「コメント」を、ソースファイルであるadocファイルに加えることができる。

「コメント」と言っても、べつにSNSみたいに意見を投稿するわけではないので、誤解の無いよう。

行の初めに

// 以下、行末まで表示されない

でadocのコメントになる。

太字と斜体

原則的に、* と *で囲んだ文字が太字になります。

つまり、

*ここは太いはず* だし、 こっちは細いはず

なら、

ここは太いはず だし、 こっちは細いはず

のように「*」で囲んだ部分だけが太字で表示されるはず。

ただし、文頭と行末以外は、半角スペースが認識のために必要である。

半角スペースが無い場合に、太字にさせたい場合は、

*太字A* と **太字B** と**太字C** 

のように「**」と2つ続ければいい。

同様に、斜体（イタリック体）は、アンダーバー「_」で囲めばいい。

_斜体（イタリック）_ と __斜体（イタリック） __

実行結果

斜体（イタリック） と 斜体（イタリック）

である。

傍注・脚注などの追加

たとえば 「」 みたいな傍注・脚注みたいなのを、asciidoc 用語ではフットノートと言う。

以降のwiki側の処理のため、いったん脚注をクリアする。

↑ 脚注クリア。

さて、asciidocでフットノートを表示するにはキーワード「 \footnote:[] 」を使えばいい。

ソース例

ルビーは赤い。footnote:[ルビーとは宝石のこと]

ジャバは黒い.footnote:disclaimer[コーヒー豆でジャバというのがある]

ジャバは外国産.footnote:disclaimer[]

実行結果

ルビーは赤い。

ジャバは黒い.

ジャバは外国産.

(※以上、実行結果)

そして、ブラウザのページ最下部には、

のような脚注がある。

なお、番号のナンバリングとか微妙に実行結果とwikiが違うかもしれないが、wiki側の編集の都合。