RubyGems - pseudohikiparser - Versions diffs - 0.0.0.14.develop → 0.0.1 - Mend

pseudohikiparser 0.0.0.14.develop → 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

checksums.yaml +4 -4
data/README.ja.md +435 -0
data/README.md +187 -79
data/lib/pseudohiki/blockparser.rb +27 -64
data/lib/pseudohiki/htmlformat.rb +0 -24
data/lib/pseudohiki/markdownformat.rb +3 -9
data/lib/pseudohiki/version.rb +1 -1
data/lib/pseudohikiparser.rb +0 -2
data/test/test_blockparser.rb +0 -29
data/test/test_htmlformat.rb +0 -63
data/test/test_markdownformat.rb +7 -60
metadata +5 -5
data/lib/pseudohiki/sinatra_helpers.rb +0 -23

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 687d3c71781413308c05437bee7de9ca5ade7370
-  data.tar.gz: 3a8e171f56796ba47882fefccb04ec78e8ba1499
+  metadata.gz: 7908f80b410e064b7380cee7982c351257e578cd
+  data.tar.gz: 193bb4b76c97e2936a87f1f6da83cbc42ee788db
 SHA512:
-  metadata.gz: 3d3935e24ba70e03f0e12cd60360e4b01e210e101ac8bcecc6e044003322b77c25eef6bdba9ed083e45c0a816e09faf73541f358521b1b2c96345ca543b1d057
-  data.tar.gz: 1d2fd247886b2c24594db8f5df51620242b661d97966bdb1ea5012cc04482f2168f2c6b8ce5503927c24a2fea3b31520cbf54b7ba3986391f0187b8e04a5df68
+  metadata.gz: 02659c1d1e708819e9b1ed50cf65a89c348ff2c92a840daee52bb8e32d70dd0c6b4af2ab8a090ecce06557811274a9f763fec897da174193603421de3e736ff8
+  data.tar.gz: 24e068590d29996d995de41bac263451a4eb994d1241a61d27626934914ad59de3286466b0c135ac7cf634ac220c984800574efa59124d712a7beb4f9bbf717d

data/README.ja.md ADDED Viewed

