[DOCUMENTATION] Japanese new Zend_Markup . Thanks to Sasezaki

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@20213 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/ja/module_specs/Zend_Markup-Getting-Started.xml

@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<!-- EN-Revision: 19777 -->
+<sect1 id="zend.markup.getting-started">
+    <title>さあ始めましょう</title>
+ 
+    <para>
+        これは <classname>Zend_Markup</classname> BBCode パーサーと <acronym>HTML</acronym>
+        レンダラーを用いる <classname>Zend_Markup</classname> を始めるためのガイドです。
+        他のパーサーやレンダラーに適用できる原則です。
+    </para>
+ 
+    <example id="zend.markup.getting-started.basic-usage">
+        <title>基本的な Zend_Markup 使用法</title>
+ 
+        <para>
+            まず初めに <methodname>Zend_Markup::factory()</methodname> メソッドを用いて、
+            <classname>Zend_Markup_Renderer_Html</classname> オブジェクトを具象化します。
+            <classname>Zend_Markup_Parser_Bbcode</classname> オブジェクトがレンダラーに
+            追加され作成されるでしょう。
+        </para>
+ 
+        <para>
+         その後、 <methodname>render()</methodname> メソッドを BBCode から
+         <acronym>HTML</acronym> の断片に変換するために使用します。
+        </para>
+ 
+        <programlisting language="php"><![CDATA[
+// Zend_Markup_Parser_BbCode を自身のパーサーとして、
+// Zend_Markup_Renderer_Html のインスタンスを生成します。
+$bbcode = Zend_Markup::factory('Bbcode');
+ 
+echo $bbcode->render('[b]bold text[/b] and [i]cursive text[/i]');
+// 出力: '<strong>bold text</strong> and <em>cursive text</em>'
+]]></programlisting>
+    </example>
+ 
+    <example id="zend.markup.getting-started.complicated-example">
+        <title>Zend_Markup のより複雑な例</title>
+ 
+        <para>
+            今回、上記と同様なことを正確に行いますが、より複雑な BBCode の例です。
+        </para>
+ 
+        <programlisting language="php"><![CDATA[
+$bbcode = Zend_Markup::factory('Bbcode');
+ 
+$input = <<<EOT
+[list]
+[*]Zend Framework
+[*]Foobar
+[/list]
+EOT;
+ 
+echo $bbcode->render($input);
+/*
+このように出力されるはずです:
+<ul>
+<li>Zend Framework</li>
+<li>Foobar</li>
+</ul>
+*/
+]]></programlisting>
+    </example>
+ 
+    <example id="zend.markup.getting-started.incorrect-input">
+        <title>不正確な入力でのプロセス</title>
+ 
+        <para>
+            BBCode のようなマークアップの簡潔な解析とレンダリングの側面から、
+            <classname>Zend_Markup</classname> は誤った入力も扱えます。大抵の BBCode
+            処理機構は全ての入力に対し <acronym>XHTML</acronym> での正しい出力を行えません。
+            <classname>Zend_Markup</classname> は、
+            不正確なネストや閉じられていない閉じタグを訂正します:
+        </para>
+ 
+        <programlisting language="php"><![CDATA[
+$bbcode = Zend_Markup::factory('Bbcode');
+ 
+echo $bbcode->render('some [i]wrong [b]sample [/i] text');
+// '[b]' は決して閉じられておらず、また不正確にネストされていることに注意しましょう。
+// それにもかかわらず、 Zend_Markup は以下のように正確にレンダリングします:
+// some <em>wrong <strong>sample </strong></em><strong> text</strong>
+]]></programlisting>
+    </example>
+</sect1>

documentation/manual/ja/module_specs/Zend_Markup-Parsers.xml

