BlueFeather マニュアル

# インストール・基本的な使い方

この文書では、BlueFeather そのものの使い方について記述しています。 BlueFeather が解釈する Markdown 記法への独自拡張については、Markdown 記法の拡張を参照してください。

- インストール
- コマンドラインから使う
  - 基本
  - 強制変換オプション（`--force`）
  - 拡張子による出力htmlの違い
  - 文書メタデータ
  - 標準入力からの読み込み（stdin-mode）
  - コマンドラインオプション
- Rubyスクリプト内で使う
  - 基本
  - HTML文書の生成
  - 文書のメタデータ取得

## インストール

同梱の setup.rb を実行することにより、ファイルが適切な位置にコピーされ、インストールが完了します。

    % ruby setup.rb

もしくは、RubyGems がインストールされていれば、インターネットに接続されたPCから次のように打ち込むことでインストールすることも可能です。

    % gem install bluefeather

## コマンドラインから使う

### 基本

インストールが正常に終了していれば、`bluefeather` コマンドを使って、Markdown記法で書かれたファイルを変換することができます。 インターフェースは以下の通りです。

    bluefeather [options] file1 [file2] [file3] ...

たとえば、次のように入力することで、拡張子が `.bftext` のファイル全てをhtmlファイルに変換することができます。

    % bluefeather *.bftext
    example1.bftext => example1.html (4240 byte)
    example2.bftext => example2.html (5613 byte)
    example3.bftext => example3.html (10499 byte)
    %

### 強制変換オプション（`--force`）

通常 `bluefeather` コマンドは、入力テキストファイルが更新されていたときのみ（更新日時が新しくなっていたときのみ）変換を行います。

    % bluefeather example1.bftext
    example1.bftext => example1.html (4240 byte)
    % bluefeather example1.bftext
    %

更新日時に関わらず全てのファイルを変換したい場合には、`--force` オプションをつけて実行してください。

    % bluefeather example1.bftext
    example1.bftext => example1.html (4240 byte)
    % bluefeather --force example1.bftext
    example1.bftext => example1.html (4240 byte)
    %

この他のオプションの種類については、この文書内のコマンドラインオプションの項を参照してください。

### 拡張子による出力htmlの違い

`bluefeather` コマンドでは、変換対象のファイルの拡張子によって、どのようなhtmlファイルを出力するかが異なります。

`.md`, `.bfdoc`
  DTD宣言やhead要素などを含んだ、完全なHTML文書を生成する
それ以外
  HTML片を生成する（DTD宣言やhead要素は含まない）

たとえば、次のような一文だけが書かれたテキストファイルがあるとします。

    test paragraph.

このテキストファイルが `test1.bftext` という名前であれば、変換結果（`test1.html`）はこのようになります。

    <p>test paragraph.</p>

しかし、もしこのファイルが `test1.bfdoc` という名前であれば、上記の例と異なり完全なHTML文書を生成します。

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    <html>
    <head>
    <title>no title (Generated by BlueFeather)</title>
    </head>
    <body>

    <p>test paragraph.</p>

    </body>
    </html>

なお、このとき変換する文書にレベル1の見出しが含まれていれば、その見出しが自動的にhtml文書のtitleとして使われます。

test2.bfdoc

      Test Document
      =============

      test paragraph.

test2.html（出力結果）

      <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
      <html>
      <head>
      <title>Test Document</title>
      </head>
      <body>

      <h1 id="bfheader-a5decd745d43af4aa8cf62eef5be43ac">Test Document</h1>

      <p>test paragraph.</p>

      </body>
      </html>

### 文書メタデータ

拡張子が `.bfdoc` や `.md` のファイルには、文書メタデータを付け加えることが出来ます。

test3.bfdoc

      Title: Test Document
      CSS: style.css

      Test paragraph.

