2014年7月14日月曜日

Readcarpet README 翻訳

RedcarpetのREADMEをライセンスにもとづき翻訳します。

原文は、RedcarpetのGitHubリポジトリのコミットd69951e110を使用しています。

なお、ライセンス部分については、原文のままです。以下、翻訳です。


Redcarpetは、砂糖、スパイス、そしてイケてるすべてもので書かれています


Redcarpetは、butterfliesやpopcorn風味のMarkdown処理系Rubyのライブラリです。

このライブラリは人によって書かれています


RedcarpetはVicent Martíによって書かれました。Robin DupretとMatt Rogersによってメンテナンスされています。

Redcarpetは、Sundownライブラリとその作者（Natacha Porté, Vicent Martí, および多くの素晴らしい貢献者）の存在なしには、ありえなかったでしょう。

Gemですべてをインストールできます


Redcarpetは、Ruby gemとして簡単に利用可能です。いくつかのネイティブ拡張をビルドしますが、パーサは単独で動作し、ライブラリのインストールは必要ありません。Redcarpet 3.0からは、Rubyのバージョン1.9.2（または、1.9モードのRubinius）以降が必要です。

$ [sudo] gem install redcarpet

Ruby 1.8.7で使用するなら、バージョン2.3.0を使う必要があります。

$ [sudo] gem install redcarpet -v 2.3.0

RedcarpetのソースはGitHubにあります。

$ git clone git://github.com/vmg/redcarpet.git

そして本当に簡単に使えるようです


Redcarpetライブラリのコアは、Redcarpet::Markdownクラスです。このクラスの各インスタンスは１つのRendererにアタッチされます。Markdownクラスは、ドキュメントのパースを行い、出力を生成するためにアタッチされたレンダラを使います。

Redcarpet::Markdownオブジェクトは必要とされる設定にもとづき一度だけインスタンス化されれることが推奨されており、パースのたびに再利用されます。

# Markdownパーサーを初期化
markdown = Redcarpet::Markdown.new(renderer, extensions = {})

ここでは、変数renderer はレンダラオブジェクトを参照しており、Redcarpet::Render::Baseを継承しています。与えられたオブジェクトがインスタンス化されていない場合、ライブラリがデフォルト引数でインスタンス化します。

Markdownオブジェクトを使ったレンダリングは、Markdown#renderで行われます。RedCloth APIとは異なり、レンダリングするテキストは引数として渡されます。再利用を促すためMarkdownインスタンス内には保存されません。
例：

markdown.render("This is *bongos*, indeed.")
# => "<p>This is <em>bongos</em>, indeed.</p>"

パーサが使用するMarkdown拡張を含んだハッシュを指定することもできます。以下の拡張が使用できます。

  • :no_intra_emphasis: 単語内の強調をパースしません。foo_bar_bazのような文字列は、<em>タグを生成しません。

  • :tables: テーブル（PHP-Markdownスタイル）をパースします。

  • :fenced_code_blocks: 囲まれた (fenced) コードブロック（PHP-Markdownスタイル）をパースします。３つ以上の~またはバッククォートで区切られたブロックをコードとして扱います。コードのインデントは必要ありません。オプションで、言語の名前をコードブロックの開きの囲い (fence) の末尾に追加しても構いません。

  • :autolink: <>で囲われていない場合にもリンクをパースします。http, httpsおよびftpプロトコルの自動リンクが、自動的に検知されます。Emailアドレスや、プロトコルがないwwwから始まるリンクも処理します。

  • :disable_indented_code_blocks: 通常のmarkdownコードブロックをパースしません。Markdownは４つのスペースで始まる行をコードブロックに変換しますが、このオプションはその挙動を抑止します。fenced_code_blocks: trueとともに使用することを推奨します。

  • :strikethrough: 取り消し線（PHP-Markdownスタイル）をパースします。２つの~が取り消し線の開始を表します。（例 this is ~~good~~ bad）。

  • :lax_spacing: Markdown標準のように、HTMLブロックを空行で囲む必要がありません。

  • :space_after_headers: ヘッダの先頭にあるハッシュ記号（訳注：#）とそれに続く文字の間にスペースが常に必要になります（例：#this is my headerは無効なヘッダになります）。

  • :superscript: ^の後を上付き文字としてパースします。隣接する上付き文字は一緒にネストされ、連続する値は括弧で囲むことができます。（例：this is the 2^(nd) time）。

  • :underline: アンダースコアによる強調を下線としてパースします。これは_下線_ですが、これは*斜体*のままです。

  • :highlight: 強調をパースします。これは==強調==です。<mark>highlighted</mark>と表示されます。

  • :quote: 引用をパースします。これは"引用"です。<q>quote</q>と表示されます。

  • :footnotes: 脚注（PHP-Markdownスタイル）をパースします。脚注は参照スタイルのリンクと同じように動作します。テキストに隣接するマーカー（例：This is a sentence.[^1]）と、独立した行に書かれた脚注の定義（例：[^1]: This is a footnote.）で構成されます。脚注の定義はドキュメント内ならどこにでも書けます。