@@ -0,0 +1,226 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<!-- EN-Revision: 19777 -->
+<sect1 id="zend.markup.parsers">
+    <title>Zend_Markup パーサー</title>
+ 
+    <para>
+        <classname>Zend_Markup</classname> には現在 BBCode パーサーと Textile パーサー
+        という２つのパーサーが同梱されています。
+    </para>
+ 
+    <sect2 id="zend.markup.parsers.theory">
+        <title>パーサーの仕組み</title>
+ 
+        <para>
+            <classname>Zend_Markup</classname> のパーサは、マークアップによる文をトークン木へと
+            変換するクラス群です。ここの例では BBCode パーサーを用いますが、
+            全てのパーサーにおいてトークン木の見解は変わりません。
+            例として BBCode のこの要素で始めます:
+        </para>
+ 
+        <programlisting><![CDATA[
+[b]foo[i]bar[/i][/b]baz
+]]></programlisting>
+ 
+        <para>
+            BBCode パーサーは、要素を分離し以下の木構造を生成した値を持つことでしょう:
+        </para>
+ 
+        <itemizedlist>
+            <listitem>
+                <para>[b]</para>
+ 
+                <itemizedlist>
+                    <listitem>
+                        <para>foo</para>
+                    </listitem>
+ 
+                    <listitem>
+                        <para>[i]</para>
+ 
+                        <itemizedlist>
+                            <listitem>
+                                <para>bar</para>
+                            </listitem>
+                        </itemizedlist>
+                    </listitem>
+                </itemizedlist>
+            </listitem>
+ 
+            <listitem>
+                <para>baz</para>
+            </listitem>
+        </itemizedlist>
+ 
+        <para>
+            クローズタグは消えていることにお気づきになったでしょう、それらは木構造の
+            内容として出現しません。これは、クローズタグは実際の内容のものではないからです。
+            ですが、これは単にクローズタグを消失したことを意図するものではなく、
+            タグ自身のタグ情報内で保持されています。さらに、これは木構造自身の簡潔な概観で
+            あるだけということに注意してください。実際の木構造は、タグの属性とその名について
+            より多くの情報を含んでいます。
+        </para>
+    </sect2>
+ 
+    <sect2 id="zend.markup.parsers.bbcode">
+        <title>BBCode パーサー</title>
+ 
+        <para>
+            BBCode パーサーは BBCode をトークン木へ変換する
+            <classname>Zend_Markup</classname> パーサーです。 全ての BBCode タグの文法は:
+        </para>
+ 
+        <programlisting language="text"><![CDATA[
+[name(=(value|"value"))( attribute=(value|"value"))*]
+]]></programlisting>
+ 
+        <para>
+            有効な BBCode タグのいくつかの例は:
+        </para>
+ 
+        <programlisting><![CDATA[
+[b]
+[list=1]
+[code file=Zend/Markup.php]
+[url="http://framework.zend.com/" title="Zend Framework!"]
+]]></programlisting>
+ 
+        <para>
+            標準で、 '[/tagname]' フォーマットを用いて閉じられます.
+        </para>
+    </sect2>
+ 
+    <sect2 id="zend.markup.parsers.textile">
+        <title>Textile パーサー</title>
+ 
+        <para>
+            Textile パーサーは、Textile からトークン木へと変換する <classname>Zend_Markup</classname>
+            パーサーです。 Textile はタグ構造を持っていないため、
+            以下は見本例のタグのリストです:
+        </para>
+ 
+        <table id="zend.markup.parsers.textile.tags">
+            <title>基本的な Textile タグのリスト</title>
+ 
+            <tgroup cols="2" align="left" colsep="1" rowsep="1">
+                <thead>
+                    <row>
+                        <entry>入力例</entry>
+ 
+                        <entry>出力例</entry>
+                    </row>
+                </thead>
+ 
+                <tbody>
+                    <row>
+                        <entry>*foo*</entry>
+ 
+                        <entry><![CDATA[<strong>foo</strong>]]></entry>
+                    </row>
+ 
+                    <row>
+                        <entry>_foo_</entry>
+ 
+                        <entry><![CDATA[<em>foo</em>]]></entry>
+                    </row>
+ 
+                    <row>
+                        <entry>??foo??</entry>
+ 
+                        <entry><![CDATA[<cite>foo</cite>]]></entry>
+                    </row>
+ 
+                    <row>
+                        <entry>-foo-</entry>
+ 
+                        <entry><![CDATA[<del>foo</del>]]></entry>
+                    </row>
+ 
+                    <row>
+                        <entry>+foo+</entry>
+ 
+                        <entry><![CDATA[<ins>foo</ins>]]></entry>
+                    </row>
+ 
+                    <row>
+                        <entry>^foo^</entry>
+ 
+                        <entry><![CDATA[<sup>foo</sup>]]></entry>
+                    </row>
+ 
+                    <row>
+                        <entry>~foo~</entry>
+ 
+                        <entry><![CDATA[<sub>foo</sub>]]></entry>
+                    </row>
+ 
+                    <row>
+                        <entry>%foo%</entry>
+ 
+                        <entry><![CDATA[<span>foo</span>]]></entry>
+                    </row>
+ 
+                    <row>
+                        <entry>PHP(PHP Hypertext Preprocessor)</entry>
+ 
+                        <entry><![CDATA[<acronym title="PHP Hypertext Preprocessor">PHP</acronym>]]></entry>
+                    </row>
+ 
+                    <row>
+                        <entry>"Zend Framework":http://framework.zend.com/</entry>
+ 
+                        <entry><![CDATA[<a href="http://framework.zend.com/">Zend Framework</a>]]></entry>
+                    </row>
+ 
+                    <row>
+                        <entry>h1. foobar</entry>
+ 
+                        <entry><![CDATA[<h1>foobar</h1>]]></entry>
+                    </row>
+ 
+                    <row>
+                        <entry>h6. foobar</entry>
+ 
+                        <entry><![CDATA[<h6>foobar</h6>]]></entry>
+                    </row>
+ 
+                    <row>
+                        <entry>!http://framework.zend.com/images/logo.gif!</entry>
+ 
+                        <entry><![CDATA[<img src="http://framework.zend.com/images/logo.gif" />]]></entry>
+                    </row>
+                </tbody>
+            </tgroup>
+        </table>
+ 
+        <para>
+            さらに、 Textile パーサーは全てのタグを段落へとラップします;
+            段落は2行の新しい行で終わり、よりタグがあった場合、新しい段落が加えられます。
+        </para>
+ 
+        <sect3 id="zend.markup.parsers.textile.lists">
+            <title>リスト</title>
+ 
+            <para>
+                Textile パーサーは2種類のリストをサポートします。"#"記号を用いた数値型と
+                "*"記号を用いた <!-- TODO : to be translated -->bullit リストです。両方のリストの例:
+            </para>
+ 
+            <programlisting><![CDATA[
+# Item 1
+# Item 2
+ 
+* Item 1
+* Item 2
+]]></programlisting>
+ 
+            <para>
+                上記は2つのリストを生成します: 一つは、数値型; 2つ目は、 <!-- TODO : to be translated -->bulleted 。
+                リスト内で、太 (*)、と 強調 (_)のように標準タグを用いることができます。タグは、
+                （'h1'などのように）新しい行にて始まっている必要があり、リスト内で用いることは
+                できません。
+            </para>
+        </sect3>
+    </sect2>
+</sect1>

