AsciiDoc 1 文書の構成

AsciiDocのドキュメントは、「ドキュメントヘッダ」、「セクション」、 「パラグラフ」、「ブロック」で構成されます。

ドキュメントヘッダ (Document header)

ドキュメントヘッダは、文書のタイトル、著者の情報を記載します。 とりあえず文書を作成するときは必要ないので、ここでは詳細な説明は省略します。

セクション (Section)

ドキュメントヘッダを付ける、付けないにしても、以降に登場するのが、 セクションです。前回のブログ AsciiDoc Introduction に説明していますので、そちらを参照してください。

パラグラフとブロック (Paragraph and Block)

ドキュメントの内容は、パラグラフとブロックで構成します。 パラグラフは文書のかたまりで空行で1つのパラグラフが終わります。 AsciiDocのパラグラフの書式は以下のとおりです。

• normal (通常)
  
• literal (文字通り)
  
• verse (詩)
  
• quote (引用)
  
• admonition (注意) (TIP/NOTE/IMPORTANT/WARNING/CAUTION)
  
• listing (リスト)
  

normal (通常) パラグラフ

文字通り、通常のパラグラフです。(ここの文章のような)。 最初の行は左端から始めます。空行までが1つのパラグラフになります。 通常パラグラフは字下げ(インデント)されることはありません。

literal (文字通り) パラグラフ

literalパラグラフ。すなわち、書いたままの文書を 等幅フォント(monospaced font)で表示します。 パラグラフの最初の行の先頭に、スペースまたは、タブを入れると、 literalパラグラフになります。

記述例

        ここの部分は、literalパラグラフ。
        1行めの先頭は、スペースでインデントしています。
        記載したままで表示されます。

表示結果

ここの部分は、literalパラグラフ。
1行めの先頭は、スペースでインデントしています。
記載したままで表示されます。

[literal] を使うことで、literalパラグラフを 明示的に表すこともできます。

記述例

[literal]
ここの部分は、literalパラグラフ。
スペースでインデントしなくても、[literal]を使えば、
記載したままで表示されます。

表示結果

ここの部分は、literalパラグラフ。
スペースでインデントしなくても、[literal]を使えば、
記載したままで表示されます。

verse (詩) パラグラフ と、quote (引用) パラグラフ

改行を記述したまま表示します。また、著者、引用元を強調して表示します。

記述例

[verse, 松尾芭蕉, 奥の細道より]
五月雨を
集めて早し
最上川

表示結果

五月雨を
集めて早し
最上川

奥の細道より
— 松尾芭蕉

一方、quoteパラグラフは、著者/引用元を、右寄せで表します。

記述例

[quote, ウィンストン・チャーチル, イギリスの政治家 ノーベル文学賞受賞 1874～1965]
悲観主義者はすべての好機の中に困難をみつけるが、
楽観主義者はすべての困難の中に好機を見いだす

表示結果

悲観主義者はすべての好機の中に困難をみつけるが、 楽観主義者はすべての困難の中に好機を見いだす

イギリスの政治家 ノーベル文学賞受賞 1874～1965
— ウィンストン・チャーチル

admonition (注意) パラグラフ

パラグラフの先頭に注意を促すマークをおく書き方です。 マークには、Note,Tip,Important,Warning,Cautionがあります。

記述例

[NOTE]
This is an example note.

[TIP]
This is an example tip.

[IMPORTANT]
This is an example important.

[WARNING]
This is an example warning.

[CAUTION]
This is an expamle caution.

表示結果

Note	This is an example note.

Tip	This is an example tip.

Important

This is an example important.

Warning

This is an example warning.

Caution

This is an expamle caution.

TODO

• admonition アイコン
  
• list パラグラフ
  
• ブロックの説明
  

---

Last updated 2012-02-04 23:27:20 JST

AsciiDoc Introduction

AsciiDocを使う理由

AsciiDocを簡単に説明しますと、 テキストファイルをHTML,PDF,EPUB,unix manページなどの多くの 形式に変換するツールです。

私は、文章を作成するのに、単純なテキストフォーマットを 使うのが好きです。 理由は、文章の作成に集中することができる、 編集が簡単、プログラミングで使い慣れている エディタが使えることです。 そこで、テキストフォーマットから、HTMLなどのフォーマットに 変換してくれるツールを探していました。 偶然発見したのが、AsciiDocです。 使い方を調べてみると、本の執筆にも使われているくらい 本格的なツールだとわかりました。

実際、AsciiDocを利用して執筆された本を挙げます。

Ruby ベストプラクティス

AsciiDocで書いて、DocBook XMLを生成し、 dblatexを使ってPDFにレンダリングしたと、 著者自身が、言っています。

Progamming iOS 4

AsciiDocホームページ (http://www.methods.co.nz/asciidoc/index.html)
「Documents written using AsciiDoc」より。
他にもたくさんのAsciiDoc使用例がリストアップされています。

AsciiDocを使ってみよう

ということで、AsciiDocを使ってみようと思ってwebを 検索すると、日本語での紹介例があまり見つかりません。 仕方がないので、自分で使って情報を発信することにしました。 このブログの作成にAsciiDocを使って、使い方を学習し紹介していきます。 おそらく日本語で使った場合の問題にも遭遇すると 思いますので、その解決にもトライしたいです。

まず手始めに、このページで使った、書式を紹介します。

セクションとタイトル (Sections and Titles)

セクションのタイトルは、2行で書きます。 行の左端から書きます。 1行目がセクションのタイトルで、2行目にセクションの タイトルであることを示す記号を書きます。記号の個数は、1行目の セクションのタイトルと同じ長さの下線に見えるようにします。 こんな感じです。(プロポーショナルフォントの表示では、 1行目と2行目の長さが異なって見えるかもしれません)

   Introduction
   ============

セクションのレベルは、0 (top level)から、4 (bottom level) まで 対応していて、記号の種類により、レベルを決めます。

セクションのレベルと記号の区別

    Level 0 (top level):     ======================
    Level 1:                 ----------------------
    Level 2:                 ~~~~~~~~~~~~~~~~~~~~~~
    Level 3:                 ^^^^^^^^^^^^^^^^^^^^^^
    Level 4 (bottom level):  ++++++++++++++++++++++

この文章が書いてあるセクションは、レベル2 で記述は次のとおりです。

    セクションとタイトル (Sections and Titles)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1行でタイトルを記述する方法もあります。レベルは記号の数で 決まるので、記号の種類を覚えられない場合は、 こちらのほうが使い勝手がよいと思います。

    = Document Title (level 0) =
    == Section title (level 1) ==
    === Section title (level 2) ===
    ==== Section title (level 3) ====
    ===== Section title (level 4) =====

(END)

---

Last updated 2012-02-04 04:25:35 JST