Asciidoc

AsciiDoc は人間が読める文書フォーマットで、意味的には DocBook XML と同等ですが、プレーンテキストによるマークアップの規則が用いられています。AsciiDoc文書はテキストエディタで作成し「そのまま」読むこともできますし、HTMLやDocBookツールチェーンがサポートする他のフォーマット、すなわちPDF、TeX、Unix manpages、電子書籍、スライドプレゼンテーションなどにもレンダリングできます。AsciiDocファイルの共通拡張子はtxt(AsciiDoc作成者が推奨)およ.adocです。
使用方法は、LinuxもWindowsも共通。
HTMLに出力したい場合、コマンド
です。
何も出力形式を指定しない場合、HTMLファイルが新規に出力される。ソース.txtファイルはそのまま残ります。
たとえば、ファイル名が拡張子込みで「sample.txt」なら、コマンドは
となります。
なお.txtファイルそのものは、テキストエディタを使って、ユーザー個人で作成することになります。
ともかく上記コマンドでファイル「sample.html」が作成されるので、あとはこれを通常のwebブラウザで閲覧すれば、閲覧できます。
実行環境によって、表示が多少、違う可能性があります。
また、本wikiでの表示は、実際のasciidocの表示とは、微妙に異なります。
asciidocで作成されるHTMLファイルのソースコードが長いので、本wikiではソースの短縮のために(wikiサーバーの負担軽減のためです)、擬似的にwikiで似た表示を再現しているので、実際のasciidocとの表示とは差異があります。
次に、asciidoctor で表を描くサンプルコードを下記に。
結果として、幅などは多少は違いますが、
のような表がwebブラウザ上にて描画されれば、成功です。

のような表を作りたい場合、
です。
「Table 1.」などの図版は、自動的に割り当てられます。
ほか、入門レベルを越えるので当面は説明しないが、他にもCSVファイルの内容のテキストをもとに表を表示する機能もあります。
文頭に「==」を加えると、見出しになります。
です。
「==」と「文法」のあいだに半角スペースが必要です。「===」と「見出しの作り方」のあいだも同様、半角スペースが必要です。もし半角スペースが無いと、見出しとしてレンダリングされません。
のように、対応している。
(wikiとはレベルの数え方が違うので、注意。asciidocは、「=」の数よりもレベルの値が 1 だけ小さい。)
asciidoc は、そのテキスト位置での見出しのレベルを数えている。なので、下記はエラーになります。
一方、
は正常に動作するだろう。
つまり、高レベルの見出しを使うためには、レベル1から順番に使う必要があります。
こめ印(アスタリスク)「 * 」 を使って、箇条書きを作れる。
実行結果
このように、箇条書きは、Wiki文法とだいたい同じ。
アスタリスクと見出し名(「箇条書きの出だし」や「ああああ」など)のあいだに半角スペースが必要。半角スペースが無いと、認識せずに誤表示になりかねない。
番号つきの箇条書きの表示には、ピリオド「.」を使う。
ソース
表示結果
ソースでは、ピリオドと見出し名のあいだに半角スペースが必要。
もし、こめ印そのものを表示したいのに、箇条書きと認識して反応してしまう場合、エスケープシーケンス「\」を先頭につけくわえるなどすればいい。他の制御文字も、だいたい同様の対処法で上手く行くらしい。
つまり、
で、こめ印だけが表示される。
なお、asciidoc のエスケープシーケンスは、バックスラッシュ「\」です。(ただしWindowsで日本語設定だと、円マークで表示される場合もあります。)
他の多くの言語でもエスケープシーケンスはバックスラッシュですので、プログラマー基礎知識として覚えよう。
「エスケープシーケンス」とは何かについては、手短かに言うと、制御文字そのものを、制御文字としてではなく、単なる表示文字として出力させたい場合に使う特別な制御文字のことがエスケープシーケンスです。
「エスケープシーケンス」とは何かについては、これ以上は詳しくは説明しない。標準的なプログラム言語の入門書に書いてある。
なお、エスケープシーケンスそのものを表示したい場合、2つ続けて「//」のように入力することで、だいたい、どの言語でも上手く表示されるだろう。
数式を書く場合、演算子の + , - , * , / , や等号 = の前後には、半角スペースを1つ入れると良い。大抵の場合は、1文字の記号の前後に半角スペースがあれば、単なる文字としてみなし、asciidocでの変換などを行わない場合が多いからです(さらに念のため、変換を実行してみてブラウザ上で確認してみると良い)。
実際
を変換しても、ブラウザ上では、そのまま表示される。
一般のプログラム言語などのコメント機能と同様に、実行結果では表示しないテキストです「コメント」を、ソースファイルであ.txtファイルに加えることができます。
「コメント」と言っても、べつにSNSみたいに意見を投稿するわけではないので、誤解の無いよう。
行の初めに
.txtのコメントになります。
原則的に、* と *で囲んだ文字が太字になります。
つまり、
なら、
ここは太いはず だし、 こっちは細いはず
のように「*」で囲んだ部分だけが太字で表示されるはず。
ただし、文頭と行末以外は、半角スペースが認識のために必要です。
半角スペースが無い場合に、太字にさせたい場合は、
のように「**」と2つ続ければいい。
同様に、斜体(イタリック体)は、アンダーバー「_」で囲めばいい。
実行結果
です。
たとえば 「」 みたいな傍注・脚注みたいなのを、asciidoc 用語ではフットノートと言う。
以降のwiki側の処理のため、いったん脚注をクリアする。
↑ 脚注クリア。
さて、asciidocでフットノートを表示するにはキーワード「 \footnote:[] 」を使えばいい。
ソース例
ルビーは赤い。
ジャバは黒い.
ジャバは外国産.
(※以上、実行結果)
そして、ブラウザのページ最下部には、
のような脚注がある。
なお、番号のナンバリングとか微妙に実行結果とwikiが違うかもしれないが、wiki側の編集の都合。
文字列の定数を定義できます。
コード例
結果
たとえば、もし誤記で「ウィンドウズ9」と書き間違えても、定数の定義の行だけを書き直せば、定数の各所の呼び出し先では、書き直す必要が無い。これは、定数の利用回数が増えるほど、編集の効率が高まる。
HMTLやCSSなどでも同様の機能は出来るが、asciidocなら、より平易な記法で可能です。
ルビーのほうの asciidoctor で、下記のように冒頭で「:icons: font」を設定すると、[NOTE] などで注記アイコン画像つきのボックスを出せる。
画像を呼び出すのに「font」と指定するのは妙かもしれないが、そう決まっている。
「image」と書いても、別の意味に解釈されるので、アイコン画像は表示されない。
コード例
冒頭に、下記のように experimental アトリビュートを追加することで、キーボードアイコン画像が使えるようになります。
コード例
asciidoc では、HTML生成時に、そのHTMLが読み込むスタイルシートの書かれたCSSファイルを指定することができます。
しかし.txt のソースファイル内部そのものでスタイルを指定することはできません。また、仮にそういう方法があったとしても非推奨でありサポート対象外です。
なぜなら、asciidoc は、コンテンツとプレゼンテーションとを明確に区別すべし、という理念の上で設計されたソフトウェアだからです。
つまり、asciidoc は、スタイルシート.txt ファイルとは別ファイルとして分離すべしという理念を持っています。
AsciiDocファイル自体へのスタイルのインライン化/埋め込みは不可・禁止・非推奨です。