|
AsciiDoc は人間が読める文書フォーマットで、意味的には DocBook XML と同等ですが、プレーンテキストによるマークアップの規則が用いられています。AsciiDoc文書はテキストエディタで作成し「そのまま」読むこともできますし、HTMLやDocBookツールチェーンがサポートする他のフォーマット、すなわちPDF、TeX、Unix manpages、電子書籍、スライドプレゼンテーションなどにもレンダリングできます。AsciiDocファイルの共通拡張子はtxt（AsciiDoc作成者が推奨）およ.adocです。
ソフト名は"Asciidoc"でも"AsciiDoc"でも"asciidoc"でも、どれでも良い。公式サイトでも、どの表記も用いられている。（※ よって、けっして当ページのページ名を誤記だと勘違いして、ページ名の改名はしないように。）
=== 使用方法 ===
== 何のためのソフトか ==
使用方法は、LinuxもWindowsも共通。
=== 用途 ===
対象者は、
# テキストエディタだけだと、表とか表示できなくて不満。
# かといって、ワードとかだと、テキストエディタで編集できなくて不満。
# そこで、HTMLみたいに、テキストエディタで編集できて、なおかつwebブラウザなどで表示できるソフトが欲しい
と思う人向け。
最終的にせいせいされるのは単なるHTMLファイルなので、サイト閲覧者は別にasciidocをインストールしておく必要は無いし、閲覧者には何のインストールも求めない。
なので、このasciidoc は、拡張子「adoc」のテキストファイルをHTMLに変換するソフトがついている。
なお、「だったら、じゃあHTMLを直接編集すれで十分では？ asciidocは不要では？」と思う人は、そうすればいい。
実際、今、あなたが読んでいるwikiでも、asciidocなど使わないで編集されている。
GitHub や GitLab などの一部の外部サイトでは、HTMLではなく asciidoc を読み取って表示させる機能もついている。
ほか、[[Markdown]] という別言語（拡張子.md）でも、GitHubなどで類似のことが出来る。というか、Markdownのほうが普及している。
Markdown については文法が異なるので、このページでは解説しない。
=== 出来ないこと ===
asciidoc中でHTMLタグは使えないのが一般的である。
なので、HTMLタグを使われて書かれた文書を再利用したい場合、asciidocは不適切である。
このため、asciidoc は、けっしてHTMLの拡張'''ではない'''。
もしHTMLの事実上の拡張アプリみたいにのを勉強したいなら、サーバ限定だがテンプレート・エンジンの勉強として例えばwiki記事 [[Python/Flask]] などを勉強するなど、別の勉強をすべきである。
また、生成されたHTMLファイルのソースを見てみると、とても長い。なぜなら、CSSの設定などで、膨大な設定が記述されるからである。なので、HTMLソースの人力での解析のしやすさ等が欲しい人にはasciidocは向いていない。
== 準備と基本の操作方法 ==
=== インストール方法 ===
==== Linuxの場合 ====
Fedora の場合、コマンド
sudo dnf install asciidoc
をする必要がある。（これだけで十分かどうかは未確認。）
asciidoc とは別に、派生ソフトで asciidoctor というのがあるが、微妙に仕様の異なる別ソフトである。
本書では asciidoc のほうを説明する。
短い方の asciidoc は Python で実装されている。
長い方の asciidoctor は Ruby で実装されている。
Windows でもインストールできるが、事前に ruby のインストールが必要であるので、公式サイトから rubyinstaller をダウンロードすることになる。64ビットCPU機なら「X64」と書いてある rubyinstaller をダウンロードする。「x86」と書いてあるのは32ビット用である。
公式サイトからダウンロードしてきた rubyinstaller の圧縮ファイルの解凍になぜか時間が何十分と掛かるので、別の作業でもしながら待つか、あるいは、windows版を使わずにいっそ Linux 版を使うのが良いだろう。
==== windowsの場合 ====
asciidoctorをインストールする際、ruby付属のパッケージ管理ソフトのgemを使うのが簡単である。
asciidoctor の公式サイトでも、gemによるインストールを進めている（2022年6月8日現在）。
このため、まずrubyのインストーラーをダウンロードしてくる必要がある。インストーラーを探す際には、面倒でも、ruby公式サイトのトップページから探していくこと。
ネットの巷の解説サイトのものは、古いリンクまたは不適切なリンクが残っているものもあり、それをダウンロードしても解凍やインストールなどが上手くいかない。
ともかく、rubyが入れば通常、gemも入る。パスの設定などは（たぶん）不要である（このセクション書いた人のパソコンにすでに色々なソフトが入っているので、詳しくは分からない。windowsをクリーンインストールしたくないので未検証）。
ruby のインストーラーがいったん終了すると、コマンドライン風の別のインストーラーが立ち上がるが、しかし何のDOSコマンドやUNIXコマンドも入れる必要は無く、単なるインストーラーなので、画面にある指示（ただし英語）の通りに進めればいい。
指示の通りに作業を進めれば、最終的に、rubyやgemなどがインストールされるはずである（2022年6月8日に確認）。
ruby のインストールが終わったらと思ったら、念のためコマンドで確認しよう。
ruby --version
次のように最近のrubyのバージョンや日付が表示されれば、成功である。日付などが最近のものでなく極端に古い場合、すでにrubyが入っている可能性がある。
:<syntaxhighlight lang=tid>
C:\Users\ユーザー名>ruby --version
ruby 3.1.2p20 (2022-04-12 revision 4491bb740a) [x64-mingw-ucrt]
</syntaxhighlight>
gemが使えればひとまず問題が無いが、なるべく最新の安定版のものが望ましい。
gem を使って入手するためのコマンドは、asciidoctor の公式サイトで確認できる。
なお、asciidoctor の公式サイトのアドレスは、wikipedia日本語版[[w:AsciiDoc]]で探してこれる。
2022年現在では、asciidoctorのインストールのコマンドは下記である。
gem install asciidoctor
実行すれば、下記の通りである。
:<syntaxhighlight lang=tid>
C:\Users\ユーザー名>gem install asciidoctor
Fetching asciidoctor-2.0.17.gem
Successfully installed asciidoctor-2.0.17
Parsing documentation for asciidoctor-2.0.17
Installing ri documentation for asciidoctor-2.0.17
Done installing documentation for asciidoctor after 17 seconds
1 gem installed
</syntaxhighlight>
上記コマンドを実行して、asciidoctorをインストールできたと思ったら、念のためバージョン確認をしよう。
:<syntaxhighlight lang=tid>
C:\Users\ユーザー>asciidoctor --version
Asciidoctor 2.0.17 [https://asciidoctor.org]
Runtime Environment (ruby 3.1.2p20 (2022-04-12 revision 4491bb740a) [x64-mingw-u
crt]) (lc:Windows-31J fs:UTF-8 in:UTF-8 ex:UTF-8)
</syntaxhighlight>
さて、これから、編集用のテキストファイルの設定に入ろう。
asciidoctor を入力するファイルの文字コードは、ユニコードである UTF8 でないといけない。
日本独自のJISコードには対応していない。
このため、まず、asciidoctor 用のテキストファイルを作る必要があり、文字コード UTF8 に指定して、そして拡張子に .adoc をつけて保存する。
例えば、sample.adoc というファイルを、UTF8形式で保存しよう。
次回からは、これを使う。
次回にファイル起動する際、windowsはそのままではadocファイルを何のプログラムで開くかを知らないので、adocファイルのダブルクリック時のダイアログの指示に従って、ファイルを開く際に使うプログラムを、お気に入りのテキストエディタに指定しよう。
上記の初期設定が終わったら、念のため、下記の出力方法を実行して、webブラウザで正しく文字が表示されているか等も確認しよう。
=== 出力方法 ===
出力方法は、LinuxもWindowsも共通。
HTMLに出力したい場合、コマンド
asciidoc ファイル名.adoctxt
であるす。
何も出力形式を指定しない場合、HTMLファイルが新規に出力される。ソースのadoc.txtファイルはそのまま残るります。
たとえば、ファイル名が拡張子込みで「sample.adoctxt」なら、コマンドは
asciidoc sample.adoctxt
となるります。
なお、adoc.txtファイルそのものは、テキストエディタを使って、ユーザー個人で作成することになるります。
ともかく上記コマンドでファイル「sample.html」が作成されるので、あとはこれを通常のwebブラウザで閲覧すれば、閲覧できるます。
* 注意1
asciidocで作成されるHTMLファイルのソースコードが長いので、本wikiではソースの短縮のために（wikiサーバーの負担軽減のためです）、擬似的にwikiで似た表示を再現しているので、実際のasciidocとの表示とは差異があります。
次に、asciidoctor で表を描くサンプルコードを下記に。
とはいえ、なんのソースコードもないのに、HTMLに出力しても、面白くない。
なので、とりあえず、asciidoctor で表を描くサンプルコードを下記に。
:<syntaxhighlight lang="tid">
結果として、幅などは多少は違ういますが、
{| class="wikitable"
|}
のような表がwebブラウザ上にて描画されれば、成功であるす。
== 基本的な文法 ==
文法のすべては紹介しない（公式サイトを見ればいいので）。
初心者に必要だろうと思われるものを紹介する。
=== 表のつくりかた ===
（※ 上述の動作確認のものの再掲）
そもそも、表などの表示と編集に強いのが asciidoc の強みである（でなければ、普通にテキストエディタやHTMLを使えば済むので）。なので、さっさと表の作り方を勉強しよう。
{| class="wikitable"
</syntaxhighlight>
であるす。
「Table 1.」などの図版は、自動的に割り当てられるます。
ほか、入門レベルを越えるので当面は説明しないが、他にもCSVファイルの内容のテキストをもとに表を表示する機能もあるります。
=== テキストの編集方法 ===
==== テキストの見出しの作りかた ====
文頭に「==」を加えると、見出しになるります。
例えば、今、あなたの見ているwikiみたいな見出しをasciidocで表示したいなら、
:<syntaxhighlight lang=tid>
</syntaxhighlight>
であるす。
「==」と「文法」のあいだに半角スペースが必要です。「===」と「見出しの作り方」のあいだも同様、半角スペースが必要です。もし半角スペースが無いと、環境などによっては、うまく認識しない場合があります。
さて、べつに、asciidoc は別に百科事典サイトを作るソフトではないので、表示結果には、編集機能だとかは無い。結果は、単に文字が大きく表示されるだけである。
ともかく、上記ソースをHTML化すれば、おおむね
<big><big>文法</big></big>
<big>見出しの作りかた</big>
のような結果がブラウザ上で表示されるだろう。
「==」と「文法」のあいだに半角スペースが必要です。「===」と「見出しの作り方」のあいだも同様、半角スペースが必要です。もし半角スペースが無いと、見出しとしてレンダリングされません。
:<syntaxhighlight lang=tid>
asciidoc は、そのテキスト位置での見出しのレベルを数えている。なので、下記はエラーになるります。
:<syntaxhighlight lang=tid>
=== レベル2
</syntaxhighlight>
一方、
いっぽう、
:<syntaxhighlight lang=tid>
== レベル1
は正常に動作するだろう。
つまり、高レベルの見出しを使うためには、レベル1から順番に使わないといけないう必要があります。
一方、高いレベルから低いレベルに降りるぶんには、割と自由にできる。
ほか、レベル0（「=」が1個だけ）は、文頭の1行目で使用することで、見出しとしての機能に加えて、ドキュメントのタイトルになる。ブラウザのタブ欄にタイトルガ表示されるだろう。
たとえば
:<syntaxhighlight lang=tid>
= 今日の予定
晩ご飯はカレーにしよう。
</syntaxhighlight>
だったら、タブのタイトル欄に「今日の予定」と表示されるだろう。
さらに、（これから実行結果）
:<big><big><big>今日の予定</big></big></big>
:<big><big>晩ご飯はカレーにしよう。</big></big>
（ここまで実行結果）のように、表示されるはずである。
いっぽう、
:<syntaxhighlight lang=tid>
これはエラーになるか、危険。
晩ご飯はカレーにしよう。
= 今日の予定
</syntaxhighlight>
のように、1行目以外で、レベル0 を使うと、エラーになる。
もしエラーにならなくても、誤動作の原因になりかねないので、2行目以降でのレベル0の利用は避けるのが安全だろう。
見出しを作るさい、見出しの名前（「見出しの作りかた」や「レベル」1など）をつけておかないと、エラーになる場合がある。きちんと名前をつけておこう。
==== 箇条書き ====
で、こめ印だけが表示される。
なお、asciidoc のエスケープシーケンスは、バックスラッシュ「\」であるす。（ただしwindowsWindowsで日本語設定だと、円マークで表示される場合もあるります。）
他の多くの言語でもエスケープシーケンスはバックスラッシュであるすので、プログラマー基礎知識として覚えよう。
「エスケープシーケンス」とは何かについては、手短かに言うと、制御文字そのものを、制御文字としてではなく、単なる表示文字として出力させたい場合に使う特別な制御文字のことがエスケープシーケンスであるす。
「エスケープシーケンス」とは何かについては、これ以上は詳しくは説明しない。標準的なプログラム言語の入門書に書いてある。
==== 数式など ====
数式を書く場合、演算子の + , - , * , / , や等号 = の前後には、半角スペースを1つ入れると良い。大抵の場合は、1文字の記号の前後に半角スペースがあれば、単なる文字としてみなし、asciidocでの変換などを行わない場合が多いからであるす（さらに念のため、変換を実行してみてブラウザ上で確認してみると良い）。
実際
=== コメント機能 ===
一般のプログラム言語などのコメント機能と同様に、実行結果では表示しないテキストであるす「コメント」を、ソースファイルであるadoc.txtファイルに加えることができるます。
「コメント」と言っても、べつにSNSみたいに意見を投稿するわけではないので、誤解の無いよう。
// 以下、行末まで表示されない
でadoc.txtのコメントになるります。
==== 太字と斜体 ====
ただし、文頭と行末以外は、半角スペースが認識のために必要であるす。
半角スペースが無い場合に、太字にさせたい場合は、
:''斜体（イタリック）'' と ''斜体（イタリック）''
であるす。
=== 傍注・脚注などの追加 ===
== 文字列の定数の利用 ==
文字列の定数を定義できるます。
コード例
たとえば、もし誤記で「ウィンドウズ9」と書き間違えても、定数の定義の行だけを書き直せば、定数の各所の呼び出し先では、書き直す必要が無い。これは、定数の利用回数が増えるほど、編集の効率が高まる。
HMTLやCSSなどでも同様の機能は出来るが、asciidocなら、より平易な記法で可能であるす。
== 機能 ==
asciidoc では、HTML生成時に、そのHTMLが読み込むスタイルシートの書かれたCSSファイルを指定することができます。
しかし、adoc.txt のソースファイル内部そのものでスタイルを指定することはできません。また、仮にそういう方法があったとしても非推奨でありサポート対象外です。
なぜなら、asciidoc は、コンテンツとプレゼンテーションとを明確に区別すべし、という理念の上で設計されたソフトウェアだからです。
つまり、asciidoc は、スタイルシートはadoc.txt ファイルとは別ファイルとして分離すべしという理念を持っています。
AsciiDocファイル自体へのスタイルのインライン化/埋め込みは不可・禁止・非推奨です。
| 