例：

markdown = Redcarpet::Markdown.new(Redcarpet::Render::HTML, autolink: true, tables: true)

あなた、ランチにレンダラーを何個か詰めておいたわよ


Redcarpetには、Redcarpet::Render::HTMLとRedcarpet::Render::XHTMLの２つのレンダラが内蔵されており、それぞれ、HTMLとXHTMLを出力します。これらのレンダラは実際にはCで実装されているため、優秀なパフォーマンスを提供します — 他のRubyで実装されたMarkdown処理系より桁違いに速いです。

以前はHTML出力にだけ適用されていたレンダリングフラグはすべて、Redcarpet::Render::HTMLクラスに移動されました。以下のようにレンダラをインスタンス化する際に有効になります。

Redcarpet::Render::HTML.new(render_options = {})

上記は、HTMLレンダラを初期化します。以下のフラグが使用可能です。

  • :filter_html: ユーザが入力したHTMLの出力を許可しません。

  • :no_images: <img>タグを生成しません。

  • :no_links: <a>タグを生成しません。

  • :no_styles: <style>タグを生成しません。

  • :escape_html: HTMLタグをエスケープします。このオプションは、:no_styles, :no_links, :no_images および :filter_htmlより優先されます。つまり、存在するタグはすべて取り除かれずにエスケープされます。

  • :safe_links_only: 安全と考えられるプロトコルのリンクのみを生成します。

  • :with_toc_data: HTMLアンカーを、出力されるHTMLの各ヘッダに追加して、各セクションへのリンクを可能にします。

  • :hard_wrap: 段落中で、もとのMarkdownに改行がある場合、HTMLの<br>タグを挿入します（デフォルトでは、Markdownはこれらの改行を無視します）。

  • :xhtml: XHTML準拠のタグを出力します。このオプションは、Render::XHTMLレンダラでは常に有効になります。

  • :prettify: google-code-prettify用に、prettyprintクラスを<code>タグに追加します。.

  • :link_attributes: リンクを追加するための、特別な属性のハッシュです。

例：

renderer = Redcarpet::Render::HTML.new(no_links: true, hard_wrap: true)

HTMLレンダラには別バージョンとしてRedcarpet::Render::HTML_TOCがあります。これは、Markdown文書のヘッダにもとづいてHTMLに目次を出力します。

このレンダラオブジェクトをインスタンス化する際には、任意でnesting_levelオプションを渡すことができます。このオプションは整数で、指定したレベルまでのヘッダのみをレンダリングすることができます。

さらに、ピュアなRubyカスタムレンダラ、あるいは既存レンダラの拡張を書くために、抽象ベースクラスRedcarpet::Render::Baseを使用できます。

自分で料理することもできます


カスタムレンダラは、既存のレンダラを継承して作成します。ビルトインされたレンダラであるHTML, XHTMLは次のように拡張できます。

