|
|
@@ -0,0 +1,669 @@
|
|
|
+<?xml version="1.0" encoding="UTF-8"?>
|
|
|
+<!-- Reviewed: no -->
|
|
|
+<!-- EN-Revision: 18134 -->
|
|
|
+<appendix id="doc-standard">
|
|
|
+ <title>Zend Framework ドキュメント標準</title>
|
|
|
+
|
|
|
+ <sect1 id="doc-standard.overview">
|
|
|
+ <title>概要</title>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.overview.scope">
|
|
|
+ <title>スコープ</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ <!-- TODO : to be translated -->
|
|
|
+ This document provides guidelines for creation of the end-user
|
|
|
+ documentation found within Zend Framework. It is intended as a
|
|
|
+ guide to Zend Framework contributors, who must write
|
|
|
+ documentation as part of component contributions, as well as to
|
|
|
+ documentation translators. The standards contained herein are
|
|
|
+ intended to ease translation of documentation, minimize
|
|
|
+ visual and stylistic differences between different documentation
|
|
|
+ files, and make finding changes in documentation easier with
|
|
|
+ <command>diff</command> tools.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ You may adopt and/or modify these standards in accordance with the terms of our
|
|
|
+ <ulink url="http://framework.zend.com/license">license</ulink>.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Topics covered in Zend Framework's documentation standards include documentation
|
|
|
+ file formatting and recommendations for documentation quality.
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+ </sect1>
|
|
|
+
|
|
|
+ <sect1 id="doc-standard.file-formatting">
|
|
|
+ <title>ドキュメントファイル形式</title>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.file-formatting.xml-tags">
|
|
|
+ <title>XML タグ</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Each manual file must include the following <acronym>XML</acronym> declarations at
|
|
|
+ the top of the file:
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<?xml version="1.0" encoding="UTF-8"?>
|
|
|
+<!-- Reviewed: no -->
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ <acronym>XML</acronym> files from translated languages must also include a revision
|
|
|
+ tag containing the revision of the corresponding English-language file the
|
|
|
+ translation was based on.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<?xml version="1.0" encoding="UTF-8"?>
|
|
|
+<!-- EN-Revision: 14978 -->
|
|
|
+<!-- Reviewed: no -->
|
|
|
+]]></programlisting>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.file-formatting.max-line-length">
|
|
|
+ <title>行の最大長</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ The maximum line length, including tags, attributes, and indentation, is not to
|
|
|
+ exceed 100 characters. There is only one exception to this rule: attribute and value
|
|
|
+ pairs are allowed to exceed the 100 chars as they are not allowed to be seperated.
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.file-formatting.indentation">
|
|
|
+ <title>インデント</title>
|
|
|
+
|
|
|
+ <para>Indentation should consist of 4 spaces. Tabs are not allowed.</para>
|
|
|
+
|
|
|
+ <para>Tags which are at the same level must have the same indentation.</para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<sect1>
|
|
|
+</sect1>
|
|
|
+
|
|
|
+<sect1>
|
|
|
+</sect1>
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Tags which are one level under the previous tag must be indented with 4 additional
|
|
|
+ spaces.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<sect1>
|
|
|
+ <sect2>
|
|
|
+ </sect2>
|
|
|
+</sect1>
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Multiple block tags within the same line are not allowed; multiple inline tags are
|
|
|
+ allowed, however.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NOT ALLOWED: -->
|
|
|
+<sect1><sect2>
|
|
|
+</sect2></sect1>
|
|
|
+
|
|
|
+<!-- ALLOWED -->
|
|
|
+<para>
|
|
|
+ <classname>Zend_Magic</classname> does not exist. <classname>Zend_Acl</classname> does.
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.file-formatting.line-termination">
|
|
|
+ <title>行の終端</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Line termination follows the Unix text file convention. Lines must end with a
|
|
|
+ single linefeed (LF) character. Linefeed characters are represented as ordinal 10,
|
|
|
+ or hexadecimal 0x0A.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Note: Do not use carriage returns (<acronym>CR</acronym>) as is the convention in
|
|
|
+ Apple OS's (0x0D) or the carriage return - linefeed combination
|
|
|
+ (<acronym>CRLF</acronym>) as is standard for the Windows OS (0x0D, 0x0A).
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.file-formatting.empty-tags">
|
|
|
+ <title>空のタグ</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ 空のタグは認められません。タグは全てテキストまたは子供タグを含まなければいけません。
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NOT ALLOWED -->
|
|
|
+<para>
|
|
|
+ Some text. <link></link>
|
|
|
+</para>
|
|
|
+
|
|
|
+<para>
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.file-formatting.whitespace">
|
|
|
+ <title>ドキュメント内での空白の利用</title>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.whitespace.trailing">
|
|
|
+ <title>タグ内での空白</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ <!-- TODO : to be translated -->
|
|
|
+ Opening block tags should have no whitespace immediately following them other
|
|
|
+ than line breaks (and indentation on the following line).
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NOT ALLOWED -->
|
|
|
+<sect1>WHITESPACE
|
|
|
+</sect1>
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Opening inline tags should have no whitespace immediately following them.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NOT ALLOWED -->
|
|
|
+This is the class <classname> Zend_Class</classname>.
|
|
|
+
|
|
|
+<!-- OK -->
|
|
|
+This is the class <classname>Zend_Class</classname>.
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Closing block tags may be preceded by whitespace equivalent to the current
|
|
|
+ indentation level, but no more than that amount.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NOT ALLOWED -->
|
|
|
+ <sect1>
|
|
|
+ </sect1>
|
|
|
+
|
|
|
+<!-- OK -->
|
|
|
+ <sect1>
|
|
|
+ </sect1>
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Closing inline tags must not be preceded by any whitespace.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NOT ALLOWED -->
|
|
|
+This is the class <classname>Zend_Class </classname>
|
|
|
+
|
|
|
+<!-- OK -->
|
|
|
+This is the class <classname>Zend_Class</classname>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.whitespace.multiple-line-breaks">
|
|
|
+ <title>複数行の切断</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ 複数行内での、またはタグの間での切断は認められません。
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NOT ALLOWED -->
|
|
|
+<para>
|
|
|
+ Some text...
|
|
|
+
|
|
|
+ ... and more text
|
|
|
+</para>
|
|
|
+
|
|
|
+
|
|
|
+<para>
|
|
|
+ Another paragraph.
|
|
|
+</para>
|
|
|
+
|
|
|
+<!-- OK -->
|
|
|
+<para>
|
|
|
+ Some text...
|
|
|
+ ... and more text
|
|
|
+</para>
|
|
|
+
|
|
|
+<para>
|
|
|
+ Another paragraph.
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.whitespace.tag-separation">
|
|
|
+ <title>タグの間の分離</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ 読みやすくするために、同じレベルのタグは空行で分離しなければいけません。
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NOT ALLOWED -->
|
|
|
+<para>
|
|
|
+ Some text...
|
|
|
+</para>
|
|
|
+<para>
|
|
|
+ More text...
|
|
|
+</para>
|
|
|
+
|
|
|
+<!-- OK -->
|
|
|
+<para>
|
|
|
+ Some text...
|
|
|
+</para>
|
|
|
+
|
|
|
+<para>
|
|
|
+ More text...
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ <!-- TODO : to be translated -->
|
|
|
+ The first child tag should open directly below its parent, with no empty line
|
|
|
+ between them; the last child tag should close directly before the closing tag of
|
|
|
+ its parent.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NOT ALLOWED -->
|
|
|
+<sect1>
|
|
|
+
|
|
|
+ <sect2>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+</sect1>
|
|
|
+
|
|
|
+<!-- OK -->
|
|
|
+<sect1>
|
|
|
+ <sect2>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2>
|
|
|
+ </sect2>
|
|
|
+</sect1>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.file-formatting.program-listing">
|
|
|
+ <title>プログラム・リスティング</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ The opening <emphasis><programlisting></emphasis> tag must indicate the
|
|
|
+ appropriate "language" attribute and be indented at the same level as its sibling
|
|
|
+ blocks.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<para>Sibling paragraph.</para>
|
|
|
+
|
|
|
+<programlisting language="php">]]><<![CDATA[![CDATA[
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ <acronym>CDATA</acronym> should be used around all program listings.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ <emphasis><programlisting></emphasis> sections must not add linebreaks or
|
|
|
+ whitespace at the beginning or end of the section, as these are then represented in
|
|
|
+ the final output.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NOT ALLOWED -->
|
|
|
+<programlisting language="php">]]><<![CDATA[![CDATA[
|
|
|
+
|
|
|
+$render = "xxx";
|
|
|
+
|
|
|
+]]]]>><![CDATA[</programlisting>
|
|
|
+
|
|
|
+<!-- OK -->
|
|
|
+<programlisting language="php">]]><<![CDATA[![CDATA[
|
|
|
+$render = "xxx";
|
|
|
+]]]]>><![CDATA[</programlisting>
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Ending <acronym>CDATA</acronym> and <emphasis><programlisting></emphasis>
|
|
|
+ tags should be on the same line, without any indentation.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NOT ALLOWED -->
|
|
|
+ <programlisting language="php">]]><<![CDATA[![CDATA[
|
|
|
+$render = "xxx";
|
|
|
+]]]]>><![CDATA[
|
|
|
+ </programlisting>
|
|
|
+
|
|
|
+<!-- NOT ALLOWED -->
|
|
|
+ <programlisting language="php">]]><<![CDATA[![CDATA[
|
|
|
+$render = "xxx";
|
|
|
+ ]]]]>><![CDATA[</programlisting>
|
|
|
+
|
|
|
+<!-- OK -->
|
|
|
+ <programlisting language="php">]]><<![CDATA[![CDATA[
|
|
|
+$render = "xxx";
|
|
|
+]]]]>><![CDATA[</programlisting>
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ The <emphasis><programlisting></emphasis> tag should contain the "language"
|
|
|
+ attribute with a value appropriate to the contents of the program listing. Typical
|
|
|
+ values include "css", "html", "ini", "javascript", "php", "text", and "xml".
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- PHP -->
|
|
|
+<programlisting language="php">]]><<![CDATA[![CDATA[
|
|
|
+
|
|
|
+<!-- Javascript -->
|
|
|
+<programlisting language="javascript">]]><<![CDATA[![CDATA[
|
|
|
+
|
|
|
+<!-- XML -->
|
|
|
+<programlisting language="xml">]]><<![CDATA[![CDATA[
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ For program listings containing only <acronym>PHP</acronym> code,
|
|
|
+ <acronym>PHP</acronym> tags (e.g., "<?php", "?>") are not required, and
|
|
|
+ should not be used. They simply clutter the narrative, and are implied by the use
|
|
|
+ of the <emphasis><programlisting></emphasis> tag.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NOT ALLOWED -->
|
|
|
+<programlisting language="php"]]><<![CDATA[![CDATA[<?php
|
|
|
+ // ...
|
|
|
+?>]]]]>><![CDATA[</programlisting>
|
|
|
+
|
|
|
+<programlisting language="php"]]><<![CDATA[![CDATA[
|
|
|
+<?php
|
|
|
+ // ...
|
|
|
+?>
|
|
|
+]]]]>><![CDATA[</programlisting>
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Line lengths within program listings should follow the <link
|
|
|
+ linkend="coding-standard.php-file-formatting.max-line-length">coding standards
|
|
|
+ recommendations</link>.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Refrain from using <methodname>require_once()</methodname>,
|
|
|
+ <methodname>require()</methodname>, <methodname>include_once()</methodname>, and
|
|
|
+ <methodname>include()</methodname> calls within <acronym>PHP</acronym> listings.
|
|
|
+ They simply clutter the narrative, and are largely obviated when using an
|
|
|
+ autoloader. Use them only when they are essential to the example.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <note>
|
|
|
+ <title>ショートタグを決して使わないで下さい</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Short tags (e.g., "<?", "<?=") should never be used within
|
|
|
+ <emphasis>programlisting</emphasis> or the narrative of a document.
|
|
|
+ </para>
|
|
|
+ </note>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.file-formatting.inline-tags">
|
|
|
+ <title>特殊なインラインタグの注意</title>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.inline-tags.classname">
|
|
|
+ <title>classname</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ The tag <emphasis><classname></emphasis> must be used each time a class
|
|
|
+ name is represented by itself; it should not be used when combined with a
|
|
|
+ method name, variable name, or constant, and no other content is allowed within
|
|
|
+ the tag.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<para>
|
|
|
+ The class <classname>Zend_Class</classname>.
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.inline-tags.varname">
|
|
|
+ <title>varname</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Variables must be wrapped in the <emphasis><varname></emphasis> tag.
|
|
|
+ Variables must be written using the "$" sigil. No other content is allowed
|
|
|
+ within this tag, unless a class name is used, which indicates a class variable.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<para>
|
|
|
+ The variable <varname>$var</varname> and the class variable
|
|
|
+ <varname>Zend_Class::$var</varname>.
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.inline-tags.methodname">
|
|
|
+ <title>methodname</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Methods must be wrapped in the <emphasis><methodname></emphasis> tag.
|
|
|
+ Methods must either include the full method signature or at the least a pair of
|
|
|
+ closing parentheses (e.g., "()"). No other content is allowed within this tag,
|
|
|
+ unless a class name is used, which indicates a class method.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<para>
|
|
|
+ The method <methodname>foo()</methodname> and the class method
|
|
|
+ <methodname>Zend_Class::foo()</methodname>. A method with a full signature:
|
|
|
+ <methodname>foo($bar, $baz)</methodname>
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.inline-tags.constant">
|
|
|
+ <title>constant</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Use the <emphasis><constant></emphasis> tag when denoting constants.
|
|
|
+ Constants must be written in <acronym>UPPERCASE</acronym>. No other content is
|
|
|
+ allowed within this tag, unless a class name is used, which indicates a class
|
|
|
+ constant.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<para>
|
|
|
+ The constant <constant>FOO</constant> and the class constant
|
|
|
+ <constant>Zend_Class::FOO</constant>.
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.inline-tags.filename">
|
|
|
+ <title>filename</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Filenames and paths must be wrapped in the
|
|
|
+ <emphasis><filename></emphasis> tag. No other content is allowed in this
|
|
|
+ tag.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<para>
|
|
|
+ The filename <filename>application/Bootstrap.php</filename>.
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.inline-tags.command">
|
|
|
+ <title>command</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Commands, shell scripts, and program calls must be wrapped in the
|
|
|
+ <emphasis><command></emphasis> tag. If the command includes arguments,
|
|
|
+ these should also be included within the tag.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<para>
|
|
|
+ Execute <command>zf.sh create project</command>.
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.inline-tags.code">
|
|
|
+ <title>code</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Usage of the <emphasis><code></emphasis> tag is discouraged, in favor of
|
|
|
+ the other inline tasks discussed previously.
|
|
|
+ </para>
|
|
|
+ </sect3>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.file-formatting.block-tags">
|
|
|
+ <title>特殊なブロックタグの注意</title>
|
|
|
+
|
|
|
+ <sect3 id="doc-standard.file-formatting.block-tags.title">
|
|
|
+ <title>title</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ <emphasis><title></emphasis> タグで他のタグを保持してはいけません。
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<!-- NOT ALLOWED -->
|
|
|
+<title>Using <classname>Zend_Class</classname></title>
|
|
|
+
|
|
|
+<!-- OK -->
|
|
|
+<title>Using Zend_Class</title>
|
|
|
+]]></programlisting>
|
|
|
+ </sect3>
|
|
|
+ </sect2>
|
|
|
+ </sect1>
|
|
|
+
|
|
|
+ <sect1 id="doc-standard.recommendations">
|
|
|
+ <title>推奨事項</title>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.recommendations.editors">
|
|
|
+ <title>自動でフォーマットしないエディタを使ってください</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ ドキュメンテーションを編集するために、
|
|
|
+ 一般的に、正式な<acronym>XML</acronym>エディタを使用するべきではありません。
|
|
|
+ そのようなエディタは、通常、それらの独自の標準に合わせるために、
|
|
|
+ 既存のドキュメントを自動的にフォーマットします。
|
|
|
+ および／または、docbook 標準に厳密には従いません。
|
|
|
+ 例えば、それらは<acronym>CDATA</acronym>タグを消したり、
|
|
|
+ ４スペースの間隔をタブや２スペースに変えたりすることを経験しています。
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ <!-- TODO : to be translated -->
|
|
|
+ The style guidelines were written in large part to assist translators in recognizing
|
|
|
+ the lines that have changed using normal <command>diff</command> tools.
|
|
|
+ Autoformatting makes this process more difficult.
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.recommendations.images">
|
|
|
+ <title>イメージを使ってください</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Good images and diagrams can improve readability and comprehension. Use them
|
|
|
+ whenever they will assist in these goals. Images should be placed in the
|
|
|
+ <filename>documentation/manual/en/figures/</filename> directory, and be named after
|
|
|
+ the section identifier in which they occur.
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.recommendations.examples">
|
|
|
+ <title>ケースの例を使ってください</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ Look for good use cases submitted by the community, especially those posted in
|
|
|
+ proposal comments or on one of the mailing lists. Examples often illustrate usage
|
|
|
+ far better than the narrative does.
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ When writing your examples for inclusion in the manual, follow
|
|
|
+ all coding standards and documentation standards.
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.recommendations.phpdoc">
|
|
|
+ <title>phpdocの内容を繰り返すことを避けてください</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ The manual is intended to be a reference guide for end-user usage. Replicating
|
|
|
+ the phpdoc documentation for internal-use components and classes is not wanted, and
|
|
|
+ the narrative should be focussed on usage, not the internal workings. In any case,
|
|
|
+ at this time, we would like the documentation teams to focus on translating the
|
|
|
+ English manual, not the phpdoc comments.
|
|
|
+ </para>
|
|
|
+ </sect2>
|
|
|
+
|
|
|
+ <sect2 id="doc-standard.recommendations.links">
|
|
|
+ <title>リンクを使ってください</title>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ ドキュメントを繰り返す代わりに、
|
|
|
+ マニュアルの他のセクションや外部のソースにリンクしてください。
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ マニュアルの他のセクションへのリンクを
|
|
|
+ <emphasis><xref></emphasis>タグ（セクションのタイトルをリンク・テキストの代わりにします）
|
|
|
+ または<emphasis><link></emphasis>タグ（リンクのテキストを用意しなければいけません）
|
|
|
+ のどちらかを使って実施できるでしょう。
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<para>
|
|
|
+ "Xref" links to a section: <xref
|
|
|
+ linkend="doc-standard.recommendations.links" />.
|
|
|
+</para>
|
|
|
+
|
|
|
+<para>
|
|
|
+ "Link" links to a section, using descriptive text: <link
|
|
|
+ linkend="doc-standard.recommendations.links">documentation on
|
|
|
+ links</link>.
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+
|
|
|
+ <para>
|
|
|
+ 外部リソースにリンクするには、<emphasis><ulink></emphasis>を使ってください。
|
|
|
+ </para>
|
|
|
+
|
|
|
+ <programlisting language="xml"><![CDATA[
|
|
|
+<para>
|
|
|
+ The <ulink url="http://framework.zend.com/">Zend Framework site</ulink>.
|
|
|
+</para>
|
|
|
+]]></programlisting>
|
|
|
+ </sect2>
|
|
|
+ </sect1>
|
|
|
+</appendix>
|
yoshida@zend.co.jp