Title: インストール・基本的な使い方 - BlueFeather マニュアル
CSS: black.css

BlueFeather マニュアル

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

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

{toc}

インストール
----
同梱の 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)
	%

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


### 拡張子による出力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>



メタデータについての詳細は、[メタデータリファレンス](metadata-reference.html)を参照してください。

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

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

	% bluefeather -


### コマンドラインオプション {#commandline-options}

`-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