# コードブロックをハイライトするカスタムレンダラを作成します
class HTMLwithPygments < Redcarpet::Render::HTML
  def block_code(code, language)
    Pygments.highlight(code, lexer: language)
  end
end

markdown = Redcarpet::Markdown.new(HTMLwithPygments, fenced_code_blocks: true)

しかし、新規レンダラをゼロから作成することもできます（Manpageレンダラの実装例として、lib/redcarpet/render_man.rbを見てみます）。

class ManPage < Redcarpet::Render::Base
  # ドリルを手に取り -- ここから始めます
end

以下のインスタンスメソッドがレンダラにより実装されます。

ブロックレベルの呼び出し

メソッドの戻り値がnilの場合、そのブロックはスキップされます。ドキュメント要素に対するメソッドが実装されていない場合、そのブロックはスキップされます。

例：

class RenderWithoutCode < Redcarpet::Render::HTML
  def block_code(code, language)
    nil
  end
end

  • block_code(code, language)
  • block_quote(quote)
  • block_html(raw_html)
  • footnotes(content)
  • footnote_def(content, number)
  • header(text, header_level)
  • hrule()
  • list(contents, list_type)
  • list_item(text, list_type)
  • paragraph(text)
  • table(header, body)
  • table_row(content)
  • table_cell(content, alignment)

Spanレベルの呼び出し

戻り値nilはデータを何も出力しません。ドキュメント要素に対するメソッドが実装されていない場合、spanの内容はそのままコピーされます。

  • autolink(link, link_type)
  • codespan(code)
  • double_emphasis(text)
  • emphasis(text)
  • image(link, title, alt_text)
  • linebreak()
  • link(link, title, content)
  • raw_html(raw_html)
  • triple_emphasis(text)
  • strikethrough(text)
  • superscript(text)
  • underline(text)
  • highlight(text)
  • quote(text)
  • footnote_ref(number)

注意：レンダラメソッドをオーバーライドする時は、必ずそのメソッドのレベルに一致するレベルのHTML要素を返してください（例：ブロックレベル呼び出しをオーバーライドする時はブロック要素を返します）。そうしなければ、意図しない出力になる可能性があります。

低レベルのレンダリング

  • entity(text)
  • normal_text(text)

ドキュメントのヘッダ

他の要素の前にレンダリングされます。

  • doc_header()

ドキュメントのフッタ

他の要素の後にレンダリングされます。

  • doc_footer()

前処理／後処理

特別なコールバックです。レンダリング処理の開始前後に全ドキュメントを前処理または後処理します。

  • preprocess(full_document)
  • postprocess(full_document)

より詳しい説明は、"How to extend the Redcarpet 2 Markdown library?"で確認できます。

ズボンがさらにかっこよくなります


Redcarpet 2には単独で動作するSmartyPants実装があり、オリジナルの実装に完全に準拠しています。存在するパーサとしては、桁違いに最速のSmartyPantsパーサです。

このSmartyPantsパーサは、Redcarpet::Render::SmartyPantsにあります。モジュールとして実装されているので、単独でもミックスインとしても使用可能です。

任意のRendererクラスにミックスインすると、レンダリングの完了後にSmartyPantsによる置換を実行するために、postprocessメソッドをオーバーライドします。

# Mixin
class HTMLWithPants < Redcarpet::Render::HTML
  include Redcarpet::Render::SmartyPants
end

# Standalone
Redcarpet::Render::SmartyPants.render("<p>Oh SmartyPants, you're so crazy...</p>")

SmartyPantsは、すでにレンダリングされたHTMLに対して動作します。HTMLタグの中身や、<code>や<pre>のような特定のHTMLブロックの内容を置換しません。

退屈な法律のこと


Copyright (c) 2011-2013, Vicent Martí

Permission to use, copy, modify, and/or distribute this software for anypurpose with or without fee is hereby granted, provided that the abovecopyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIESWITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OFMERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FORANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGESWHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN ANACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OFOR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
投稿者 時刻:
ラベル: ,

0 件のコメント:

コメントを投稿

登録: コメントの投稿 (Atom)