documentation/manual/ja/module_specs/Zend_Markup-Renderers.xml

@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<!-- EN-Revision: 19777 -->
+<sect1 id="zend.markup.renderers">
+    <title>Zend_Markup レンダラー</title>
+ 
+    <para>
+        <classname>Zend_Markup</classname> には現在ひとつのレンダラー、
+        <acronym>HTML</acronym> レンダラーが同梱されています。
+    </para>
+ 
+    <sect2 id="zend.markup.renderers.add">
+        <title>自作のタグの追加</title>
+ 
+        <para>
+            自作のタグを追加することによって、<classname>Zend_Markup</classname> レンダラーに
+            自作の機能の追加できます。 タグ構造とともに、
+            あなたが望むいかなる機能も追加ができます。
+            簡潔なタグから複雑なタグ構造まで。 'foo' タグでの単純な例:
+        </para>
+ 
+        <programlisting language="php"><![CDATA[
+// Zend_Markup_Parser_BbCode をパーサーとして、
+// Zend_Markup_Renderer_Html のインスタンスを生成します。
+$bbcode = Zend_Markup::factory('Bbcode');
+ 
+// これは単純な 'foo' タグが作成されるでしょう
+// 第一引数は自身のタグ名を定義します。
+// 第二引数はタグの定数で定義された整数を引数に取ります。
+// 第三引数は、タグについて、タググループと(この例では)開始ならびに終了タグのように
+// 他のことを配列にて定義します。
+$bbcode->addTag(
+    'foo',
+    Zend_Markup_Renderer_RendererAbstract::TYPE_REPLACE
+        | Zend_Markup_Renderer_RendererAbstract::TAG_NORMAL,
+    array(
+        'start' => '-bar-',
+        'end'   => '-baz-',
+        'group' => 'inline',
+    )
+);
+ 
+// これは 'my -bar-tag-baz-' と出力されるでしょう。
+echo $bbcode->render('my [foo]tag[/foo]');
+]]></programlisting>
+ 
+        <para>
+            あなたの作成したタグは、あなたのパーサーがタグ構造もサポートするときに
+            機能することに注意してください。現在、 BBCode はこれをサポートします。
+            Textile はカスタムタグをサポートしません。
+        </para>
+    </sect2>
+</sect1>

documentation/manual/ja/module_specs/Zend_Markup.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<!-- EN-Revision: 19777 -->
+<sect1 id="zend.markup.introduction">
+    <title>導入</title>
+ 
+    <para>
+        <classname>Zend_Markup</classname> コンポーネントは BBcode や Textile の
+        ような軽量マークアップ言語のテキストパースならびにレンダリングのための
+        拡張方法を提供します。 Zend Framework 1.10 から利用できます。
+    </para>
+ 
+    <para>
+        <classname>Zend_Markup</classname> は <classname>Zend_Markup_Renderer_Abstract</classname>
+        を拡張したレンダラーのインスタンスを生成するファクトリーメソッドを使用します。
+        <classname>Zend_Markup_Renderer_Abstract</classname> のファクトリーメソッドは
+        ３つの引数を取ります。第一引数はテキストをトークンにするパーサーを指定します
+        (例: BbCode )。第２引数(オプション)は使用するレンダラーで、
+        デフォルトは HTML です。3つ目の引数はレンダラーで使用可能なオプションの配列です。
+    </para>
+</sect1>