「Asciidoc」の版間の差分

削除された内容追加された内容

インライン

2022年7月7日 (木) 11:16時点における版

AsciiDoc は人間が読める文書フォーマットで、意味的には DocBook XML と同等ですが、プレーンテキストによるマークアップの規則が用いられています。AsciiDoc文書はテキストエディタで作成し「そのまま」読むこともできますし、HTMLやDocBookツールチェーンがサポートする他のフォーマット、すなわちPDF、TeX、Unix manpages、電子書籍、スライドプレゼンテーションなどにもレンダリングできます。AsciiDocファイルの共通拡張子はtxt（AsciiDoc作成者が推奨）およ.adocです。

使用方法

使用方法は、LinuxもWindowsも共通。

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

asciidoc ファイル名.txt

です。

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

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

asciidoc sample.txt

となります。

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

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

注意1

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

注意2

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

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

次に、asciidoctor で表を描くサンプルコードを下記に。

.おもな税金
|===
|      |直接税 |間接税 

|国税
|所得税 +
 法人税 +
   相続税
|消費税 +
酒税 +
関税 +
たばこ税

|地方税
|住民税 +
固定資産税
|たばこ税
|===

結果として、幅などは多少は違いますが、

Table 1.おもな税金
	直接税	間接税
国税	所得税　法人税　相続税	消費税　酒税　関税　たばこ税
地方税	住民税固定資産税	たばこ税

のような表がwebブラウザ上にて描画されれば、成功です。

基本的な文法

表のつくりかた

Table 1.おもな税金
	直接税	間接税
国税	所得税　法人税　相続税	消費税　酒税　関税　たばこ税
地方税	住民税固定資産税	たばこ税

のような表を作りたい場合、

.おもな税金
|===
|      |直接税 |間接税 

|国税
|所得税 +
 法人税 +
   相続税
|消費税 +
酒税 +
関税 +
たばこ税

|地方税
|住民税 +
固定資産税
|たばこ税
|===

です。

「Table 1.」などの図版は、自動的に割り当てられます。

ほか、入門レベルを越えるので当面は説明しないが、他にもCSVファイルの内容のテキストをもとに表を表示する機能もあります。

テキストの編集方法

テキストの見出しの作りかた

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

== 文法

=== 見出しの作りかた

です。

「==」と「文法」のあいだに半角スペースが必要です。「===」と「見出しの作り方」のあいだも同様、半角スペースが必要です。もし半角スペースが無いと、見出しとしてレンダリングされません。

== レベル1

=== レベル2

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

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

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

=== レベル2

== レベル1

一方、

== レベル1

=== レベル2

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

つまり、高レベルの見出しを使うためには、レベル1から順番に使う必要があります。

箇条書き

番号なし箇条書き

こめ印（アスタリスク）「 * 」を使って、箇条書きを作れる。

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

実行結果

箇条書きの出だし

ああああ

いいい

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

アスタリスクと見出し名（「箇条書きの出だし」や「ああああ」など）のあいだに半角スペースが必要。半角スペースが無いと、認識せずに誤表示になりかねない。

番号つきの箇条書き

番号つきの箇条書きの表示には、ピリオド「.」を使う。

ソース

. ひとよの生き血をすすり
. ふらちな悪行ざんまい
. 右にもハゲがある

表示結果

1.ひとよの生き血をすすり
2.ふらちな悪行ざんまい
3.右にもハゲがある

ソースでは、ピリオドと見出し名のあいだに半角スペースが必要。

エスケープシーケンス

基本

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

つまり、

\*

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

なお、asciidoc のエスケープシーケンスは、バックスラッシュ「\」です。（ただしWindowsで日本語設定だと、円マークで表示される場合もあります。）

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

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

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

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

数式など

数式を書く場合、演算子の + , - , * , / , や等号 = の前後には、半角スペースを1つ入れると良い。大抵の場合は、1文字の記号の前後に半角スペースがあれば、単なる文字としてみなし、asciidocでの変換などを行わない場合が多いからです（さらに念のため、変換を実行してみてブラウザ上で確認してみると良い）。

実際

7 = 2 * 3 + 1

を変換しても、ブラウザ上では、そのまま表示される。

コメント機能

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

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

行の初めに

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

.txtのコメントになります。

太字と斜体

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

つまり、

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

なら、

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

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

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

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

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

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

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

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

実行結果

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

です。

傍注・脚注などの追加

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

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

^ ああああ

↑ 脚注クリア。

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

ソース例

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

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

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

実行結果

ルビーは赤い。^[1]

ジャバは黒い.^[2]

ジャバは外国産.^[3]

(※以上、実行結果)

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

^ ルビーとは宝石のこと
^ コーヒー豆でジャバというのがある
^ コーヒー豆でジャバというのがある

のような脚注がある。

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

記法いろいろ

記法	表示結果
H~2~	H₂
x^2^	x²
[red]#赤文字#	赤文字
[line-through]#打ち消し線#	~~打ち消し線~~

文字列の定数の利用

文字列の定数を定義できます。

コード例

:aaaa: ウィンドウズ10 

{aaaa} での動作確認済みです。

{aaaa} はマイクロソフト社の製品のはずです。

結果

ウィンドウズ10 での動作確認済みです。

ウィンドウズ10 はマイクロソフト社の製品のはずです。

たとえば、もし誤記で「ウィンドウズ9」と書き間違えても、定数の定義の行だけを書き直せば、定数の各所の呼び出し先では、書き直す必要が無い。これは、定数の利用回数が増えるほど、編集の効率が高まる。

HMTLやCSSなどでも同様の機能は出来るが、asciidocなら、より平易な記法で可能です。

機能

注記ボックス

ルビーのほうの asciidoctor で、下記のように冒頭で「:icons: font」を設定すると、[NOTE] などで注記アイコン画像つきのボックスを出せる。

画像を呼び出すのに「font」と指定するのは妙かもしれないが、そう決まっている。

「image」と書いても、別の意味に解釈されるので、アイコン画像は表示されない。

コード例

:icons: font

[NOTE]
====
ここにnote注記の内容を書く。
====

[TIP]
====
ここTIPSの内容を書く。
====

[IMPORTANT]
====
ここに内容を書く。
====

[CAUTION]
====
ここにcaution注記の内容を書く。
====

[WARNING]
====
ここにwarning注記の内容を書く。
====

キーボードアイコン画像の挿入

冒頭に、下記のように experimental アトリビュートを追加することで、キーボードアイコン画像が使えるようになります。

コード例

:experimental:

kbd:[Ctrl] + kbd:[C] でクリップボードにコピーします。

スタイルシート

asciidoc では、HTML生成時に、そのHTMLが読み込むスタイルシートの書かれたCSSファイルを指定することができます。

しかし.txt のソースファイル内部そのものでスタイルを指定することはできません。また、仮にそういう方法があったとしても非推奨でありサポート対象外です。

なぜなら、asciidoc は、コンテンツとプレゼンテーションとを明確に区別すべし、という理念の上で設計されたソフトウェアだからです。

つまり、asciidoc は、スタイルシート.txt ファイルとは別ファイルとして分離すべしという理念を持っています。

AsciiDocファイル自体へのスタイルのインライン化/埋め込みは不可・禁止・非推奨です。

[1] ああああ

[2] ルビーとは宝石のこと

[3] コーヒー豆でジャバというのがある

[4] コーヒー豆でジャバというのがある

[1]

[1]

[2]

[3]