[DOCUMENTATION] English:

- docu fixes (ZF -> Zend Framework)

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

documentation/manual/en/module_specs/Zend_Date-Introduction.xml

@@ -113,7 +113,7 @@ date_default_timezone_set('Europe/Berlin');
                         url="http://www.php.net/float">http://www.php.net/float</ulink> ].
                     Additionally, inherent limitations of float data types, and rounding error of
                     float numbers may introduce errors into calculations. To avoid these problems,
-                    the ZF I18n components use BCMath extension, if available.
+                    the Zend Framework I18n components use BCMath extension, if available.
                 </para>
             </listitem>
             <listitem>

documentation/manual/en/module_specs/Zend_Date-Overview.xml

@@ -80,10 +80,10 @@
                 familiar with SQL will expect February 28th as the result. On the other side, people
                 familiar with Excel and OpenOffice will expect March 3rd as the result. The problem
                 only occurs, if the resulting month does not have the day, which is set in the
-                original date. For ZF developers, the desired behavior is selectable using the
-                <code>extend_month</code> option to choose either the SQL behaviour, if set to
-                false, or the spreadsheet behaviour when set to true. The default behaviour for
-                <code>extend_month</code> is false, providing behavior compatible to SQL. By
+                original date. For Zend Framework developers, the desired behavior is selectable
+                using the <code>extend_month</code> option to choose either the SQL behaviour, if
+                set to false, or the spreadsheet behaviour when set to true. The default behaviour
+                for <code>extend_month</code> is false, providing behavior compatible to SQL. By
                 default, <classname>Zend_Date</classname> computes month calculations by truncating
                 dates to the end of the month (if necessary), without wrapping into the next month
                 when the original date designates a day of the month exceeding the number of days in

documentation/manual/en/module_specs/Zend_Locale-Functions.xml