@@ -0,0 +1,435 @@
+PseudoHikiParser
+================
+PseudoHikiParserは[Hiki](http://hikiwiki.org/en/)に似た記法で書かれたテキストをHTMLその他のファイル形式に変換するコンバータです。
+このツールは次の目的を念頭において作成中です。
+* オリジナルのHiki記法にはない特徴を付け加える
+  * より行指向を徹底する
+  * 見出しのような要素にid属性を付けられるようにする
+* HTML以外のファイル形式をサポートする
+  * 実装にあたってVisitorパターンを採用したため、新たなファイル形式を追加するのに必要なのは(願わくは)Visitorクラスを用意することだけです。
+なお、オリジナルのHiki記法との互換性はなくなります。
+## ライセンス
+2条項BSDライセンスです。
+## インストール
+```
+gem install pseudohikiparser
+```
+もし実験的な機能も試してみたければ、
+```
+gem install pseudohikiparser --pre
+```
+## 使い方
+### サンプル
+* Hiki記法で書かれた[テキストのサンプル](https://github.com/nico-hn/PseudoHikiParser/blob/develop/samples/wikipage.txt)
+その変換結果:
+* [HTML 4.01](http://htmlpreview.github.com/?https://github.com/nico-hn/PseudoHikiParser/blob/develop/samples/wikipage.html)
+* [XHTML 1.0](http://htmlpreview.github.com/?https://github.com/nico-hn/PseudoHikiParser/blob/develop/samples/wikipage_with_toc.html)
+* [HTML5](http://htmlpreview.github.com/?https://github.com/nico-hn/PseudoHikiParser/blob/develop/samples/wikipage_html5_with_toc.html)
+* [GFM](https://github.com/nico-hn/PseudoHikiParser/blob/develop/samples/wikipage.md)
+このサンプルは[develop branch](https://github.com/nico-hn/PseudoHikiParser/tree/develop/samples)に置いてあります。
+### pseudohiki2html.rb
+_(pseudohiki2html.rbは現時点ではPseudoHikiParserの利用例として提供されており、現段階ではオプションも継続的に変更されることにご注意ください。)_
+インストールが終わると**pseudohiki2html.rb**というコマンドが使えるようになります。
+コマンドラインで次のように入力すると
+```
+pseudohiki2html.rb <<TEXT
+!! The first heading
+The first paragraph
+TEXT
+```
+下のような結果が返ってくるはずです。
+```html
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+  "http://www.w3.org/TR/html4/loose.dtd">
+<html lang="en">
+<head>
+<meta content="en" http-equiv="Content-Language">
+<meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
+<meta content="text/javascript" http-equiv="Content-Script-Type">
+<title>-</title>
+<link href="default.css" rel="stylesheet" type="text/css">
+</head>
+<body>
+<div class="section h2">
+<h2> The first heading
+</h2>
+<p>
+The first paragraph
+</p>
+<!-- end of section h2 -->
+</div>
+</body>
+</html>
+```
+`--output`オプションを使ってファイル名を指定した場合は
+```
+pseudohiki2html.rb --output first_example.html <<TEXT
+!! The first heading
+The first paragraph
+TEXT
+```
+で、結果がfirst\_example.htmlに保存されます。
+その他のオプションについては`pseudohiki2html.rb --help`でご参照ください。
+#### 非互換な変更
+version 0.0.0.9.developから、コマンドラインのオプション名を以下の通り変更しています。
+|元の名前           |新しい名前            |注記                                                         |
+|---------------|-----------------|-----------------------------------------------------------|
+|-f             |-F               |'-f' is now used as the short version of '--format-version'|
+|-h             |-f               |'-h' is now used as the short version of '--help'          |
+|--html\_version|--format-version |other formats than html should be supported                |
+|--encoding     |--format-encoding|'--encoding' is now used as the long version of '-E' option|
+|-              |--encoding       |now same as '-E' option of MRI                             |
+### PseudoHiki::BlockParserクラス
+PseudoHiki::BlockParserのクラスメソッド parseは入力から構文木を生成し、Visitorクラスでその木を別の形式に変換します。
+以下の内容をファイルに保存・実行すると
+```ruby
+#!/usr/bin/env ruby
+require 'pseudohikiparser'
+hiki_text = <<TEXT
+!! The first heading
+The first paragraph
+TEXT
+tree = PseudoHiki::BlockParser.parse(hiki_text)
+html = PseudoHiki::HtmlFormat.format(tree)
+puts html
+```
+次のように出力されます。
+```html
+<div class="section h2">
+<h2> The first heading
+</h2>
+<p>
+The first paragraph
+</p>
+<!-- end of section h2 -->
+</div>
+```
+この例では、HtmlFormatがVisitorクラスで、構文木をHTML4.01形式に変換しています。
+HtmlFormat以外にはXhtmlFormat、Xhtml5Format、PlainTextFormat、MarkDownFormatが用意されています。
+### PseudoHiki::Formatクラス
+PseudoHiki::BlockParser.parseで作られた構文木を使い回す必要がなければ、以下のPseudoHiki::Formatのクラスメソッドも利用可能です。
+|メソッド名       |変換結果                    |
+|------------|------------------------|
+|to\_html    |HTML 4.01               |
+|to\_xhtml   |XHTML 1.0               |
+|to\_html5   |HTML 5                  |
+|to\_plain   |修飾なしのテキスト               |
+|to\_markdown|Markdown                |
+|to\_gfm     |Github Flavored Markdown|
+例えば次のスクリプトは[PseudoHiki::BlockParserクラス](#pseudohikiblockparserクラス)の例と同じ結果を返します。
+```ruby
+#!/usr/bin/env ruby
+require 'pseudohikiparser'
+hiki_text = <<TEXT
+!! The first heading
+The first paragraph
+TEXT
+puts PseudoHiki::Format.to_html(hiki_text)
+```
+## オリジナルの[Hiki記法](http://rabbit-shocker.org/en/hiki.html)にある機能の実装状況
+* パラグラフ - 使いものになる
+* リンク
+  * WikiNames - 未サポート(実装予定なし)
+  * ページへのリンク - これも未サポート
+  * 任意のURLへのリンク - 一応使えるはず
+* 整形済みテキスト - 使いものになる
+* 文字の修飾 - 一部をサポート
+  * インライン修飾用タグのエスケープ手段は実験的なもの
+  * バッククォートタグ(``)による等幅表示の記法は\<tt\>要素ではなく\<code\>要素に変換される
+* 見出し - 使いものになる
+* 水平線 - 使いものになる
+* 箇条書き - 使いものになる
+* 引用 - 使いものになる
+* 用語解説 - 使いものになる
+* 表 - 使いものになる
+* コメント行 - 使いものになる
+* プラグイン - 未サポート (オリジナルのHikiとは非互換になる予定)
+## オリジナルのHiki記法にはない特徴
+### id属性の付与
+下の例のように、見出しもしくはリストを示す記号の直後に[name\_of\_id]を付けると、その値が変換後のHTML要素のid属性になります。
+```
+!![heading_id]heading
+*[list_id]list
+```
+は次のように変換されます。
+```html
+<div class="section h2">
+<h2 id="HEADING_ID">heading
+</h2>
+<ul>
+<li id="LIST_ID">list
+</li>
+</ul>
+<!-- end of section h2 -->
+</div>
+```
+### インライン修飾用タグのエスケープ
+_(これは実験的な機能ですのでご注意ください。)_
+インライン修飾用のタグはプラグイン用のタグに入れることでエスケープできます。
+```
+For example, {{''}} and {{==}} can be escaped.
+And {{ {}} and {{} }} should be rendered as two left curly braces and two right curly braces respectively.
+```
+は次のように変換されます。
+```
+For example, '' or == can be escaped.
+And {{ and }} sould be rendered as two left curly braces and two right curly braces respectively.
+```
+### リンク用タグの入れ子
+リンク用タグが他のリンク用タグの中に入れ子になっている場合、外側のタグは画像へのurlを指定していても常にリンクとして扱われます。
+そのため下の例のように、サムネイル画像からリンクを張ることも可能です。
+```
+[[[[thumbnail of an image|http://www.example.org/image_thumb.png]]|http://www.example.org/image.png]]
+```
+は次のように変換されます。
+```html
+<a href="http://www.example.org/image.png"><img alt="thumbnail of an image" src="http://www.example.org/image_thumb.png">
+</a></p>
+```
+### 実験的な機能
+以下の機能は実験的なもので、[developブランチ](https://github.com/nico-hn/PseudoHikiParser/tree/develop)でのみ利用可能です。
+#### ブロック用のデコレータ
+'//@'で始まる行を使って、その後に続くブロックに属性を付与することができます。
+例えば
+```
+//@class[class_name]
+!!A section with a class name
+paragraph
+```
+は次のように変換されます。
+```html
+<div class="class_name">
+<h2>A section with a class name
+</h2>
+<p>
+paragraph
+</p>
+<!-- end of class_name -->
+</div>
+```
+### 未実装の機能
+## Visitorクラス
+以下のクラスのうちの一部は、部分的にしか実装されていないかテストが十分ではないことにご注意ください。
+### [HtmlFormat](https://github.com/nico-hn/PseudoHikiParser/blob/develop/lib/pseudohiki/htmlformat.rb#L8), [XhtmlFormat](https://github.com/nico-hn/PseudoHikiParser/blob/develop/lib/pseudohiki/htmlformat.rb#L263)
+これらのクラスのクラスメソッド(HtmlFormat|XhtmlFormat).formatは[HtmlElement](https://github.com/nico-hn/PseudoHikiParser/blob/develop/lib/htmlelement.rb)オブジェクトを木にしたものを返すため、以下の例のように後から手を加えることができます。
+```ruby
+#!/usr/bin/env ruby
+require 'pseudohikiparser'
+hiki_text = <<HIKI
+!! heading
+paragraph 1 that contains [[a link to a html file|http://www.example.org/example.html]]
+paragraph 2 that contains [[a link to a pdf file|http://www.example.org/example.pdf]]
+HIKI
+html = HtmlFormat.format(hiki_text)
+html.traverse do |elm|
+  if elm.kind_of? HtmlElement and elm.tagname == "a"
+    elm["class"] = "pdf" if /\.pdf\Z/o =~ elm["href"]
+  end
+end
+puts html.to_s
+```
+は次のように出力します。
+```html
+<div class="section h2">
+<h2> heading
+</h2>
+<p>
+paragraph 1 that contains <a href="http://www.example.org/example.html">a link to a html file</a>
+</p>
+<p>
+paragraph 2 that contains <a class="pdf" href="http://www.example.org/example.pdf">a link to a pdf file</a>
+</p>
+<!-- end of section h2 -->
+</div>
+```
+### [Xhtml5Format](https://github.com/nico-hn/PseudoHikiParser/blob/develop/lib/pseudohiki/htmlformat.rb#L268)
+HTML5への変換用のVisitorクラスです。
+現時点では\<section\>要素の扱い以外に[XhtmlFormat](https://github.com/nico-hn/PseudoHikiParser/blob/develop/lib/pseudohiki/htmlformat.rb#L263)との違いは余りありません。
+### [PlainTextFormat](https://github.com/nico-hn/PseudoHikiParser/blob/develop/lib/pseudohiki/plaintextformat.rb)
+Hiki記法のマークアップを除去するためのVisitorクラスで、使用例は以下の通りです。
+```
+:tel:03-xxxx-xxxx
+::03-yyyy-yyyy
+:fax:03-xxxx-xxxx
+```
+will be rendered as
+```
+tel:	03-xxxx-xxxx
+	03-yyyy-yyyy
+fax:	03-xxxx-xxxx
+```
+また
+```
+||cell 1-1||>>cell 1-2,3,4||cell 1-5
+||cell 2-1||^>cell 2-2,3 3-2,3||cell 2-4||cell 2-5
+||cell 3-1||cell 3-4||cell 3-5
+||cell 4-1||cell 4-2||cell 4-3||cell 4-4||cell 4-5
+```
+は次のように変換されます。
+```
+cell 1-1	cell 1-2,3,4	==	==	cell 1-5
+cell 2-1	cell 2-2,3 3-2,3	==	cell 2-4	cell 2-5
+cell 3-1	||	||	cell 3-4	cell 3-5
+cell 4-1	cell 4-2	cell 4-3	cell 4-4	cell 4-5
+```
+### [MarkDownFormat](https://github.com/nico-hn/PseudoHikiParser/blob/develop/lib/pseudohiki/markdownformat.rb)
+(Git Flavored) Markdownへの変換用のVisitorクラスですが、まだ実験段階です。
+以下がサンプルのスクリプトとその出力結果です。
+```ruby
+#!/usr/bin/env ruby
+require 'pseudohiki/markdownformat'
+md = PseudoHiki::MarkDownFormat.create
+gfm = PseudoHiki::MarkDownFormat.create(gfm_style: true)
+hiki = <<TEXT
+!! The first heading
+The first paragraph
+||!header 1||!header 2
+||''cell 1''||cell2
+TEXT
+tree = PseudoHiki::BlockParser.parse(hiki)
+md_text = md.format(tree).to_s
+gfm_text = gfm.format(tree).to_s
+puts md_text
+puts "--------------------"
+puts gfm_text
+```
+(出力結果)
+```
+## The first heading
+The first paragraph
+<table>
+<tr><th>header 1</th><th>header 2</th></tr>
+<tr><td><em>cell 1</em></td><td>cell2</td></tr>
+</table>
+--------------------
+## The first heading
+The first paragraph
+|header 1|header 2|
+|--------|--------|
+|_cell 1_|cell2   |
+```

data/README.md CHANGED Viewed

@@ -1,9 +1,7 @@
 PseudoHikiParser
 ================
-PseudoHikiParser is a converter of texts written in a [Hiki](http://hikiwiki.org/en/) like notation, into html or other formats.
-Currently, only a limited range of notations can be converted into HTML4 or XHTML1.0.
+PseudoHikiParser is a converter of texts written in a [Hiki](http://hikiwiki.org/en/) like notation, into HTML or other formats.
 I am writing this tool with following objectives in mind,
@@ -21,6 +19,12 @@ BSD 2-Clause License
 ## Installation
+```
+gem install pseudohikiparser
+```
+or if you also want to try out experimental features,
 ```
 gem install pseudohikiparser --pre
 ```
@@ -29,17 +33,24 @@ gem install pseudohikiparser --pre
 ### Samples
-[A sample text](https://github.com/nico-hn/PseudoHikiParser/blob/develop/samples/wikipage.txt) in Hiki notation and [a result of conversion](http://htmlpreview.github.com/?https://github.com/nico-hn/PseudoHikiParser/blob/develop/samples/wikipage.html), [another result of conversion](http://htmlpreview.github.com/?https://github.com/nico-hn/PseudoHikiParser/blob/develop/samples/wikipage_with_toc.html) and [yet another result](http://htmlpreview.github.com/?https://github.com/nico-hn/PseudoHikiParser/blob/develop/samples/wikipage_html5_with_toc.html).
+* [A sample text](https://github.com/nico-hn/PseudoHikiParser/blob/develop/samples/wikipage.txt) in Hiki notation
+And results of conversion
-You will find those samples in [develop branch](https://github.com/nico-hn/PseudoHikiParser/tree/develop/samples).
+* [HTML 4.01](http://htmlpreview.github.com/?https://github.com/nico-hn/PseudoHikiParser/blob/develop/samples/wikipage.html)
+* [XHTML 1.0](http://htmlpreview.github.com/?https://github.com/nico-hn/PseudoHikiParser/blob/develop/samples/wikipage_with_toc.html)
+* [HTML5](http://htmlpreview.github.com/?https://github.com/nico-hn/PseudoHikiParser/blob/develop/samples/wikipage_html5_with_toc.html)
+* [GFM](https://github.com/nico-hn/PseudoHikiParser/blob/develop/samples/wikipage.md)
+You will find these samples in [develop branch](https://github.com/nico-hn/PseudoHikiParser/tree/develop/samples).
 ### pseudohiki2html.rb
-After the installation of PseudoHikiParser, you could use a command: **pseudohiki2html.rb**.
+_(Please note that pseudohiki2html.rb is currently provided as a showcase of PseudoHikiParser, and the options will be continuously changed at this stage of development.)_
-_Please note that pseudohiki2html.rb is currently provided as a showcase of PseudoHikiParser, and the options will be continuously changed at this stage of development._
+After the installation of PseudoHikiParser, you can use a command: **pseudohiki2html.rb**.
-Typing the following lines at the command prompt:
+Type the following lines at the command prompt:
 ```
 pseudohiki2html.rb <<TEXT
@@ -48,7 +59,7 @@ The first paragraph
 TEXT
 ```
-will return the following result to stdout:
+And it will return the following result to stdout:
 ```html
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
@@ -83,13 +94,13 @@ The first paragraph
 TEXT
 ```
-the result will be saved in first_example.html.
+the result will be saved in first\_example.html.
 For more options, please try `pseudohiki2html.rb --help`
 #### Incompatible changes
-From version 0.0.0.9, command line options are renamed as follows:
+From version 0.0.0.9.develop, command line options are renamed as follows:
 |old name       |new name         |note                                                       |
 |---------------|-----------------|-----------------------------------------------------------|
@@ -99,7 +110,9 @@ From version 0.0.0.9, command line options are renamed as follows:
 |--encoding     |--format-encoding|'--encoding' is now used as the long version of '-E' option|
 |-              |--encoding       |now same as '-E' option of MRI                             |
-### module PseudoHiki
+### class PseudoHiki::BlockParser
+A class method PseudoHiki::BlockParser.parse composes a syntax tree from its input, and a visitor class converts the tree into a certain format.
 If you save the lines below as a ruby script and execute it:
@@ -108,12 +121,12 @@ If you save the lines below as a ruby script and execute it:
 require 'pseudohikiparser'
-plain = <<TEXT
+hiki_text = <<TEXT
 !! The first heading
 The first paragraph
 TEXT
-tree = PseudoHiki::BlockParser.parse(plain.lines.to_a)
+tree = PseudoHiki::BlockParser.parse(hiki_text)
 html = PseudoHiki::HtmlFormat.format(tree)
 puts html
 ```
@@ -131,7 +144,37 @@ The first paragraph
 </div>
 ```
-Other than PseudoHiki::HtmlFormat, you can choose PseudoHiki::XhtmlFormat, PseudoHiki::Xhtml5Format, PseudoHiki::PlainTextFormat.
+In the example above, HtmlFormat is a visitor class that converts the parsed text into HTML 4.01 format.
+Other than HtmlFormat, XhtmlFormat, Xhtml5Format, PlainTextFormat and MarkDownFormat are available.
+### class PseudoHiki::Format
+If you don't need to reuse a tree parsed by PseudoHiki::BlockParser.parse, you can use following class methods of PseudoHiki::Format.
+|Method name |Result of conversion    |
+|------------|------------------------|
+|to\_html    |HTML 4.01               |
+|to\_xhtml   |XHTML 1.0               |
+|to\_html5   |HTML 5                  |
+|to\_plain   |plain text              |
+|to\_markdown|Markdown                |
+|to\_gfm     |Github Flavored Markdown|
+For example, the script below returns the same result as the example of [PseudoHiki::BlockParser](#class-pseudohikiblockparser)
+```ruby
+#!/usr/bin/env ruby
+require 'pseudohikiparser'
+hiki_text = <<TEXT
+!! The first heading
+The first paragraph
+TEXT
+puts PseudoHiki::Format.to_html(hiki_text)
+```
 ## Development status of features from the original [Hiki notation](http://rabbit-shocker.org/en/hiki.html)
@@ -142,7 +185,7 @@ Other than PseudoHiki::HtmlFormat, you can choose PseudoHiki::XhtmlFormat, Pseud
   * Linking to an arbitrary URL - Maybe usable
 * Preformatted text - Usable
 * Text decoration - Partly supported
-  * Means of escaping tags for inline decorations is only experimetal.
+  * Means of escaping tags for inline decorations is just experimetal.
   * The notation for inline literals by backquote tags(``) is converted into not \<tt\> element but \<code\> element.
 * Headings - Usable
 * Horizontal lines - Usable
@@ -155,11 +198,9 @@ Other than PseudoHiki::HtmlFormat, you can choose PseudoHiki::XhtmlFormat, Pseud
 ## Additional Features
-### Already Implemented
+### Assigning ids
-#### Assigning ids
-If you add [name_of_id], just after the marks that denote heading or list type items, it becomes the id attribute of resulting html elements. Below is an example.
+If you add [name\_of\_id], just after the marks that denote heading or list type items, it becomes the id attribute of resulting html elements. Below is an example.
 ```
 !![heading_id]heading
@@ -181,11 +222,130 @@ will be rendered as
 </div>
 ```
-### Partly Implemented
+### Escaping tags for inline decorations
+_(Please note that this is just an experimental feature.)_
+Tags for inline decorations are escaped when they are enclosed in plugin tags:
+```
+For example, {{''}} and {{==}} can be escaped.
+And {{ {}} and {{} }} should be rendered as two left curly braces and two right curly braces respectively.
+```
+will be rendered as
+```
+For example, '' or == can be escaped.
+And {{ and }} sould be rendered as two left curly braces and two right curly braces respectively.
+```
+### Nesting of link tags
-#### A visitor that removes markups and returns plain texts
+If a link tag is nested inside another link tag, the outer tag is always treated as a link even when its url is for an image.
-The visitor, [PlainTextFormat](https://github.com/nico-hn/PseudoHikiParser/blob/develop/lib/pseudohiki/plaintextformat.rb) is currently available only in the [develop branch](https://github.com/nico-hn/PseudoHikiParser/tree/develop). Below are examples
+So you can make a link from a thumbnail as in the following example.
+```
+[[[[thumbnail of an image|http://www.example.org/image_thumb.png]]|http://www.example.org/image.png]]
+```
+will be rendered as
+```html
+<a href="http://www.example.org/image.png"><img alt="thumbnail of an image" src="http://www.example.org/image_thumb.png">
+</a></p>
+```
+### Experimental
+The following feature is just experimental and available only in [develop branch](https://github.com/nico-hn/PseudoHikiParser/tree/develop).
+#### Decorator for blocks
+By lines that begin with '//@', you can assign certain attributes to its succeeding block.
+For example,
+```
+//@class[class_name]
+!!A section with a class name
+paragraph
+```
+will be renderes as
+```html
+<div class="class_name">
+<h2>A section with a class name
+</h2>
+<p>
+paragraph
+</p>
+<!-- end of class_name -->
+</div>
+```
+### Not Implemented Yet
+## Visitor classes
+Please note that some of the following classes are implemented partly or not tested well.
+### [HtmlFormat](https://github.com/nico-hn/PseudoHikiParser/blob/develop/lib/pseudohiki/htmlformat.rb#L8), [XhtmlFormat](https://github.com/nico-hn/PseudoHikiParser/blob/develop/lib/pseudohiki/htmlformat.rb#L263)
+Their class method (HtmlFormat|XhtmlFormat).format returns a tree of [HtmlElement](https://github.com/nico-hn/PseudoHikiParser/blob/develop/lib/htmlelement.rb) objects, and you can traverse the tree as in the following example.
+```ruby
+#!/usr/bin/env ruby
+require 'pseudohikiparser'
+hiki_text = <<HIKI
+!! heading
+paragraph 1 that contains [[a link to a html file|http://www.example.org/example.html]]
+paragraph 2 that contains [[a link to a pdf file|http://www.example.org/example.pdf]]
+HIKI
+html = HtmlFormat.format(hiki_text)
+html.traverse do |elm|
+  if elm.kind_of? HtmlElement and elm.tagname == "a"
+    elm["class"] = "pdf" if /\.pdf\Z/o =~ elm["href"]
+  end
+end
+puts html.to_s
+```
+will print
+```html
+<div class="section h2">
+<h2> heading
+</h2>
+<p>
+paragraph 1 that contains <a href="http://www.example.org/example.html">a link to a html file</a>
+</p>
+<p>
+paragraph 2 that contains <a class="pdf" href="http://www.example.org/example.pdf">a link to a pdf file</a>
+</p>
+<!-- end of section h2 -->
+</div>
+```
+### [Xhtml5Format](https://github.com/nico-hn/PseudoHikiParser/blob/develop/lib/pseudohiki/htmlformat.rb#L268)
+This visitor is for HTML5.
+Currently there aren't many differences with [XhtmlFormat](https://github.com/nico-hn/PseudoHikiParser/blob/develop/lib/pseudohiki/htmlformat.rb#L263) exept for the treatment of \<section\> elements.
+### [PlainTextFormat](https://github.com/nico-hn/PseudoHikiParser/blob/develop/lib/pseudohiki/plaintextformat.rb)
+This visitor removes markups from its input and returns plain texts. Below are examples
 ```
 :tel:03-xxxx-xxxx
@@ -219,15 +379,9 @@ cell 3-1	||	||	cell 3-4	cell 3-5
 cell 4-1	cell 4-2	cell 4-3	cell 4-4	cell 4-5
 ```
-#### A visitor for HTML5
-The visitor, [Xhtml5Format](https://github.com/nico-hn/PseudoHikiParser/blob/develop/lib/pseudohiki/htmlformat.rb#L239) is currently available only in the [develop branch](https://github.com/nico-hn/PseudoHikiParser/tree/develop).
-#### A visitor for (Git Flavored) Markdown
-The visitor, [MarkDownFormat](https://github.com/nico-hn/PseudoHikiParser/blob/develop/lib/pseudohiki/markdownformat.rb) too, is currently available only in the [develop branch](https://github.com/nico-hn/PseudoHikiParser/tree/develop/).
+### [MarkDownFormat](https://github.com/nico-hn/PseudoHikiParser/blob/develop/lib/pseudohiki/markdownformat.rb)
-It's just in experimental stage.
+This visitor is for (Git Flavored) Markdown and just in experimental stage.
 The following are a sample script and its output:
@@ -253,7 +407,7 @@ tree = PseudoHiki::BlockParser.parse(hiki)
 md_text = md.format(tree).to_s
 gfm_text = gfm.format(tree).to_s
 puts md_text
-puts "===================="
+puts "--------------------"
 puts gfm_text
 ```
@@ -269,7 +423,7 @@ The first paragraph
 <tr><td><em>cell 1</em></td><td>cell2</td></tr>
 </table>
-====================
+--------------------
 ## The first heading
 The first paragraph
@@ -279,49 +433,3 @@ The first paragraph
 |_cell 1_|cell2   |
 ```
-### Experimental
-#### Escaping tags for inline decorations
-Tags for inline decorations are escaped when they are enclosed in plugin tags:
-```
-For example, {{''}} and {{==}} can be escaped.
-And {{ {}} and {{} }} should be rendered as two left curly braces and two right curly braces respectively.
-```
-will be rendered as
-```
-For example, '' or == can be escaped.
-And {{ and }} sould be rendered as two left curly braces and two right curly braces respectively.
-```
-#### Decorator for blocks
-By lines that begin with '//@', you can assign certain attributes to its succeeding block.
-For example,
-```
-//@class[class_name]
-!!A section with a class name
-paragraph
-```
-will be renderes as
-```html
-<div class="class_name">
-<h2>A section with a class name
-</h2>
-<p>
-paragraph
-</p>
-<!-- end of class_name -->
-</div>
-```
-### Not Implemented Yet