「Asciidoc」の版間の差分

出典: フリー教科書『ウィキブックス(Wikibooks)』
削除された内容 追加された内容
→‎エスケープシーケンス: ただしwindowsで日本語設定だと、円マークで表示される場合もある。
Ef3 (トーク | 投稿記録)
タグ: 2017年版ソースエディター
607 行 607 行


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

[[Category:Asciidoc|*]]
[[Category:マークアップ言語]]

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

ソフト名は"Asciidoc"でも"AsciiDoc"でも"asciidoc"でも、どれでも良い。公式サイトでも、どの表記も用いられている。(※ よって、けっして当ページのページ名を誤記だと勘違いして、ページ名の改名はしないように。)

何のためのソフトか

用途

対象者は、

  1. テキストエディタだけだと、表とか表示できなくて不満。
  2. かといって、ワードとかだと、テキストエディタで編集できなくて不満。
  3. そこで、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が入っている可能性がある。

C:\Users\ユーザー名>ruby --version
ruby 3.1.2p20 (2022-04-12 revision 4491bb740a) [x64-mingw-ucrt]


gemが使えればひとまず問題が無いが、なるべく最新の安定版のものが望ましい。


gem を使って入手するためのコマンドは、asciidoctor の公式サイトで確認できる。

なお、asciidoctor の公式サイトのアドレスは、wikipedia日本語版w:AsciiDocで探してこれる。

2022年現在では、asciidoctorのインストールのコマンドは下記である。

gem install asciidoctor

実行すれば、下記の通りである。

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

上記コマンドを実行して、asciidoctorをインストールできたと思ったら、念のためバージョン確認をしよう。

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)


さて、これから、編集用のテキストファイルの設定に入ろう。

asciidoctor を入力するファイルの文字コードは、ユニコードである UTF8 でないといけない。

日本独自のJISコードには対応していない。

このため、まず、asciidoctor 用のテキストファイルを作る必要があり、文字コード UTF8 に指定して、そして拡張子に .adoc をつけて保存する。

例えば、sample.adoc というファイルを、UTF8形式で保存しよう。

次回からは、これを使う。

次回にファイル起動する際、windowsはそのままではadocファイルを何のプログラムで開くかを知らないので、adocファイルのダブルクリック時のダイアログの指示に従って、ファイルを開く際に使うプログラムを、お気に入りのテキストエディタに指定しよう。

上記の初期設定が終わったら、念のため、下記の出力方法を実行して、webブラウザで正しく文字が表示されているか等も確認しよう。

出力方法

出力方法は、LinuxもWindowsも共通。

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

asciidoc ファイル名.adoc

である。

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

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

asciidoc sample.adoc

となる。

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

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

  • 注意1

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

  • 注意2

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

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


とはいえ、なんのソースコードもないのに、HTMLに出力しても、面白くない。

なので、とりあえず、asciidoctor で表を描くサンプルコードを下記に。

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

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

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


結果として、幅などは多少は違うが、

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

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


基本的な文法

文法のすべては紹介しない(公式サイトを見ればいいので)。

初心者に必要だろうと思われるものを紹介する。

表のつくりかた

(※ 上述の動作確認のものの再掲)

そもそも、表などの表示と編集に強いのが asciidoc の強みである(でなければ、普通にテキストエディタやHTMLを使えば済むので)。なので、さっさと表の作り方を勉強しよう。

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

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

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

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

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

である。

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

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

テキストの編集方法

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

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

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

== 文法

=== 見出しの作りかた

である。

「==」と「文法」のあいだに半角スペースが必要です。「===」と「見出しの作り方」のあいだも同様、半角スペースが必要です。もし半角スペースが無いと、環境などによっては、うまく認識しない場合があります。


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


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

文法

見出しの作りかた

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


== レベル1

=== レベル2

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

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


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

=== レベル2

== レベル1


いっぽう、

== レベル1

=== レベル2

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

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

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

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

たとえば

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

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

さらに、(これから実行結果)

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

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


いっぽう、

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

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

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

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

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

箇条書き

番号なし箇条書き

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

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

実行結果

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

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

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

番号つきの箇条書き

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

ソース

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

表示結果

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

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

エスケープシーケンス

基本

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

つまり、

\*

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

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

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

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

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

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

数式など

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

実際

7 = 2 * 3 + 1

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

コメント機能

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

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

行の初めに

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

でadocのコメントになる。

太字と斜体

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

つまり、

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

なら、

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

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


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

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

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

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

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

_斜体(イタリック)_ と __斜体(イタリック) __

実行結果

斜体(イタリック)斜体(イタリック)

である。

傍注・脚注などの追加

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

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

  1. ^ ああああ

↑ 脚注クリア。


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

ソース例

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

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

ジャバは外国産.footnote:disclaimer[]
実行結果

ルビーは赤い。[1]

ジャバは黒い.[2]

ジャバは外国産.[3]

(※以上、実行結果)


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

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

のような脚注がある。


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

記法いろいろ

       記法        表示結果  
H~2~ H2
x^2^ x2
[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ファイルを指定することができます。

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

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

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

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