@@ -74,14 +74,15 @@ if ($locale->equals($mylocale)) {
         <title>Default locales</title>
 
         <para>
-            The method <code>getDefault()</code> returns an array of relevant locales using information from the user's
-            web browser (if available), information from the environment of the host server, and ZF settings. As with
-            the constructor for <classname>Zend_Locale</classname>, the first parameter selects a preference of which information
-            to consider
-            <link linkend="zend.locale.selection">(<code>BROWSER</code>, <code>ENVIRONMENT</code>, or <code>FRAMEWORK)</code>
-            </link>
-            first. The second parameter toggles between returning all matching locales or only the first/best match.
-            Locale-aware components normally use only the first locale. A quality rating is included, when available.
+            The method <code>getDefault()</code> returns an array of relevant locales using
+            information from the user's web browser (if available), information from the
+            environment of the host server, and Zend Framework settings. As with the constructor
+            for <classname>Zend_Locale</classname>, the first parameter selects a preference of
+            which information to consider <link
+                linkend="zend.locale.selection">(<code>BROWSER</code>, <code>ENVIRONMENT</code>, or
+                <code>FRAMEWORK)</code></link> first. The second parameter toggles between
+            returning all matching locales or only the first/best match. Locale-aware components
+            normally use only the first locale. A quality rating is included, when available.
         </para>
 
         <example id="zend.locale.getdefault.example-1">
@@ -1057,7 +1058,7 @@ print Zend_Locale::getTranslation('de', 'language', 'zh');
         </note>
 
         <table id="zend.locale.getdata.table-3">
-            <title>Differences between ZF 1.0 and ZF 1.5</title>
+            <title>Differences between Zend Framework 1.0 and 1.5</title>
             <tgroup cols="2">
                 <thead>
                     <row>
@@ -1419,7 +1420,7 @@ if ($locale instanceof Zend_Locale) {
         </para>
 
         <example id="zend.locale.detection.example-4">
-            <title>Locale aware behaviour as with ZF 1.8</title>
+            <title>Locale aware behaviour as with Zend Framework 1.8</title>
             <programlisting language="php"><![CDATA[
 $locale = Zend_Locale::findLocale($inputstring);
 ]]></programlisting>

documentation/manual/en/module_specs/Zend_Locale-Introduction.xml

@@ -55,8 +55,8 @@
         <itemizedlist mark='opencircle'>
             <listitem>
                 <para>
-                    <classname>Zend_Locale</classname> - Backend support of locales available for localization support within
-                    other ZF components.
+                    <classname>Zend_Locale</classname> - Backend support of locales available for
+                    localization support within other Zend Framework components.
                 </para>
             </listitem>
             <listitem>
@@ -169,13 +169,15 @@ $locale = new Zend_Locale('de_DE'); // German language _ Germany
         </para>
 
         <para>
-            Beware of historical changes, as ZF components do not know about or attempt to track the numerous timezone
-            changes made over many years by many regions. For example,
-            <ulink url="http://www.statoids.com/tus.html">we can see a historical list</ulink>
-            showing dozens of changes made by governments to when and if a particular region observes Daylight Savings
-            Time, and even which timezone a particular geographic area belongs. Thus, when performing date math, the
-            math performed by ZF components will not adjust for these changes, but instead will give the correct time
-            for the timezone using current, modern rules for DST and timezone assignment for geographic regions.
+            Beware of historical changes, as Zend Framework components do not know about or attempt
+            to track the numerous timezone changes made over many years by many regions. For
+            example, <ulink url="http://www.statoids.com/tus.html">we can see a historical
+                list</ulink> showing dozens of changes made by governments to when and if a
+            particular region observes Daylight Savings Time, and even which timezone a particular
+            geographic area belongs. Thus, when performing date math, the math performed by Zend
+            Framework components will not adjust for these changes, but instead will give the
+            correct time for the timezone using current, modern rules for DST and timezone
+            assignment for geographic regions.
         </para>
 
     </sect2>
@@ -378,10 +380,11 @@ $date = new Zend_Date();
         <title>ZF Locale-Aware Classes</title>
 
         <para>
-            In the ZF, locale-aware classes rely on <classname>Zend_Locale</classname> to automatically select a locale, as
-            explained above. For example, in a ZF web application, constructing a date using <classname>Zend_Date</classname>
-            without specifying a locale results in an object with a locale based on information provided by the current
-            user's web browser.
+            In the ZF, locale-aware classes rely on <classname>Zend_Locale</classname> to
+            automatically select a locale, as explained above. For example, in a Zend Framework web
+            application, constructing a date using <classname>Zend_Date</classname> without
+            specifying a locale results in an object with a locale based on information provided by
+            the current user's web browser.
         </para>
 
         <example id="zend.locale.interoperate.example-1">
@@ -392,9 +395,9 @@ $date = new Zend_Date('2006',Zend_Date::YEAR);
         </example>
 
         <para>
-            To override this default behavior, and force locale-aware ZF components to use specific locales, regardless
-            of the origin of your website visitors, explicitly specify a locale as the third argument to the
-            constructor.
+            To override this default behavior, and force locale-aware Zend Framework components to
+            use specific locales, regardless of the origin of your website visitors, explicitly
+            specify a locale as the third argument to the constructor.
         </para>
 
         <example id="zend.locale.interoperate.example-2">

documentation/manual/en/module_specs/Zend_Measure-Creation.xml

@@ -51,17 +51,16 @@ echo $unit;
         <title>Creating measurements from strings</title>
 
         <para>
-            Many measurements received as input to ZF applications can only be passed to <classname>Zend_Measure_*</classname>
-            classes as strings, such as numbers written using
-            <ulink url="http://en.wikipedia.org/wiki/Roman_numerals">roman numerals</ulink>
-            or extremely large binary values that exceed the precision of PHP's native integer and float types. Since
-            integers can be denoted using strings, if there is any risk of losing precision due to limitations of PHP's
-            native integer and float types, using strings instead. <classname>Zend_Measure_Number</classname> uses the BCMath
-            extension to support arbitrary precision, as shown in the example below, to avoid limitations in many PHP
-            functions, such as
-            <ulink url="http://php.net/bin2dec"><code>bin2dec()</code>
-            </ulink>
-            .
+            Many measurements received as input to Zend Framework applications can only be passed
+            to <classname>Zend_Measure_*</classname> classes as strings, such as numbers written
+            using <ulink url="http://en.wikipedia.org/wiki/Roman_numerals">roman numerals</ulink>
+            or extremely large binary values that exceed the precision of PHP's native integer
+            and float types. Since integers can be denoted using strings, if there is any risk of
+            losing precision due to limitations of PHP's native integer and float types, using
+            strings instead. <classname>Zend_Measure_Number</classname> uses the BCMath extension
+            to support arbitrary precision, as shown in the example below, to avoid limitations in
+            many PHP functions, such as
+            <ulink url="http://php.net/bin2dec"><code>bin2dec()</code></ulink>.
         </para>
 
         <example id="zend.measure.creation.string.example-1">

documentation/manual/en/module_specs/Zend_Translate-SourceCreation.xml

@@ -0,0 +1,317 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<sect1 id="zend.translate.sourcecreation">
+
+    <title>Creating source files</title>
+
+    <para>
+        Below you will find a description of the different source formats
+        which can be used with <classname>Zend_Translate</classname>.
+    </para>
+
+    <note>
+        <para>
+            Note that most of the described formats should be created by using
+            a tool or a generation process. These Tools and processes are not part
+            of Zend Framework and for most of the described formats free tools
+            are available.
+        </para>
+    </note>
+
+    <sect2 id="zend.translate.sourcecreation.array">
+
+        <title>Creating Array source files</title>
+
+        <para>
+            Array source files are plain arrays. But you have to define them
+            manually since there is no tool to aid this.
+            But because they are so simple, it's the fastest way to look up
+            messages if your code works as expected. It's generally the best
+            adapter to get started with translation business.
+        </para>
+
+        <programlisting role="php"><![CDATA[
+$english = array(
+    'message1' => 'message1',
+    'message2' => 'message2',
+    'message3' => 'message3');
+
+$german = array(
+    'message1' => 'Nachricht1',
+    'message2' => 'Nachricht2',
+    'message3' => 'Nachricht3');
+
+$translate = new Zend_Translate('array', $english, 'en');
+$translate->addTranslation($deutsch, 'de');
+]]></programlisting>
+
+        <para>
+            Since release 1.5 it is also supported to have arrays included within an external file.
+            You just have to provide the filename and <classname>Zend_Translate</classname> will automatically
+            include it and look for the array. See the following example for details:
+        </para>
+
+        <programlisting role="php"><![CDATA[
+// myarray.php
+return array(
+    'message1' => 'Nachricht1',
+    'message2' => 'Nachricht2',
+    'message3' => 'Nachricht3');
+
+// controller
+$translate = new Zend_Translate('array', '/path/to/myarray.php', 'de');
+]]></programlisting>
+
+        <note>
+            <para>
+                Files which do not return an array will fail to be included.
+                Also any output within this file will be ignored and suppressed.
+            </para>
+
+        </note>
+
+    </sect2>
+
+    <sect2 id="zend.translate.sourcecreation.gettext">
+
+        <title>Creating Gettext source files</title>
+
+        <para>
+            Gettext source files are created by GNU's gettext library.
+            There are several free tools available that can parse your
+            code files and create the needed gettext source files.
+            These have the extension <emphasis>*.mo</emphasis>
+            and they are binary files.
+            An open source tool for creating the files is
+            <ulink url="http://sourceforge.net/projects/poedit/">poEdit</ulink>.
+            This tool also supports you during the translation process itself.
+        </para>
+
+        <programlisting role="php"><![CDATA[
+// We accume that we have created the mo files and translated them
+$translate = new Zend_Translate('gettext', '/path/to/english.mo', 'en');
+$translate->addTranslation('/path/to/german.mo', 'de');
+]]></programlisting>
+
+        <para>
+            As you can see the adapters are used exactly the same way,
+            with one small difference:
+            change <emphasis>array</emphasis> to <emphasis>gettext</emphasis>. All other usages are exactly
+            the same as with all other adapters.
+            With the gettext adapter you no longer have to be aware of
+            gettext's standard directory structure,
+            bindtextdomain and textdomain.
+            Just give the path and filename to the adapter.
+        </para>
+
+        <note>
+            <para>
+                 You should always use UTF-8 as source encoding.
+                 Otherwise you will have problems when using two
+                 different source encodings.
+                 E.g. one of your source files is encoded
+                 with ISO-8815-11 and another one with CP815.
+                 You can set only one encoding for your source file,
+                 so one of your languages probably will not display correctly.
+            </para>
+            <para>
+                 UTF-8 is a portable format which supports all languages.
+                 When using UTF-8 for all languages, you will eliminate
+                 the problem of incompatible encodings.
+            </para>
+        </note>
+
+        <para>
+            Many gettext editors add adapter informations as empty translation string.
+            This is the reason why empty strings are not translated when using the
+            gettext adapter. Instead they are erased from the translation table and
+            provided by the <code>getAdapterInfo()</code> method. It will return
+            the adapter informations for all added gettext files as array using the
+            filename as key.
+        </para>
+
+        <programlisting role="php"><![CDATA[
+// Getting the adapter informations
+$translate = new Zend_Translate('gettext', '/path/to/english.mo', 'en');
+print_r($translate->getAdapterInfo());
+]]></programlisting>
+
+    </sect2>
+
+    <sect2 id="zend.translate.sourcecreation.tmx">
+
+        <title>Creating TMX source files</title>
+
+        <para>
+            TMX source files are a new industry standard.
+            They have the advantage of being XML files and so they are
+            readable by every editor and of course by humans.
+            You can either create TMX files manually with a text editor,
+            or you can use a special tool. But most tools currently available for
+            creating TMX source files are not freely available.
+        </para>
+
+        <example id="zend.translate.sourcecreation.tmx.example">
+            <title>Example TMX file</title>
+            <programlisting role="xml"><![CDATA[
+<?xml version="1.0" ?>
+<!DOCTYPE tmx SYSTEM "tmx14.dtd">
+<tmx version="1.4">
+ <header creationtoolversion="1.0.0" datatype="winres" segtype="sentence"
+         adminlang="en-us" srclang="de-at" o-tmf="abc"
+         creationtool="XYZTool" >
+ </header>
+ <body>
+  <tu tuid='message1'>
+   <tuv xml:lang="de"><seg>Nachricht1</seg></tuv>
+   <tuv xml:lang="en"><seg>message1</seg></tuv>
+  </tu>
+  <tu tuid='message2'>
+   <tuv xml:lang="en"><seg>message2</seg></tuv>
+   <tuv xml:lang="de"><seg>Nachricht2</seg></tuv>
+  </tu>
+]]></programlisting>
+
+            <programlisting role="php"><![CDATA[
+$translate = new Zend_Translate('tmx', 'path/to/mytranslation.tmx', 'en');
+]]></programlisting>
+        </example>
+
+        <para>
+            TMX files can have several languages within the same file.
+            All other included languages are added automatically,
+            so you do not have to call <code>addLanguage()</code>.
+        </para>
+
+        <para>
+            If you want to have only specified languages from the source translated
+            you can set the option '<code>defined_language</code>' to <constant>TRUE</constant>.
+            With this option you can add the wished languages explicitly with
+            <code>addLanguage()</code>. The default value for this option is to add all
+            languages.
+        </para>
+    </sect2>
+
+    <sect2 id="zend.translate.sourcecreation.csv">
+
+        <title>Creating CSV source files</title>
+
+        <para>
+            CSV source files are small and human readable.
+            If your customers want to translate their own,
+            you will probably use the CSV adapter.
+        </para>
+
+        <example id="zend.translate.sourcecreation.csv.example">
+            <title>Example CSV file</title>
+            <programlisting language="txt"><![CDATA[
+#Example csv file
+message1;Nachricht1
+message2;Nachricht2
+]]></programlisting>
+
+            <programlisting role="php"><![CDATA[
+$translate = new Zend_Translate('csv', '/path/to/mytranslation.csv', 'de');
+$translate->addTranslation('path/to/other.csv', 'fr');
+]]></programlisting>
+        </example>
+
+        <para>
+            There are three different options for the CSV adapter.
+            You can set '<code>delimiter</code>', '<code>limit</code>' and
+            '<code>enclosure</code>'.
+        </para>
+
+        <para>
+            The default delimiter for CSV string is '<code>;</code>', but
+            with the option '<code>delimiter</code>'
+            you can decide to use another one.
+        </para>
+
+        <para>
+            The default limit for a line within a CSV file is '<code>0</code>'. This means
+            that the end of a CSV line is searched automatically. If you set
+            '<code>limit</code>' to any value, then the CSV file will be
+            read faster, but any line exceeding this limit will be truncated.
+        </para>
+
+        <para>
+            The default enclosure to use for CSV files is '<code>"</code>'. You can
+            set a different one using the option '<code>enclosure</code>'.
+        </para>
+
+        <example id="zend.translate.sourcecreation.csv.example2">
+            <title>Second CSV file example</title>
+            <programlisting language="txt"><![CDATA[
+# Example CSV file
+"message,1",Nachricht1
+message2,"Nachricht,2"
+"message3,",Nachricht3
+]]></programlisting>
+
+            <programlisting role="php"><![CDATA[
+$translate = new Zend_Translate(
+    'csv',
+    '/path/to/mytranslation.csv',
+    'de',
+    array('delimiter' => ','));
+
+$translate->addTranslation('/path/to/other.csv', 'fr');
+]]></programlisting>
+        </example>
+
+        <note>
+
+            <para>
+                When you are using non-ASCII characters within your CSV file, like umlauts or UTF-8
+                chars, then you should always use enclosure. Omitting the enclosure can lead to
+                missing characters in your translation.
+            </para>
+
+        </note>
+
+    </sect2>
+
+    <sect2 id="zend.translate.sourcecreation.ini">
+
+        <title>Creating INI source files</title>
+
+        <para>
+            INI source files are human readable but normally not very small as they also
+            include other data beside translations. If you have data which shall be
+            editable by your customers you can use the INI adapter.
+        </para>
+
+        <example id="zend.translate.sourcecreation.ini.example">
+            <title>Example INI file</title>
+            <programlisting language="txt"><![CDATA[
+[Test]
+;TestPage Comment
+Message_1="Nachricht 1 (de)"
+Message_2="Nachricht 2 (de)"
+Message_3="Nachricht :3 (de)"
+]]></programlisting>
+
+            <programlisting role="php"><![CDATA[
+$translate = new Zend_Translate('ini', '/path/to/mytranslation.ini', 'de');
+$translate->addTranslation('/path/to/other.ini', 'it');
+]]></programlisting>
+        </example>
+
+        <para>
+            INI files have several restrictions. If a value in the ini file contains any
+            non-alphanumeric characters it needs to be enclosed in double-quotes (<code>"</code>).
+            There are also reserved words which must not be used as keys for ini files.
+            These include: <constant>NULL</constant>, <code>yes</code>, <code>no</code>, <constant>TRUE</constant>,
+            and <constant>FALSE</constant>. Values <constant>NULL</constant>, <code>no</code> and <constant>FALSE</constant> results
+            in <code>""</code>, <code>yes</code> and <constant>TRUE</constant> results in <code>1</code>. Characters <code>{}|&amp;~![()"</code> must not be used anywhere
+            in the key and have a special meaning in the value. Do not use them as it will
+            produce unexpected behaviour.
+        </para>
+
+    </sect2>
+
+</sect1>
+<!--
+vim:se ts=4 sw=4 et:
+-->

documentation/manual/en/module_specs/Zend_Validate-InArray.xml

@@ -0,0 +1,149 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<sect2 id="zend.validate.set.in_array">
+
+    <title>InArray</title>
+
+    <para>
+        <classname>Zend_Validate_InArray</classname> allows you to validate if a given value is
+        contained within an array. It is also able to validate multidimensional arrays.
+    </para>
+
+    <sect3 id="zend.validate.set.in_array.basic">
+        <title>Simple array validation</title>
+
+        <para>
+            The simplest way, is just to give the array which should be searched against at
+            initiation:
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$validator = new Zend_Validate_InArray(array('key' => 'value', 'otherkey' => 'othervalue'));
+if ($validator->isValid('value')) {
+    // value found
+} else {
+    // no value found
+}
+]]></programlisting>
+
+        <para>
+            This will behave exactly like <acronym>PHP</acronym>'s <methodname>in_array()</methodname> method.
+        </para>
+
+        <note>
+            <para>
+                Per default this validation is not strict nor can it validate multidimensional arrays.
+            </para>
+        </note>
+
+        <para>
+            Of course you can give the array to validate against also afterwards by using the
+            <methodname>setHaystack()</methodname> method.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$validator = new Zend_Validate_InArray();
+$validator->setHaystack(array('key' => 'value', 'otherkey' => 'othervalue'));
+
+if ($validator->isValid('value')) {
+    // value found
+} else {
+    // no value found
+}
+]]></programlisting>
+    </sect3>
+
+    <sect3 id="zend.validate.set.in_array.strict">
+        <title>Strict array validation</title>
+
+        <para>
+            As mentioned before you can also do a strict validation within the array. Per default there
+            would be no difference between the integer value <emphasis>0</emphasis> and the string
+            <emphasis>"0"</emphasis>. When doing a strict validation this difference will also be
+            validated and only same types are accepted.
+        </para>
+
+        <para>
+            A strict validation can also be done by using two different ways. At initiation and by using
+            a method. At initiation you have to give an array with the following structure:
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$validator = new Zend_Validate_InArray(
+    array(
+        'haystack' => array('key' => 'value', 'otherkey' => 'othervalue'),
+        'strict'   => true
+    )
+);
+
+if ($validator->isValid('value')) {
+    // value found
+} else {
+    // no value found
+}
+]]></programlisting>
+
+        <para>
+            The <emphasis>haystack</emphasis> key contains your array to validate against, and by
+            setting the <emphasis>script</emphasis> key to <constant>TRUE</constant> the validation
+            is done by using a strict type check.
+        </para>
+
+        <para>
+            Of course you can also use the <methodname>setStrict()</methodname> method to change
+            this setting afterwards.
+        </para>
+
+        <note>
+            <para>
+                Note that the <emphasis>strict</emphasis> setting is per default
+                <constant>FALSE</constant>.
+            </para>
+        </note>
+    </sect3>
+
+    <sect3 id="zend.validate.set.in_array.recursive">
+        <title>Recursive array validation</title>
+
+        <para>
+            In addition to <acronym>PHP</acronym>'s <methodname>in_array()</methodname> method
+            this validator can also be used to validate multidimensional arrays.
+        </para>
+
+        <para>
+            To validate multidimensional arrays you have to set the <emphasis>recursive</emphasis>
+            option.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$validator = new Zend_Validate_InArray(
+    array(
+        'haystack' => array(
+            'firstDimension' => array('key' => 'value', 'otherkey' => 'othervalue'),
+            'secondDimension' => array('some' => 'real', 'different' => 'key')),
+        'recursive' => true
+    )
+);
+
+if ($validator->isValid('value')) {
+    // value found
+} else {
+    // no value found
+}
+]]></programlisting>
+
+        <para>
+            Your array will then be validated recursive to see if the given value is contained.
+        </para>
+
+        <note>
+            <para>
+                Note that per default the recursive validation is turned off.
+            </para>
+        </note>
+    </sect3>
+
+</sect2>
+<!--
+vim:se ts=4 sw=4 et:
+-->