test3.html

      <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
      <html>
      <head>
      <title>Test Document</title>
      <link rel="stylesheet" type="text/css" href="style.css" />
      </head>
      <body>

      <p>Test paragraph.</p>

      </body>
      </html>

メタデータについての詳細は、メタデータリファレンスを参照してください。

### 標準入力からの読み込み（stdin-mode）

ファイル名を `-` とだけ指定すると特殊な動作モードになり、標準入力からテキストを読み込み、変換結果のhtmlを標準出力へ書き込みます。 パイプラインを用いるときなどに便利です。

    % bluefeather -

### コマンドラインオプション

`-e NAME`, `--encoding NAME`
  変換するテキストファイルのエンコーディングを、指定したエンコーディングとして解釈します。 （`shift-jis` / `euc-jp` / `utf-8` / `ascii` のうちいずれか、もしくは最初の数文字。標準では `utf-8`）
`-f TYPE`, `--format TYPE`
  出力するhtmlの種別を特定します。 `text`, `bftext` ならhtml片を、 `document`, `bfdoc` なら完全なhtml文書を出力します。 （標準ではファイルの拡張子から自動判別）
`--force`
  入力ファイルの更新日時に関わらず、全てのファイルを変換します。（標準では入力ファイルが新しくなっている場合のみ変換）
`-h`, `--help`
  `bluefeather` コマンドの解説を表示します。
`-o DIR`, `--output DIR`
  指定したディレクトリに全てのファイルを生成します。（標準ではパース対象のファイルと同じ位置に生成）
`-q`, `--quiet`
  動作時に作業の状況や結果を表示しません。
`--suffix .SUF`
  出力するファイルの拡張子を指定します。（標準は.html）
`-v`, `--verbose`
  冗長フラグ。作業内容を詳細に表示します。
`--version`
  BlueFeather のバージョンを表示します。

## Rubyスクリプト内で使う

### 基本

もっとも基本的なメソッドは、`BlueFeather.parse` です。 このメソッドにより、BlueFeatherを用いて文字列をパースし、htmlに変換することができます。

    require 'bluefeather'

    str = "もっとも基本的な例です。"
    puts BlueFeather.parse(str)      #=> "<p>もっとも基本的な例です。</p>"

また、`BlueFeather.parse_file` を使えば、ファイルの中にある文字列を読み込んでパースすることができます。

    BlueFeather.parse_file('test1.txt')
    BlueFeather.parse_file('test2.markdown')
    BlueFeather.parse_file('test3.bftext')

### HTML文書の生成

`parse` や `parse_file` メソッドの代わりに、`parse_document` や `parse_document_file` メソッドを用いることによって、HTML片ではなく完全なHTML文書を生成することが可能です。

test.bfdoc

      The sentence is expected as HTML.

test.rb

      require 'bluefeather'

      puts '-- parse_file --'
      puts BlueFeather.parse_file('test.bfdoc')

      puts '-- parse_document_file --'
      puts BlueFeather.parse_document_file('test.bfdoc')

実行結果

      -- parse_file --
      <p>The sentence is expected as HTML.</p>

      -- parse_document_file --
      <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
      <html>
      <head>
      <title>no title (Generated by BlueFeather)</title>
      </head>
      <body>

      <p>The sentence is expected as HTML.</p>

      </body>
      </html>

### 文書のメタデータ取得

文書をパースして直接 html を生成するのではなく、`BlueFeather::Document` オブジェクトを生成することにより、その文書のメタデータを取得することができます。

    doc = BlueFeather::Document.parse(<<EOS)
    Title: test document
    CSS: style.css

    test paragraph.
    EOS

    p doc['title']     # => "test document"
    p doc['css']       # => "style.css"
    p doc[:css]        # => "style.css"
    p doc['undefined'] # => nil

    p doc.body         # => "test paragraph."

この `BlueFeather::Document` オブジェクトから実際に html を生成するには、 `to_html` メソッドを呼んでください。

    doc.to_html