「Asciidoc」の版間の差分
:<syntaxhighlight lang=tid> タグ: 2017年版ソースエディター |
:<syntaxhighlight lang="tid"> タグ: 2017年版ソースエディター |
||
1 行 | 1 行 | ||
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に出力したい場合、コマンド |
HTMLに出力したい場合、コマンド |
||
asciidoc ファイル名. |
asciidoc ファイル名.txt |
||
で |
です。 |
||
何も出力形式を指定しない場合、HTMLファイルが新規に出力される。ソース |
何も出力形式を指定しない場合、HTMLファイルが新規に出力される。ソース.txtファイルはそのまま残ります。 |
||
たとえば、ファイル名が拡張子込みで「sample. |
たとえば、ファイル名が拡張子込みで「sample.txt」なら、コマンドは |
||
asciidoc sample. |
asciidoc sample.txt |
||
とな |
となります。 |
||
なお |
なお.txtファイルそのものは、テキストエディタを使って、ユーザー個人で作成することになります。 |
||
ともかく上記コマンドでファイル「sample.html」が作成されるので、あとはこれを通常のwebブラウザで閲覧すれば、閲覧でき |
ともかく上記コマンドでファイル「sample.html」が作成されるので、あとはこれを通常のwebブラウザで閲覧すれば、閲覧できます。 |
||
* 注意1 |
* 注意1 |
||
169 行 | 30 行 | ||
asciidocで作成されるHTMLファイルのソースコードが長いので、本wikiではソースの短縮のために(wikiサーバーの負担軽減のためです)、擬似的にwikiで似た表示を再現しているので、実際のasciidocとの表示とは差異があります。 |
asciidocで作成されるHTMLファイルのソースコードが長いので、本wikiではソースの短縮のために(wikiサーバーの負担軽減のためです)、擬似的にwikiで似た表示を再現しているので、実際のasciidocとの表示とは差異があります。 |
||
次に、asciidoctor で表を描くサンプルコードを下記に。 |
|||
とはいえ、なんのソースコードもないのに、HTMLに出力しても、面白くない。 |
|||
なので、とりあえず、asciidoctor で表を描くサンプルコードを下記に。 |
|||
:<syntaxhighlight lang="tid"> |
:<syntaxhighlight lang="tid"> |
||
196 行 | 54 行 | ||
結果として、幅などは多少は違 |
結果として、幅などは多少は違いますが、 |
||
{| class="wikitable" |
{| class="wikitable" |
||
209 行 | 67 行 | ||
|} |
|} |
||
のような表がwebブラウザ上にて描画されれば、成功で |
のような表がwebブラウザ上にて描画されれば、成功です。 |
||
== 基本的な文法 == |
== 基本的な文法 == |
||
文法のすべては紹介しない(公式サイトを見ればいいので)。 |
|||
初心者に必要だろうと思われるものを紹介する。 |
|||
=== 表のつくりかた === |
=== 表のつくりかた === |
||
(※ 上述の動作確認のものの再掲) |
|||
そもそも、表などの表示と編集に強いのが asciidoc の強みである(でなければ、普通にテキストエディタやHTMLを使えば済むので)。なので、さっさと表の作り方を勉強しよう。 |
|||
{| class="wikitable" |
{| class="wikitable" |
||
256 行 | 107 行 | ||
</syntaxhighlight> |
</syntaxhighlight> |
||
で |
です。 |
||
「Table 1.」などの図版は、自動的に割り当てられ |
「Table 1.」などの図版は、自動的に割り当てられます。 |
||
ほか、入門レベルを越えるので当面は説明しないが、他にもCSVファイルの内容のテキストをもとに表を表示する機能もあ |
ほか、入門レベルを越えるので当面は説明しないが、他にもCSVファイルの内容のテキストをもとに表を表示する機能もあります。 |
||
=== テキストの編集方法 === |
=== テキストの編集方法 === |
||
==== テキストの見出しの作りかた ==== |
==== テキストの見出しの作りかた ==== |
||
文頭に「==」を加えると、見出しにな |
文頭に「==」を加えると、見出しになります。 |
||
例えば、今、あなたの見ているwikiみたいな見出しをasciidocで表示したいなら、 |
|||
:<syntaxhighlight lang=tid> |
:<syntaxhighlight lang=tid> |
||
274 行 | 123 行 | ||
</syntaxhighlight> |
</syntaxhighlight> |
||
で |
です。 |
||
「==」と「文法」のあいだに半角スペースが必要です。「===」と「見出しの作り方」のあいだも同様、半角スペースが必要です。もし半角スペースが無いと、環境などによっては、うまく認識しない場合があります。 |
|||
さて、べつに、asciidoc は別に百科事典サイトを作るソフトではないので、表示結果には、編集機能だとかは無い。結果は、単に文字が大きく表示されるだけである。 |
|||
ともかく、上記ソースをHTML化すれば、おおむね |
|||
<big><big>文法</big></big> |
|||
<big>見出しの作りかた</big> |
|||
のような結果がブラウザ上で表示されるだろう。 |
|||
「==」と「文法」のあいだに半角スペースが必要です。「===」と「見出しの作り方」のあいだも同様、半角スペースが必要です。もし半角スペースが無いと、見出しとしてレンダリングされません。 |
|||
:<syntaxhighlight lang=tid> |
:<syntaxhighlight lang=tid> |
||
302 行 | 138 行 | ||
asciidoc は、そのテキスト位置での見出しのレベルを数えている。なので、下記はエラーにな |
asciidoc は、そのテキスト位置での見出しのレベルを数えている。なので、下記はエラーになります。 |
||
:<syntaxhighlight lang=tid> |
:<syntaxhighlight lang=tid> |
||
=== レベル2 |
=== レベル2 |
||
309 行 | 145 行 | ||
</syntaxhighlight> |
</syntaxhighlight> |
||
一方、 |
|||
いっぽう、 |
|||
:<syntaxhighlight lang=tid> |
:<syntaxhighlight lang=tid> |
||
== レベル1 |
== レベル1 |
||
319 行 | 155 行 | ||
は正常に動作するだろう。 |
は正常に動作するだろう。 |
||
つまり、高レベルの見出しを使うためには、レベル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など)をつけておかないと、エラーになる場合がある。きちんと名前をつけておこう。 |
|||
==== 箇条書き ==== |
==== 箇条書き ==== |
||
401 行 | 203 行 | ||
で、こめ印だけが表示される。 |
で、こめ印だけが表示される。 |
||
なお、asciidoc のエスケープシーケンスは、バックスラッシュ「\」で |
なお、asciidoc のエスケープシーケンスは、バックスラッシュ「\」です。(ただしWindowsで日本語設定だと、円マークで表示される場合もあります。) |
||
他の多くの言語でもエスケープシーケンスはバックスラッシュで |
他の多くの言語でもエスケープシーケンスはバックスラッシュですので、プログラマー基礎知識として覚えよう。 |
||
「エスケープシーケンス」とは何かについては、手短かに言うと、制御文字そのものを、制御文字としてではなく、単なる表示文字として出力させたい場合に使う特別な制御文字のことがエスケープシーケンスで |
「エスケープシーケンス」とは何かについては、手短かに言うと、制御文字そのものを、制御文字としてではなく、単なる表示文字として出力させたい場合に使う特別な制御文字のことがエスケープシーケンスです。 |
||
「エスケープシーケンス」とは何かについては、これ以上は詳しくは説明しない。標準的なプログラム言語の入門書に書いてある。 |
「エスケープシーケンス」とは何かについては、これ以上は詳しくは説明しない。標準的なプログラム言語の入門書に書いてある。 |
||
412 行 | 214 行 | ||
==== 数式など ==== |
==== 数式など ==== |
||
数式を書く場合、演算子の + , - , * , / , や等号 = の前後には、半角スペースを1つ入れると良い。大抵の場合は、1文字の記号の前後に半角スペースがあれば、単なる文字としてみなし、asciidocでの変換などを行わない場合が多いからで |
数式を書く場合、演算子の + , - , * , / , や等号 = の前後には、半角スペースを1つ入れると良い。大抵の場合は、1文字の記号の前後に半角スペースがあれば、単なる文字としてみなし、asciidocでの変換などを行わない場合が多いからです(さらに念のため、変換を実行してみてブラウザ上で確認してみると良い)。 |
||
実際 |
実際 |
||
421 行 | 223 行 | ||
=== コメント機能 === |
=== コメント機能 === |
||
一般のプログラム言語などのコメント機能と同様に、実行結果では表示しないテキストで |
一般のプログラム言語などのコメント機能と同様に、実行結果では表示しないテキストです「コメント」を、ソースファイルであ.txtファイルに加えることができます。 |
||
「コメント」と言っても、べつにSNSみたいに意見を投稿するわけではないので、誤解の無いよう。 |
「コメント」と言っても、べつにSNSみたいに意見を投稿するわけではないので、誤解の無いよう。 |
||
429 行 | 231 行 | ||
// 以下、行末まで表示されない |
// 以下、行末まで表示されない |
||
.txtのコメントになります。 |
|||
==== 太字と斜体 ==== |
==== 太字と斜体 ==== |
||
445 行 | 247 行 | ||
ただし、文頭と行末以外は、半角スペースが認識のために必要で |
ただし、文頭と行末以外は、半角スペースが認識のために必要です。 |
||
半角スペースが無い場合に、太字にさせたい場合は、 |
半角スペースが無い場合に、太字にさせたい場合は、 |
||
464 行 | 266 行 | ||
:''斜体(イタリック)'' と ''斜体(イタリック)'' |
:''斜体(イタリック)'' と ''斜体(イタリック)'' |
||
で |
です。 |
||
=== 傍注・脚注などの追加 === |
=== 傍注・脚注などの追加 === |
||
524 行 | 326 行 | ||
== 文字列の定数の利用 == |
== 文字列の定数の利用 == |
||
文字列の定数を定義でき |
文字列の定数を定義できます。 |
||
コード例 |
コード例 |
||
544 行 | 346 行 | ||
たとえば、もし誤記で「ウィンドウズ9」と書き間違えても、定数の定義の行だけを書き直せば、定数の各所の呼び出し先では、書き直す必要が無い。これは、定数の利用回数が増えるほど、編集の効率が高まる。 |
たとえば、もし誤記で「ウィンドウズ9」と書き間違えても、定数の定義の行だけを書き直せば、定数の各所の呼び出し先では、書き直す必要が無い。これは、定数の利用回数が増えるほど、編集の効率が高まる。 |
||
HMTLやCSSなどでも同様の機能は出来るが、asciidocなら、より平易な記法で可能で |
HMTLやCSSなどでも同様の機能は出来るが、asciidocなら、より平易な記法で可能です。 |
||
== 機能 == |
== 機能 == |
||
600 行 | 402 行 | ||
asciidoc では、HTML生成時に、そのHTMLが読み込むスタイルシートの書かれたCSSファイルを指定することができます。 |
asciidoc では、HTML生成時に、そのHTMLが読み込むスタイルシートの書かれたCSSファイルを指定することができます。 |
||
しかし |
しかし.txt のソースファイル内部そのものでスタイルを指定することはできません。また、仮にそういう方法があったとしても非推奨でありサポート対象外です。 |
||
なぜなら、asciidoc は、コンテンツとプレゼンテーションとを明確に区別すべし、という理念の上で設計されたソフトウェアだからです。 |
なぜなら、asciidoc は、コンテンツとプレゼンテーションとを明確に区別すべし、という理念の上で設計されたソフトウェアだからです。 |
||
つまり、asciidoc は、スタイルシート |
つまり、asciidoc は、スタイルシート.txt ファイルとは別ファイルとして分離すべしという理念を持っています。 |
||
AsciiDocファイル自体へのスタイルのインライン化/埋め込みは不可・禁止・非推奨です。 |
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 で表を描くサンプルコードを下記に。
.おもな税金 |=== | |直接税 |間接税 |国税 |所得税 + 法人税 + 相続税 |消費税 + 酒税 + 関税 + たばこ税 |地方税 |住民税 + 固定資産税 |たばこ税 |===
結果として、幅などは多少は違いますが、
直接税 | 間接税 | |
---|---|---|
国税 | 所得税 法人税 相続税 |
消費税 酒税 関税 たばこ税 |
地方税 | 住民税 固定資産税 |
たばこ税 |
のような表がwebブラウザ上にて描画されれば、成功です。
基本的な文法
表のつくりかた
直接税 | 間接税 | |
---|---|---|
国税 | 所得税 法人税 相続税 |
消費税 酒税 関税 たばこ税 |
地方税 | 住民税 固定資産税 |
たばこ税 |
のような表を作りたい場合、
.おもな税金 |=== | |直接税 |間接税 |国税 |所得税 + 法人税 + 相続税 |消費税 + 酒税 + 関税 + たばこ税 |地方税 |住民税 + 固定資産税 |たばこ税 |===
です。
「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~ | 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ファイルを指定することができます。
しかし.txt のソースファイル内部そのものでスタイルを指定することはできません。また、仮にそういう方法があったとしても非推奨でありサポート対象外です。
なぜなら、asciidoc は、コンテンツとプレゼンテーションとを明確に区別すべし、という理念の上で設計されたソフトウェアだからです。
つまり、asciidoc は、スタイルシート.txt ファイルとは別ファイルとして分離すべしという理念を持っています。
AsciiDocファイル自体へのスタイルのインライン化/埋め込みは不可・禁止・非推奨です。