「Asciidoc」の版間の差分
→記法いろいろ: 文字列の定数の利用 |
M こめ印(アスタリスク) |
||
222 行 | 222 行 | ||
==== 箇条書き ==== |
==== 箇条書き ==== |
||
こめ印「 * 」 を使って、箇条書きを作れる。 |
こめ印(アスタリスク)「 * 」 を使って、箇条書きを作れる。 |
||
<pre> |
<pre> |
2022年5月31日 (火) 08:48時点における版
何のためのソフトか
用途
対象者は、
- テキストエディタだけだと、表とか表示できなくて不満。
- かといって、ワードとかだと、テキストエディタで編集できなくて不満。
- そこで、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は向いていない。
準備と基本の操作方法
インストール方法
Fedora の場合、コマンド
sudo dnf install asciidoc
をする必要がある。(これだけで十分かどうかは未確認。)
asciidoc とは別に、派生ソフトで asciidoctor というのがあるが、微妙に仕様の異なる別ソフトである。
本書では asciidoc のほうを説明する。
短い方の asciidoc は Python で実装されている。
長い方の asciidoctor は Ruby で実装されている。
出力方法
HTMLに出力したい場合、コマンド
asciidoc ファイル名.adoc
である。
何も出力形式を指定しない場合、HTMLファイルが新規に出力される。ソースのadocファイルはそのまま残る。
たとえば、ファイル名が拡張子込みで「sample.adoc」なら、コマンドは
asciidoc sample.adoc
となる。
なお、adocファイルそのものは、テキストエディタを使って、ユーザー個人で作成することになる。
ともかく上記コマンドでファイル「sample.html」が作成されるので、あとはこれを通常のwebブラウザで閲覧すれば、閲覧できる。
- 注意1
実行環境によって、表示が多少、違う可能性があります。
- 注意2
また、本wikiでの表示は、実際のasciidocの表示とは、微妙に異なります。
asciidocで作成されるHTMLファイルのソースコードが長いので、本wikiではソースの短縮のために(wikiサーバーの負担軽減のためです)、擬似的にwikiで似た表示を再現しているので、実際のasciidocとの表示とは差異があります。
基本的な文法
文法のすべては紹介しない(公式サイトを見ればいいので)。
初心者に必要だろうと思われるものを紹介する。
表のつくりかた
そもそも、表などの表示賭編集に強いのが asciidoc の強みである(でなければ、普通にテキストエディタやHTMLを使えば済むので)。なので、さっさと表の作り方を勉強しよう。
直接税 | 間接税 | |
---|---|---|
国税 | 所得税 法人税 相続税 |
消費税 酒税 関税 たばこ税 |
地方税 | 住民税 固定資産税 |
たばこ税 |
のような表を作りたい場合、
.おもな税金 |=== | |直接税 |間接税 |国税 |所得税 + 法人税 + 相続税 |消費税 + 酒税 + 関税 + たばこ税 |地方税 |住民税 + 固定資産税 |たばこ税 |===
である。
「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文法とだいたい同じ。
エスケープシーケンス
もし、こめ印そのものを表示したいのに、箇条書きと認識して反応してしまう場合、エスケープシーケンス「\」を先頭につけくわえるなどすればいい。他の制御文字も、だいたい同様の対処法で上手く行くらしい。
つまり、
\*
で、こめ印だけが表示される。
なお、asciidoc のエスケープシーケンスは、バックスラッシュ「\」である。他の多くの言語でもエスケープシーケンスはバックスラッシュであるので、プログラマー基礎知識として覚えよう。
「エスケープシーケンス」とは何かについては、手短かに言うと、制御文字そのものを、制御文字としてではなく、単なる表示文字として出力させたい場合に使う特別な制御文字のことがエスケープシーケンスである。
「エスケープシーケンス」とは何かについては、これ以上は詳しくは説明しない。標準的なプログラム言語の入門書に書いてある。
なお、エスケープシーケンスそのものを表示したい場合、2つ続けて「//」のように入力することで、だいたい、どの言語でも上手く表示されるだろう。
コメント機能
一般のプログラム言語などのコメント機能と同様に、実行結果では表示しないテキストである「コメント」を、ソースファイルであるadocファイルに加えることができる。
「コメント」と言っても、べつにSNSみたいに意見を投稿するわけではないので、誤解の無いよう。
行の初めに
// 以下、行末まで表示されない
でadocのコメントになる。
太字と斜体
原則的に、* と *で囲んだ文字が太字になります。
つまり、
*ここは太いはず* だし、 こっちは細いはず
なら、
ここは太いはず だし、 こっちは細いはず
のように「*」で囲んだ部分だけが太字で表示されるはず。
ただし、文頭と行末以外は、半角スペースが認識のために必要である。
半角スペースが無い場合に、太字にさせたい場合は、
*太字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なら、より平易な記法で可能である。