[ZF-8965] Zend_Filter:

- added section for Zend_Filter_StripNewLines
- reworked filter description for available settings

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

documentation/manual/en/module_specs/Zend_Filter-Boolean.xml

@@ -8,6 +8,39 @@
         useful when working with databases or when processing form values.
     </para>
 
+    <sect3 id="zend.filter.set.boolean.options">
+        <title>Supported options for Zend_Filter_Boolean</title>
+
+        <para>
+            The following options are supported for <classname>Zend_Filter_Boolean</classname>:
+        </para>
+
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <emphasis><property>casting</property></emphasis>: When this option is set to
+                    <constant>TRUE</constant> then any given input will be casted to boolean. This
+                    option defaults to <constant>TRUE</constant>.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis><property>locale</property></emphasis>: This option sets the locale
+                    which will be used to detect localized input.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis><property>type</property></emphasis>: The <property>type</property>
+                    option sets the boolean type which should be used. Read the following for
+                    details.
+                </para>
+            </listitem>
+        </itemizedlist>
+    </sect3>
+
     <sect3 id="zend.filter.set.boolean.default">
         <title>Default behaviour for Zend_Filter_Boolean</title>
 

documentation/manual/en/module_specs/Zend_Filter-Callback.xml

@@ -9,23 +9,52 @@
         have a method which does the job.
     </para>
 
-    <para>
-        Let's expect we want to create a filter which reverses a string.
-    </para>
+    <sect3 id="zend.filter.set.callback.options">
+        <title>Supported options for Zend_Filter_Callback</title>
+
+        <para>
+            The following options are supported for <classname>Zend_Filter_Callback</classname>:
+        </para>
 
-    <programlisting language="php"><![CDATA[
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <emphasis><property>callback</property></emphasis>: This sets the callback
+                    which should be used.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis><property>options</property></emphasis>: This property sets the
+                    options which are used when the callback is processed.
+                </para>
+            </listitem>
+        </itemizedlist>
+    </sect3>
+
+    <sect3 id="zend.filter.set.callback.basic">
+        <title>Basic usage</title>
+
+        <para>
+            The usage of this filter is quite simple. Let's expect we want to create a filter which
+            reverses a string.
+        </para>
+
+        <programlisting language="php"><![CDATA[
 $filter = new Zend_Filter_Callback('strrev');
 
 print $filter->filter('Hello!');
 // returns "!olleH"
 ]]></programlisting>
 
-    <para>
-        As you can see it's really simple to use a callback to define a own filter. It is also
-        possible to use a method, which is defined within a class, by giving an array as callback.
-    </para>
+        <para>
+            As you can see it's really simple to use a callback to define a own filter. It is also
+            possible to use a method, which is defined within a class, by giving an array as
+            callback.
+        </para>
 
-    <programlisting language="php"><![CDATA[
+        <programlisting language="php"><![CDATA[
 // Our classdefinition
 class MyClass
 {
@@ -37,18 +66,31 @@ $filter = new Zend_Filter_Callback(array('MyClass', 'Reverse'));
 print $filter->filter('Hello!');
 ]]></programlisting>
 
-    <para>
-        To get the actual set callback use <methodname>getCallback()</methodname> and to set
-        another callback use <methodname>setCallback()</methodname>.
-    </para>
+        <para>
+            To get the actual set callback use <methodname>getCallback()</methodname> and to set
+            another callback use <methodname>setCallback()</methodname>.
+        </para>
 
-    <para>
-        It is also possible to define default parameters, which are given to the called method
-        as array when the filter is executed. This array will be concatenated with the value which
-        will be filtered.
-    </para>
+        <note>
+            <title>Possible exceptions</title>
+
+            <para>
+                You should note that defining a callback method which can not be called will raise
+                an exception.
+            </para>
+        </note>
+    </sect3>
+
+    <sect3 id="zend.filter.set.callback.parameters">
+        <title>Default parameters within a callback</title>
+
+        <para>
+            It is also possible to define default parameters, which are given to the called method
+            as array when the filter is executed. This array will be concatenated with the value
+            which will be filtered.
+        </para>
 
-    <programlisting language="php"><![CDATA[
+        <programlisting language="php"><![CDATA[
 $filter = new Zend_Filter_Callback(
     array(
         'callback' => 'MyMethod',
@@ -58,18 +100,12 @@ $filter = new Zend_Filter_Callback(
 $filter->filter(array('value' => 'Hello'));
 ]]></programlisting>
 
-    <para>
-        When you would call the above method definition manually it would look like this:
-    </para>
+        <para>
+            When you would call the above method definition manually it would look like this:
+        </para>
 
-    <programlisting language="php"><![CDATA[
+        <programlisting language="php"><![CDATA[
 $value = MyMethod('Hello', 'param1', 'param2');
 ]]></programlisting>
-
-    <note>
-        <para>
-            You should note that defining a callback method which can not be called will raise
-            an exception.
-        </para>
-    </note>
+    </sect3>
 </sect2>

documentation/manual/en/module_specs/Zend_Filter-Compress.xml

@@ -5,53 +5,86 @@
 
     <para>
         These two filters are capable of compressing and decompressing strings, files, and
-        directories. They make use of adapters and support the following compression formats:
+        directories.
     </para>
 
-    <itemizedlist>
-        <listitem>
-            <para>
-                <emphasis>Bz2</emphasis>
-            </para>
-        </listitem>
+    <sect3 id="zend.filter.set.compress.options">
+        <title>Supported options for Zend_Filter_Compress and Zend_Filter_Decompress</title>
 
-        <listitem>
-            <para>
-                <emphasis>Gz</emphasis>
-            </para>
-        </listitem>
+        <para>
+            The following options are supported for <classname>Zend_Filter_Compress</classname>
+            and <classname>Zend_Filter_Decompress</classname>:
+        </para>
 
-        <listitem>
-            <para>
-                <emphasis>Lzf</emphasis>
-            </para>
-        </listitem>
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <emphasis><property>adapter</property></emphasis>: The compression adapter which
+                    should be used. It defaults to <property>Gz</property>.
+                </para>
+            </listitem>
 
-        <listitem>
-            <para>
-                <emphasis>Rar</emphasis>
-            </para>
-        </listitem>
+            <listitem>
+                <para>
+                    <emphasis><property>options</property></emphasis>: Additional options which are
+                    given to the adapter at initiation. Each adapter supports it's own options.
+                </para>
+            </listitem>
+        </itemizedlist>
+    </sect3>
 
-        <listitem>
-            <para>
-                <emphasis>Tar</emphasis>
-            </para>
-        </listitem>
+    <sect3 id="zend.filter.set.compress.basic">
+        <title>Supported compression adapters</title>
 
-        <listitem>
-            <para>
-                <emphasis>Zip</emphasis>
-            </para>
-        </listitem>
-    </itemizedlist>
+        <para>
+            The following compression formats are supported by their own adapter:
+        </para>
 
-    <para>
-        Each compression format has different capabilities as described below. All compression
-        filters may be used in approximately the same ways, and differ primarily in the options
-        available and the type of compression they offer (both algorithmically as well as string vs.
-        file vs. directory)
-    </para>
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <emphasis>Bz2</emphasis>
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis>Gz</emphasis>
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis>Lzf</emphasis>
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis>Rar</emphasis>
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis>Tar</emphasis>
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis>Zip</emphasis>
+                </para>
+            </listitem>
+        </itemizedlist>
+
+        <para>
+            Each compression format has different capabilities as described below. All compression
+            filters may be used in approximately the same ways, and differ primarily in the options
+            available and the type of compression they offer (both algorithmically as well as string
+            vs. file vs. directory)
+        </para>
+    </sect3>
 
     <sect3 id="zend.filter.set.compress.generic">
         <title>Generic handling</title>

documentation/manual/en/module_specs/Zend_Filter-Decryption.xml

@@ -1,170 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- Reviewed: no -->
-<sect2 id="zend.filter.set.decrypt">
-    <title>Decrypt</title>
-
-    <para>
-        This filter will decrypt any given string with the provided setting. Therefor it makes use
-        of Adapters. Actually there are adapters for the <classname>Mcrypt</classname> and
-        <classname>OpenSSL</classname> extensions from <acronym>PHP</acronym>.
-    </para>
-
-    <para>
-        For details about how to encrypt content look at the <classname>Encrypt</classname> filter.
-        As the basics are covered within the <classname>Encrypt</classname> filter, we will
-        describe here only the needed additional methods and changes for decryption.
-    </para>
-
-    <sect3 id="zend.filter.set.decrypt.mcrypt">
-        <title>Decryption with Mcrypt</title>
-
-        <para>
-            For decrypting content which was previously encrypted with <classname>Mcrypt</classname>
-            you need to have the options with which the encryption has been called.
-        </para>
-
-        <para>
-            There is one eminent difference for you. When you did not provide a vector at
-            encryption you need to get it after you encrypted the content by using the
-            <methodname>getVector()</methodname> method on the encryption filter. Without the
-            correct vector you will not be able to decrypt the content.
-        </para>
-
-        <para>
-            As soon as you have provided all options decryption is as simple as encryption.
-        </para>
-
-        <programlisting language="php"><![CDATA[
-// Use the default blowfish settings
-$filter = new Zend_Filter_Decrypt('myencryptionkey');
-
-// Set the vector with which the content was encrypted
-$filter->setVector('myvector');
-
-$decrypted = $filter->filter('encoded_text_normally_unreadable');
-print $decrypted;
-]]></programlisting>
-
-        <note>
-            <para>
-                Note that you will get an exception if the mcrypt extension is not available in your
-                environment.
-            </para>
-        </note>
-
-        <note>
-            <para>
-                You should also note that all settings which be checked when you create the instance
-                or when you call <methodname>setEncryption()</methodname>. If mcrypt detects problem
-                with your settings an exception will be thrown.
-            </para>
-        </note>
-    </sect3>
-
-    <sect3 id="zend.filter.set.decrypt.openssl">
-        <title>Decryption with OpenSSL</title>
-
-        <para>
-            Decryption with <classname>OpenSSL</classname> is as simple as encryption. But you need
-            to have all data from the person who encrypted the content.
-        </para>
-
-        <para>
-            For decryption with <classname>OpenSSL</classname> you need:
-        </para>
-
-        <itemizedlist>
-            <listitem>
-                <para>
-                    <emphasis>private</emphasis>: Your private key which will be used for decrypting
-                    the content. The private key can be either a filename with path of the key
-                    file, or just the content of the key file itself.
-                </para>
-            </listitem>
-
-            <listitem>
-                <para>
-                    <emphasis>envelope</emphasis>: The encrypted envelope key from the user who
-                    encrypted the content. You can either provide the path and filename of the key
-                    file, or just the content of the key file itself. When the
-                    <property>package</property> option has been set, then you can omit this
-                    parameter.
-                </para>
-            </listitem>
-
-            <listitem>
-                <para>
-                    <emphasis>package</emphasis>: If the envelope key has been packed with the
-                    encrypted value. Defaults to <constant>FALSE</constant>.
-                </para>
-            </listitem>
-        </itemizedlist>
-
-        <programlisting language="php"><![CDATA[
-// Use openssl and provide a private key
-$filter = new Zend_Filter_Decrypt(array(
-    'adapter' => 'openssl',
-    'private' => '/path/to/mykey/private.pem'
-));
-
-// of course you can also give the envelope keys at initiation
-$filter->setEnvelopeKey(array(
-    '/key/from/encoder/first.pem',
-    '/key/from/encoder/second.pem'
-));
-]]></programlisting>
-
-        <note>
-            <para>
-                Note that the <classname>OpenSSL</classname> adapter will not work when you do not
-                provide valid keys.
-            </para>
-        </note>
-
-        <para>
-            Optionally it could be necessary to provide the passphrase for decrypting the keys
-            themself by using the <methodname>setPassphrase()</methodname> method.
-        </para>
-
-        <programlisting language="php"><![CDATA[
-// Use openssl and provide a private key
-$filter = new Zend_Filter_Decrypt(array(
-    'adapter' => 'openssl',
-    'private' => '/path/to/mykey/private.pem'
-));
-
-// of course you can also give the envelope keys at initiation
-$filter->setEnvelopeKey(array(
-    '/key/from/encoder/first.pem',
-    '/key/from/encoder/second.pem'
-));
-$filter->setPassphrase('mypassphrase');
-]]></programlisting>
-
-        <para>
-            At last, decode the content. Our complete example for decrypting the previously
-            encrypted content looks like this.
-        </para>
-
-        <programlisting language="php"><![CDATA[
-// Use openssl and provide a private key
-$filter = new Zend_Filter_Decrypt(array(
-    'adapter' => 'openssl',
-    'private' => '/path/to/mykey/private.pem'
-));
-
-// of course you can also give the envelope keys at initiation
-$filter->setEnvelopeKey(array(
-    '/key/from/encoder/first.pem',
-    '/key/from/encoder/second.pem'
-));
-$filter->setPassphrase('mypassphrase');
-
-$decrypted = $filter->filter('encoded_text_normally_unreadable');
-print $decrypted;
-]]></programlisting>
-    </sect3>
-</sect2>
-<!--
-vim:se ts=4 sw=4 et:
--->

documentation/manual/en/module_specs/Zend_Filter-Encryption.xml

@@ -1,82 +1,79 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- Reviewed: no -->
 <sect2 id="zend.filter.set.encrypt">
-    <title>Encrypt</title>
+    <title>Encrypt and Decrypt</title>
 
     <para>
-        This filter will encrypt any given string with the provided setting. Therefor it makes use
-        of Adapters. Actually there are adapters for the <classname>Mcrypt</classname> and
+        These filters allow to encrypt and decrypt any given string. Therefor they make use of
+        Adapters. Actually there are adapters for the <classname>Mcrypt</classname> and
         <classname>OpenSSL</classname> extensions from <acronym>PHP</acronym>.
     </para>
 
-    <para>
-        As these two encryption methodologies work completely different, also the usage of the
-        adapters differ. You have to select the adapter you want to use when initiating the filter.
-    </para>
-
-    <programlisting language="php"><![CDATA[
-// Use the Mcrypt adapter
-$filter1 = new Zend_Filter_Encrypt(array('adapter' => 'mcrypt'));
-
-// Use the OpenSSL adapter
-$filter2 = new Zend_Filter_Encrypt(array('adapter' => 'openssl'));
-]]></programlisting>
-
-    <para>
-        To set another adapter you can also use <methodname>setAdapter()</methodname>, and the
-        <methodname>getAdapter()</methodname> method to receive the actual set adapter.
-    </para>
-
-    <programlisting language="php"><![CDATA[
-// Use the Mcrypt adapter
-$filter = new Zend_Filter_Encrypt();
-$filter->setAdapter('openssl');
-]]></programlisting>
-
-    <note>
-        <para>
-            When you do not supply the <property>adapter</property> option or do not use setAdapter,
-            then the <classname>Mcrypt</classname> adapter will be used per default.
-        </para>
-    </note>
-
-    <sect3 id="zend.filter.set.encrypt.mcrypt">
-        <title>Encryption with Mcrypt</title>
+    <sect3 id="zend.filter.set.encrypt.options">
+        <title>Supported options for Zend_Filter_Encrypt and Zend_Filter_Decrypt</title>
 
         <para>
-            When you have installed the <classname>Mcrypt</classname> extension you can use the
-            <classname>Mcrypt</classname> adapter. This adapter supports the following options at
-            initiation:
+            The following options are supported for <classname>Zend_Filter_Encrypt</classname> and
+            <classname>Zend_Filter_Decrypt</classname>:
         </para>
 
         <itemizedlist>
             <listitem>
                 <para>
-                    <emphasis>key</emphasis>: The encryption key with which the input will be
-                    encrypted. You need the same key for decryption.
+                    <emphasis><property>adapter</property></emphasis>: This sets the encryption
+                    adapter which should be used
                 </para>
             </listitem>
 
             <listitem>
                 <para>
-                    <emphasis>algorithm</emphasis>: The algorithm which has to be used. It should be
+                    <emphasis><property>algorithm</property></emphasis>: Only
+                    <classname>MCrypt</classname>. The algorithm which has to be used. It should be
                     one of the algorithm ciphers which can be found under
                     <ulink url="http://php.net/mcrypt">PHP's mcrypt ciphers</ulink>. If not set it
-                    defaults to 'blowfish'.
+                    defaults to <property>blowfish</property>.
                 </para>
             </listitem>
 
             <listitem>
                 <para>
-                    <emphasis>algorithm_directory</emphasis>: The directory where the algorithm can
+                    <emphasis><property>algorithm_directory</property></emphasis>: Only
+                    <classname>MCrypt</classname>. The directory where the algorithm can
                     be found. If not set it defaults to the path set within the mcrypt extension.
                 </para>
             </listitem>
 
             <listitem>
                 <para>
-                    <emphasis>mode</emphasis>: The encryption mode which has to be used. It should
-                    be one of the modes which can be found under
+                    <emphasis><property>compression</property></emphasis>: If the encrypted value
+                    should be compressed. Default is no compression.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis><property>envelope</property></emphasis>: Only
+                    <classname>OpenSSL</classname>. The encrypted envelope key from the user who
+                    encrypted the content. You can either provide the path and filename of the key
+                    file, or just the content of the key file itself. When the
+                    <property>package</property> option has been set, then you can omit this
+                    parameter.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis><property>key</property></emphasis>: Only
+                    <classname>MCrypt</classname>. The encryption key with which the input will be
+                    encrypted. You need the same key for decryption.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis><property>mode</property></emphasis>: Only
+                    <classname>MCrypt</classname>. The encryption mode which has to be used. It
+                    should be one of the modes which can be found under
                     <ulink url="http://php.net/mcrypt">PHP's mcrypt modes</ulink>. If not set it
                     defaults to 'cbc'.
                 </para>
@@ -84,7 +81,8 @@ $filter->setAdapter('openssl');
 
             <listitem>
                 <para>
-                    <emphasis>mode_directory</emphasis>: The directory where the mode can be found.
+                    <emphasis><property>mode_directory</property></emphasis>: Only
+                    <classname>MCrypt</classname>. The directory where the mode can be found.
                     If not set it defaults to the path set within the <classname>Mcrypt</classname>
                     extension.
                 </para>
@@ -92,31 +90,94 @@ $filter->setAdapter('openssl');
 
             <listitem>
                 <para>
-                    <emphasis>vector</emphasis>: The initialization vector which shall be used. If
-                    not set it will be a random vector.
+                    <emphasis><property>package</property></emphasis>: Only
+                    <classname>OpenSSL</classname>. If the envelope key should be packed with the
+                    encrypted value. Default is <constant>FALSE</constant>.
                 </para>
             </listitem>
 
             <listitem>
                 <para>
-                    <emphasis>salt</emphasis>: If the key should be used as salt value. The key used
-                    for encryption will then itself also be encrypted. Default is
+                    <emphasis><property>private</property></emphasis>: Only
+                    <classname>OpenSSL</classname>. Your private key which will be used for
+                    encrypting the content. Also the private key can be either a filename with path
+                    of the key file, or just the content of the key file itself.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis><property>public</property></emphasis>: Only
+                    <classname>OpenSSL</classname>. The public key of the user whom you want to
+                    provide the encrpted content. You can give multiple public keys by using an
+                    array. You can eigther provide the path and filename of the key file, or just
+                    the content of the key file itself.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis><property>salt</property></emphasis>: Only
+                    <classname>MCrypt</classname>. If the key should be used as salt value. The key
+                    used for encryption will then itself also be encrypted. Default is
                     <constant>FALSE</constant>.
                 </para>
             </listitem>
 
             <listitem>
                 <para>
-                    <emphasis>compression</emphasis>: If the encrypted value should be compressed.
-                    Default is no compression. For details take a look into <link
-                        linkend="zend.filter.set.encrypt.openssl.compressed">compression for
-                        Openssl</link>.
+                    <emphasis><property>vector</property></emphasis>: Only
+                    <classname>MCrypt</classname>. The initialization vector which shall be used. If
+                    not set it will be a random vector.
                 </para>
             </listitem>
         </itemizedlist>
+    </sect3>
+
+    <sect3 id="zend.filter.set.encrypt.adapterusage">
+        <title>Adapter usage</title>
+
+        <para>
+            As these two encryption methodologies work completely different, also the usage of the
+            adapters differ. You have to select the adapter you want to use when initiating the
+            filter.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+// Use the Mcrypt adapter
+$filter1 = new Zend_Filter_Encrypt(array('adapter' => 'mcrypt'));
+
+// Use the OpenSSL adapter
+$filter2 = new Zend_Filter_Encrypt(array('adapter' => 'openssl'));
+]]></programlisting>
+
+        <para>
+            To set another adapter you can also use <methodname>setAdapter()</methodname>, and the
+            <methodname>getAdapter()</methodname> method to receive the actual set adapter.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+// Use the Mcrypt adapter
+$filter = new Zend_Filter_Encrypt();
+$filter->setAdapter('openssl');
+]]></programlisting>
+
+        <note>
+            <para>
+                When you do not supply the <property>adapter</property> option or do not use
+                <methodname>setAdapter()</methodname>, then the <classname>Mcrypt</classname>
+                adapter will be used per default.
+            </para>
+        </note>
+    </sect3>
+
+    <sect3 id="zend.filter.set.encrypt.mcrypt">
+        <title>Encryption with Mcrypt</title>
 
         <para>
-            If you give a string instead of an array, this string will be used as key.
+            When you have installed the <classname>Mcrypt</classname> extension you can use the
+            <classname>Mcrypt</classname> adapter. If you provide a string instead of an array of
+            options, this string will be used as key.
         </para>
 
         <para>
@@ -169,54 +230,62 @@ print $encrypted;
 ]]></programlisting>
     </sect3>
 
-    <sect3 id="zend.filter.set.encrypt.openssl">
-        <title>Encryption with OpenSSL</title>
+    <sect3 id="zend.filter.set.encrypt.mcryptdecrypt">
+        <title>Decryption with Mcrypt</title>
 
         <para>
-            When you have installed the <classname>OpenSSL</classname> extension you can use the
-            <classname>OpenSSL</classname> adapter. This adapter supports the following options at
-            initiation:
+            For decrypting content which was previously encrypted with <classname>Mcrypt</classname>
+            you need to have the options with which the encryption has been called.
         </para>
 
-        <itemizedlist>
-            <listitem>
-                <para>
-                    <emphasis>public</emphasis>: The public key of the user whom you want to provide
-                    the encrpted content. You can give multiple public keys by using an array. You
-                    can eigther provide the path and filename of the key file, or just the content
-                    of the key file itself.
-                </para>
-            </listitem>
+        <para>
+            There is one eminent difference for you. When you did not provide a vector at
+            encryption you need to get it after you encrypted the content by using the
+            <methodname>getVector()</methodname> method on the encryption filter. Without the
+            correct vector you will not be able to decrypt the content.
+        </para>
 
-            <listitem>
-                <para>
-                    <emphasis>private</emphasis>: Your private key which will be used for encrypting
-                    the content. Also the private key can be either a filename with path of the key
-                    file, or just the content of the key file itself.
-                </para>
-            </listitem>
+        <para>
+            As soon as you have provided all options decryption is as simple as encryption.
+        </para>
 
-            <listitem>
-                <para>
-                    <emphasis>compression</emphasis>: If the encrypted value should be compressed.
-                    Default is no compression.
-                </para>
-            </listitem>
+        <programlisting language="php"><![CDATA[
+// Use the default blowfish settings
+$filter = new Zend_Filter_Decrypt('myencryptionkey');
 
-            <listitem>
-                <para>
-                    <emphasis>package</emphasis>: If the envelope key should be packed with the
-                    encrypted value. Default is <constant>FALSE</constant>.
-                </para>
-            </listitem>
-        </itemizedlist>
+// Set the vector with which the content was encrypted
+$filter->setVector('myvector');
+
+$decrypted = $filter->filter('encoded_text_normally_unreadable');
+print $decrypted;
+]]></programlisting>
+
+        <note>
+            <para>
+                Note that you will get an exception if the mcrypt extension is not available in your
+                environment.
+            </para>
+        </note>
+
+        <note>
+            <para>
+                You should also note that all settings which be checked when you create the instance
+                or when you call <methodname>setEncryption()</methodname>. If mcrypt detects problem
+                with your settings an exception will be thrown.
+            </para>
+        </note>
+    </sect3>
+
+    <sect3 id="zend.filter.set.encrypt.openssl">
+        <title>Encryption with OpenSSL</title>
 
         <para>
-            You can get or set the public keys also afterwards with the
-            <methodname>getPublicKey()</methodname> and <methodname>setPublicKey()</methodname>
-            methods. The private key can also be get and set with the related
-            <methodname>getPrivateKey()</methodname> and <methodname>setPrivateKey()</methodname>
-            methods.
+            When you have installed the <classname>OpenSSL</classname> extension you can use the
+            <classname>OpenSSL</classname> adapter. You can get or set the public keys also
+            afterwards with the <methodname>getPublicKey()</methodname> and
+            <methodname>setPublicKey()</methodname> methods. The private key can also be get and set
+            with the related <methodname>getPrivateKey()</methodname> and
+            <methodname>setPrivateKey()</methodname> methods.
         </para>
 
         <programlisting language="php"><![CDATA[
@@ -380,6 +449,79 @@ $filter2 = new Zend_Filter_Encrypt(array(
             </note>
         </sect4>
     </sect3>
+
+    <sect3 id="zend.filter.set.encrypt.openssldecrypt">
+        <title>Decryption with OpenSSL</title>
+
+        <para>
+            Decryption with <classname>OpenSSL</classname> is as simple as encryption. But you need
+            to have all data from the person who encrypted the content. See the following example:
+        </para>
+
+        <programlisting language="php"><![CDATA[
+// Use openssl and provide a private key
+$filter = new Zend_Filter_Decrypt(array(
+    'adapter' => 'openssl',
+    'private' => '/path/to/mykey/private.pem'
+));
+
+// of course you can also give the envelope keys at initiation
+$filter->setEnvelopeKey(array(
+    '/key/from/encoder/first.pem',
+    '/key/from/encoder/second.pem'
+));
+]]></programlisting>
+
+        <note>
+            <para>
+                Note that the <classname>OpenSSL</classname> adapter will not work when you do not
+                provide valid keys.
+            </para>
+        </note>
+
+        <para>
+            Optionally it could be necessary to provide the passphrase for decrypting the keys
+            themself by using the <methodname>setPassphrase()</methodname> method.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+// Use openssl and provide a private key
+$filter = new Zend_Filter_Decrypt(array(
+    'adapter' => 'openssl',
+    'private' => '/path/to/mykey/private.pem'
+));
+
+// of course you can also give the envelope keys at initiation
+$filter->setEnvelopeKey(array(
+    '/key/from/encoder/first.pem',
+    '/key/from/encoder/second.pem'
+));
+$filter->setPassphrase('mypassphrase');
+]]></programlisting>
+
+        <para>
+            At last, decode the content. Our complete example for decrypting the previously
+            encrypted content looks like this.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+// Use openssl and provide a private key
+$filter = new Zend_Filter_Decrypt(array(
+    'adapter' => 'openssl',
+    'private' => '/path/to/mykey/private.pem'
+));
+
+// of course you can also give the envelope keys at initiation
+$filter->setEnvelopeKey(array(
+    '/key/from/encoder/first.pem',
+    '/key/from/encoder/second.pem'
+));
+$filter->setPassphrase('mypassphrase');
+
+$decrypted = $filter->filter('encoded_text_normally_unreadable');
+print $decrypted;
+]]></programlisting>
+    </sect3>
 </sect2>
 <!--
 vim:se ts=4 sw=4 et:

documentation/manual/en/module_specs/Zend_Filter-LocalizedToNormalized.xml

@@ -1,78 +1,121 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- Reviewed: no -->
 <sect2 id="zend.filter.set.localizedtonormalized">
-    <title>LocalizedToNormalized</title>
+    <title>LocalizedToNormalized and NormalizedToLocalized</title>
 
     <para>
-        This filter will change any given localized input to it's normalized representation. It
-        uses in Background <classname>Zend_Locale</classname> to do this transformation for you.
+        These two filters can change given localized input to it's normalized representation and
+        reverse. They use in Background <classname>Zend_Locale</classname> to do this transformation
+        for you.
     </para>
 
-    <para>
-        This allows your user to enter informations in his own language notation, and you can then
-        store the normalized value into your database for example.
-    </para>
+    <sect3 id="zend.filter.set.localizedtonormalized.options">
+        <title>
+            Supported options for Zend_Filter_LocalizedToNormalized and
+            Zend_Filter_NormalizedToLocalized
+        </title>
 
-    <note>
         <para>
-            Please note that normalization is not equal to translation. This filter can not
-            translate strings from one language into another like you could expect with months or
-            names of days.
+            The following options are supported for
+            <classname>Zend_Filter_LocalizedToNormalized</classname> and
+            <classname>Zend_Filter_NormalizedToLocalized</classname>:
         </para>
-    </note>
 
-    <para>
-        The following input types can be normalized:
-    </para>
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <emphasis><property>date_format</property></emphasis>: This sets the date format
+                    to use for normalization and to detect the localized date format
+                </para>
+            </listitem>
 
-    <itemizedlist>
-        <listitem>
-            <para>
-                <emphasis>integer</emphasis>: Integer numbers, which are localized, will be
-                normalized to the english notation.
-            </para>
-        </listitem>
+            <listitem>
+                <para>
+                    <emphasis><property>locale</property></emphasis>: This sets the locale to use
+                    for normalization and to detect the localized format
+                </para>
+            </listitem>
 
-        <listitem>
-            <para>
-                <emphasis>float</emphasis>: Float numbers, which are localized, will be normalized
-                to the english notation.
-            </para>
-        </listitem>
+            <listitem>
+                <para>
+                    <emphasis><property>precision</property></emphasis>: This sets the precision to
+                    use for number conversion
+                </para>
+            </listitem>
+        </itemizedlist>
+    </sect3>
 
-        <listitem>
-            <para>
-                <emphasis>numbers</emphasis>: Other numbers, like real, will be normalized
-                to the english notation.
-            </para>
-        </listitem>
+    <sect3 id="zend.filter.set.localizedtonormalized.workflow">
+        <title>Workflow</title>
 
-        <listitem>
-            <para>
-                <emphasis>time</emphasis>: Time values, will be normalized to a named array.
-            </para>
-        </listitem>
+        <para>
+            Normalization allows your user to enter informations in his own language notation, and
+            you can then store the normalized value into your database for example. Localization
+            on the other hand allows you to display normalized informations in a localized manner
+            to your user.
+        </para>
 
-        <listitem>
+        <note>
             <para>
-                <emphasis>date</emphasis>: Date values, will be normalized to a named array.
+                Please note that normalization and localization is not equal to translation. These
+                filters can not translate strings from one language into another like you could
+                expect with months or names of days.
             </para>
-        </listitem>
-    </itemizedlist>
+        </note>
 
-    <para>
-        Any other input will be returned as it, without changing it.
-    </para>
+        <para>
+            The following input types can be normalized and localized:
+        </para>
+
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <emphasis>integer</emphasis>: Integer numbers. Normalization returns the english
+                    notation
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis>float</emphasis>: Float numbers. Normalization returns the english
+                    notation
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis>numbers</emphasis>: Other numbers, like real. Normalization returns
+                    the english notation
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis>time</emphasis>: Time values. The normalized value is a named array
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis>date</emphasis>: Date values. The normalized value is a named array
+                </para>
+            </listitem>
+        </itemizedlist>
 
-    <note>
         <para>
-            You should note that normalized output is always given as string. Otherwise your
-            environment would transfer the normalized output automatically to the notation used
-            by the locale your environment is set to.
+            Any other input will be returned as is, without changing it.
         </para>
-    </note>
 
-    <sect3 id="zend.filter.set.localizedtonormalized.numbers">
+        <note>
+            <para>
+                You should note that normalized output is always given as string. Otherwise your
+                environment would transfer the normalized output automatically to the notation used
+                by the locale your environment is set to.
+            </para>
+        </note>
+    </sect3>
+
+    <sect3 id="zend.filter.set.localizedtonormalized.numbersnormal">
         <title>Normalization for numbers</title>
 
         <para>
@@ -101,38 +144,13 @@ $filter->filter('123.456,78');
 
         <para>
             You can also control how your normalized number has to look like. Therefor you can give
-            all options which are also used by <classname>Zend_Locale_Format</classname>. The most
-            common are:
-        </para>
-
-        <itemizedlist>
-            <listitem>
-                <para>
-                    <emphasis>date_format</emphasis>
-                </para>
-            </listitem>
-
-            <listitem>
-                <para>
-                    <emphasis>locale</emphasis>
-                </para>
-            </listitem>
-
-            <listitem>
-                <para>
-                    <emphasis>precision</emphasis>
-                </para>
-            </listitem>
-        </itemizedlist>
-
-        <para>
-            For details about how these options are used take a look into this
+            all options which are also used by <classname>Zend_Locale_Format</classname>. For
+            details about available options take a look into this
             <link linkend="zend.locale.parsing">Zend_Locale chapter</link>.
         </para>
 
         <para>
-            Below is a example with defined precision so you can see how options
-            work:
+            Below is a example with defined precision so you can see how options work:
         </para>
 
         <programlisting language="php"><![CDATA[
@@ -182,6 +200,93 @@ $filter->filter('11:22:33');
 // returns array('hour' => '33', 'minute' => '22', 'second' => '11')
 ]]></programlisting>
     </sect3>
+
+    <sect3 id="zend.filter.set.localizedtonormalized.numberslocal">
+        <title>Localization for numbers</title>
+
+        <para>
+            Any given number like integer, float or real value, can be localized. Note, that
+            numbers in scientific notation, can actually not be handled by this filter.
+        </para>
+
+        <para>
+            So how does localization work in detail for numbers:
+        </para>
+
+        <programlisting language="php"><![CDATA[
+// Initiate the filter
+$filter = new Zend_Filter_NormalizedToLocalized();
+$filter->filter(123456.78);
+// returns the value '123.456,78'
+]]></programlisting>
+
+        <para>
+            Let's expect you have set the locale 'de' as application wide locale.
+            <classname>Zend_Filter_NormalizedToLocalized</classname> will take the set locale and
+            use it to detect which sort of output you want to have. In our example it was a value
+            with precision. Now the filter will return you the localized representation for this
+            value as string.
+        </para>
+
+        <para>
+            You can also control how your localized number has to look like. Therefor you can give
+            all options which are also used by <classname>Zend_Locale_Format</classname>. For
+            details about how these options are used take a look into this
+            <link linkend="zend.locale.parsing">Zend_Locale chapter</link>.
+        </para>
+
+        <para>
+            Below is a example with defined precision so you can see how options
+            work:
+        </para>
+
+        <programlisting language="php"><![CDATA[
+// Numeric Filter
+$filter = new Zend_Filter_NormalizedToLocalized(array('precision' => 2));
+
+$filter->filter(123456);
+// returns the value '123.456,00'
+
+$filter->filter(123456.78901);
+// returns the value '123.456,79'
+]]></programlisting>
+    </sect3>
+
+    <sect3 id="zend.filter.set.normalizedtolocalized.dates">
+        <title>Localization for date and time</title>
+
+        <para>
+            Normalized for date and time values can also be localized. All given date and time
+            values will be returned as string, with the format defined by the set locale.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+// Initiate the filter
+$filter = new Zend_Filter_NormalizedToLocalized();
+$filter->filter(array('day' => '12', 'month' => '04', 'year' => '2009');
+// returns '12.04.2009'
+]]></programlisting>
+
+        <para>
+            Let's expect you have set the locale 'de' again. Now the input is automatically detected
+            as date, and will be returned in the format defined by the locale 'de'.
+        </para>
+
+        <para>
+            Of course you can also control how your date input looks like with the
+            <emphasis>date_format</emphasis>, and the <emphasis>locale</emphasis> option.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+// Date Filter
+$filter = new Zend_Filter_LocalizedToNormalized(
+    array('date_format' => 'ss:mm:HH')
+);
+
+$filter->filter(array('hour' => '33', 'minute' => '22', 'second' => '11'));
+// returns '11:22:33'
+]]></programlisting>
+    </sect3>
 </sect2>
 <!--
 vim:se ts=4 sw=4 et:

documentation/manual/en/module_specs/Zend_Filter-NormalizedToLocalized.xml

@@ -1,183 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- Reviewed: no -->
-<sect2 id="zend.filter.set.normalizedtolocalized">
-    <title>NormalizedToLocalized</title>
-
-    <para>
-        This filter is the reverse of the filter
-        <classname>Zend_Filter_LocalizedToNormalized</classname> and will change any given
-        normalized input to it's localized representation. It uses in Background
-        <classname>Zend_Locale</classname> to do this transformation for you.
-    </para>
-
-    <para>
-        This allows you to give your user any stored normalised value in a localized manner, your
-        user is more common to.
-    </para>
-
-    <note>
-        <para>
-            Please note that localization is not equal to translation. This filter can not translate
-            strings from one language into another like you could expect with months or names of
-            days.
-        </para>
-    </note>
-
-    <para>
-        The following input types can be localized:
-    </para>
-
-    <itemizedlist>
-        <listitem>
-            <para>
-                <emphasis>integer</emphasis>: Integer numbers, which are normalized, will be
-                localized to the set notation.
-            </para>
-        </listitem>
-
-        <listitem>
-            <para>
-                <emphasis>float</emphasis>: Float numbers, which are normalized, will be localized
-                to the set notation.
-            </para>
-        </listitem>
-
-        <listitem>
-            <para>
-                <emphasis>numbers</emphasis>: Other numbers, like real, will be localized
-                to the set notation.
-            </para>
-        </listitem>
-
-        <listitem>
-            <para>
-                <emphasis>time</emphasis>: Time values, will be localized to a string.
-            </para>
-        </listitem>
-
-        <listitem>
-            <para>
-                <emphasis>date</emphasis>: Date values, will be normalized to a string.
-            </para>
-        </listitem>
-    </itemizedlist>
-
-    <para>
-        Any other input will be returned as it, without changing it.
-    </para>
-
-    <sect3 id="zend.filter.set.normalizedtolocalized.numbers">
-        <title>Localization for numbers</title>
-
-        <para>
-            Any given number like integer, float or real value, can be localized. Note, that
-            numbers in scientific notation, can actually not be handled by this filter.
-        </para>
-
-        <para>
-            So how does localization work in detail for numbers:
-        </para>
-
-        <programlisting language="php"><![CDATA[
-// Initiate the filter
-$filter = new Zend_Filter_NormalizedToLocalized();
-$filter->filter(123456.78);
-// returns the value '123.456,78'
-]]></programlisting>
-
-        <para>
-            Let's expect you have set the locale 'de' as application wide locale.
-            <classname>Zend_Filter_NormalizedToLocalized</classname> will take the set locale and
-            use it to detect which sort of output you want to have. In our example it was a value
-            with precision. Now the filter will return you the localized representation for this
-            value as string.
-        </para>
-
-        <para>
-            You can also control how your localized number has to look like. Therefor you can give
-            all options which are also used by <classname>Zend_Locale_Format</classname>. The most
-            common are:
-        </para>
-
-        <itemizedlist>
-            <listitem>
-                <para>
-                    <emphasis>date_format</emphasis>
-                </para>
-            </listitem>
-
-            <listitem>
-                <para>
-                    <emphasis>locale</emphasis>
-                </para>
-            </listitem>
-
-            <listitem>
-                <para>
-                    <emphasis>precision</emphasis>
-                </para>
-            </listitem>
-        </itemizedlist>
-
-        <para>
-            For details about how these options are used take a look into this
-            <link linkend="zend.locale.parsing">Zend_Locale chapter</link>.
-        </para>
-
-        <para>
-            Below is a example with defined precision so you can see how options
-            work:
-        </para>
-
-        <programlisting language="php"><![CDATA[
-// Numeric Filter
-$filter = new Zend_Filter_NormalizedToLocalized(array('precision' => 2));
-
-$filter->filter(123456);
-// returns the value '123.456,00'
-
-$filter->filter(123456.78901);
-// returns the value '123.456,79'
-]]></programlisting>
-    </sect3>
-
-    <sect3 id="zend.filter.set.normalizedtolocalized.dates">
-        <title>Localization for date and time</title>
-
-        <para>
-            Normalized for date and time values can also be localized. All given date and time
-            values will be returned as string, with the format defined by the set locale.
-        </para>
-
-        <programlisting language="php"><![CDATA[
-// Initiate the filter
-$filter = new Zend_Filter_NormalizedToLocalized();
-$filter->filter(array('day' => '12', 'month' => '04', 'year' => '2009');
-// returns '12.04.2009'
-]]></programlisting>
-
-        <para>
-            Let's expect you have set the locale 'de' again. Now the input is automatically detected
-            as date, and will be returned in the format defined by the locale 'de'.
-        </para>
-
-        <para>
-            Of course you can also control how your date input looks like with the
-            <emphasis>date_format</emphasis>, and the <emphasis>locale</emphasis> option.
-        </para>
-
-        <programlisting language="php"><![CDATA[
-// Date Filter
-$filter = new Zend_Filter_LocalizedToNormalized(
-    array('date_format' => 'ss:mm:HH')
-);
-
-$filter->filter(array('hour' => '33', 'minute' => '22', 'second' => '11'));
-// returns '11:22:33'
-]]></programlisting>
-    </sect3>
-</sect2>
-
-<!--
-vim:se ts=4 sw=4 et:
--->

documentation/manual/en/module_specs/Zend_Filter-Null.xml

@@ -9,6 +9,23 @@
         <constant>NULL</constant> value instead of a boolean or any other type.
     </para>
 
+    <sect3 id="zend.filter.set.null.options">
+        <title>Supported options for Zend_Filter_Null</title>
+
+        <para>
+            The following options are supported for <classname>Zend_Filter_Null</classname>:
+        </para>
+
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <emphasis><property>type</property></emphasis>: The variable type which should
+                    be supported.
+                </para>
+            </listitem>
+        </itemizedlist>
+    </sect3>
+
     <sect3 id="zend.filter.set.null.default">
         <title>Default behaviour for Zend_Filter_Null</title>
 

documentation/manual/en/module_specs/Zend_Filter-PregReplace.xml

@@ -8,19 +8,50 @@
         and replaces all found elements.
     </para>
 
-    <para>
-        The option <property>match</property> has to be given to set the pattern which will be
-        searched for. It can be a string for a single pattern, or an array of strings for multiple
-        pattern.
-    </para>
+    <sect3 id="zend.filter.set.pregreplace.options">
+        <title>Supported options for Zend_Filter_PregReplace</title>
 
-    <para>
-        To set the pattern which will be used as replacement the option <property>replace</property>
-        has to be used. It can be a string for a single pattern, or an array of strings for multiple
-        pattern.
-    </para>
+        <para>
+            The following options are supported for <classname>Zend_Filter_PregReplace</classname>:
+        </para>
+
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <emphasis><property>match</property></emphasis>: The pattern which will be
+                    searched for.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
+                    <emphasis><property>replace</property></emphasis>: The string which is used as
+                    replacement for the matches.
+                </para>
+            </listitem>
+        </itemizedlist>
+    </sect3>
+
+    <sect3 id="zend.filter.set.pregreplace.basic">
+        <title>Basic usage</title>
 
-    <programlisting language="php"><![CDATA[
+        <para>
+            To use this filter properly you must give two options:
+        </para>
+
+        <para>
+            The option <property>match</property> has to be given to set the pattern which will be
+            searched for. It can be a string for a single pattern, or an array of strings for
+            multiple pattern.
+        </para>
+
+        <para>
+            To set the pattern which will be used as replacement the option
+            <property>replace</property> has to be used. It can be a string for a single pattern, or
+            an array of strings for multiple pattern.
+        </para>
+
+        <programlisting language="php"><![CDATA[
 $filter = new Zend_Filter_PregReplace(array('match' => 'bob',
                                             'replace' => 'john'));
 $input  = 'Hy bob!";
@@ -29,14 +60,14 @@ $filter->filter($input);
 // returns 'Hy john!'
 ]]></programlisting>
 
-    <para>
-        You can use <methodname>getMatchPattern()</methodname> and
-        <methodname>setMatchPattern()</methodname> to set the matching pattern afterwards. To set
-        the replacement pattern you can use <methodname>getReplacement()</methodname> and
-        <methodname>setReplacement()</methodname>.
-    </para>
+        <para>
+            You can use <methodname>getMatchPattern()</methodname> and
+            <methodname>setMatchPattern()</methodname> to set the matching pattern afterwards. To
+            set the replacement pattern you can use <methodname>getReplacement()</methodname> and
+            <methodname>setReplacement()</methodname>.
+        </para>
 
-    <programlisting language="php"><![CDATA[
+        <programlisting language="php"><![CDATA[
 $filter = new Zend_Filter_PregReplace();
 $filter->setMatchPattern(array('bob', 'Hy'))
        ->setReplacement(array('john', 'Bye'));
@@ -46,9 +77,10 @@ $filter->filter($input);
 // returns 'Bye john!'
 ]]></programlisting>
 
-    <para>
-        For a more complex usage take a look into <acronym>PHP</acronym>'s <ulink
-            url="http://www.php.net/manual/en/reference.pcre.pattern.modifiers.php">PCRE
-            Pattern Chapter</ulink>.
-    </para>
+        <para>
+            For a more complex usage take a look into <acronym>PHP</acronym>'s <ulink
+                url="http://www.php.net/manual/en/reference.pcre.pattern.modifiers.php">PCRE
+                Pattern Chapter</ulink>.
+        </para>
+    </sect3>
 </sect2>

documentation/manual/en/module_specs/Zend_Filter-RealPath.xml

@@ -5,35 +5,64 @@
 
     <para>
         This filter will resolve given links and pathnames and returns canonicalized absolute
-        pathnames. References to '<filename>/./</filename>', '<filename>/../</filename>' and extra
-        '<filename>/</filename>' characters in the input path will be stripped. The resulting path
-        will not have any symbolic link, '<filename>/./</filename>' or '<filename>/../</filename>'
-        character.
+        pathnames.
     </para>
 
-    <para>
-        <classname>Zend_Filter_RealPath</classname> will return <constant>FALSE</constant> on
-        failure, e.g. if the file does not exist. On <acronym>BSD</acronym> systems
-        <classname>Zend_Filter_RealPath</classname> doesn't fail if only the last path component
-        doesn't exist, while other systems will return <constant>FALSE</constant>.
-    </para>
+    <sect3 id="zend.filter.set.realpath.options">
+        <title>Supported options for Zend_Filter_RealPath</title>
+
+        <para>
+            The following options are supported for <classname>Zend_Filter_RealPath</classname>:
+        </para>
+
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <emphasis><property>exists</property></emphasis>: This option defaults to
+                    <constant>TRUE</constant> which checks if the given path really exists.
+                </para>
+            </listitem>
+        </itemizedlist>
+    </sect3>
+
+    <sect3 id="zend.filter.set.realpath.basic">
+        <title>Basic usage</title>
 
-    <programlisting language="php"><![CDATA[
+        <para>
+            For any given link of pathname its absolute path will be returned.
+            References to '<filename>/./</filename>', '<filename>/../</filename>' and extra
+            '<filename>/</filename>' characters in the input path will be stripped. The resulting
+            path will not have any symbolic link, '<filename>/./</filename>' or
+            '<filename>/../</filename>' character.
+        </para>
+
+        <para>
+            <classname>Zend_Filter_RealPath</classname> will return <constant>FALSE</constant> on
+            failure, e.g. if the file does not exist. On <acronym>BSD</acronym> systems
+            <classname>Zend_Filter_RealPath</classname> doesn't fail if only the last path component
+            doesn't exist, while other systems will return <constant>FALSE</constant>.
+        </para>
+
+        <programlisting language="php"><![CDATA[
 $filter = new Zend_Filter_RealPath();
 $path   = '/www/var/path/../../mypath';
 $filtered = $filter->filter($path);
 
 // returns '/www/mypath'
 ]]></programlisting>
+    </sect3>
 
-    <para>
-        Sometimes it is useful to get also paths when they don't exist, f.e. when you want to
-        get the real path for a path which you want to create. You can then either give a
-        <constant>FALSE</constant> at initiation, or use <methodname>setExists()</methodname> to
-        set it.
-    </para>
+    <sect3 id="zend.filter.set.realpath.exists">
+        <title>Non existing paths</title>
+
+        <para>
+            Sometimes it is useful to get also paths when they don't exist, f.e. when you want to
+            get the real path for a path which you want to create. You can then either give a
+            <constant>FALSE</constant> at initiation, or use <methodname>setExists()</methodname> to
+            set it.
+        </para>
 
-    <programlisting language="php"><![CDATA[
+        <programlisting language="php"><![CDATA[
 $filter = new Zend_Filter_RealPath(false);
 $path   = '/www/var/path/../../non/existing/path';
 $filtered = $filter->filter($path);
@@ -41,4 +70,5 @@ $filtered = $filter->filter($path);
 // returns '/www/non/existing/path'
 // even when file_exists or realpath would return false
 ]]></programlisting>
+    </sect3>
 </sect2>

documentation/manual/en/module_specs/Zend_Filter-Set.xml

@@ -13,28 +13,19 @@
     <xi:include href="Zend_Filter-Boolean.xml" />
     <xi:include href="Zend_Filter-Callback.xml" />
     <xi:include href="Zend_Filter-Compress.xml" />
-    <xi:include href="Zend_Filter-Decryption.xml" />
     <xi:include href="Zend_Filter-Digits.xml" />
     <xi:include href="Zend_Filter-Dir.xml" />
     <xi:include href="Zend_Filter-Encryption.xml" />
     <xi:include href="Zend_Filter-HtmlEntities.xml" />
     <xi:include href="Zend_Filter-Int.xml" />
     <xi:include href="Zend_Filter-LocalizedToNormalized.xml" />
-    <xi:include href="Zend_Filter-NormalizedToLocalized.xml" />
     <xi:include href="Zend_Filter-Null.xml" />
     <xi:include href="Zend_Filter-PregReplace.xml" />
     <xi:include href="Zend_Filter-RealPath.xml" />
     <xi:include href="Zend_Filter-StringToLower.xml" />
     <xi:include href="Zend_Filter-StringToUpper.xml" />
     <xi:include href="Zend_Filter-StringTrim.xml" />
-
-    <sect2 id="zend.filter.set.stripnewlines">
-        <title>StripNewlines</title>
-
-        <para>
-            Returns the string <varname>$value</varname> without any newline control characters.
-        </para>
-    </sect2>
+    <xi:include href="Zend_Filter-StripNewLines.xml" />
 
     <sect2 id="zend.filter.set.striptags">
         <title>StripTags</title>

documentation/manual/en/module_specs/Zend_Filter-StringToLower.xml

@@ -7,23 +7,52 @@
         This filter converts any input to be lowercased.
     </para>
 
-    <programlisting language="php"><![CDATA[
+    <sect3 id="zend.filter.set.stringtolower.options">
+        <title>Supported options for Zend_Filter_StringToLower</title>
+
+        <para>
+            The following options are supported for
+            <classname>Zend_Filter_StringToLower</classname>:
+        </para>
+
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <emphasis><property>encoding</property></emphasis>: This option can be used to
+                    set an encoding which has to be used.
+                </para>
+            </listitem>
+        </itemizedlist>
+    </sect3>
+
+    <sect3 id="zend.filter.set.stringtolower.basic">
+        <title>Basic usage</title>
+
+        <para>
+            This is a basic example:
+        </para>
+
+        <programlisting language="php"><![CDATA[
 $filter = new Zend_Filter_StringToLower();
 
 print $filter->filter('SAMPLE');
 // returns "sample"
 ]]></programlisting>
+    </sect3>
 
-    <para>
-        Per default it will only handle characters from the actual locale of your
-        server. Characters from other charsets would be ignored. Still, it's
-        possible to also lowercase them when the mbstring extension is available
-        in your environment. Simply set the wished encoding when initiating the
-        <classname>StringToLower</classname> filter. Or use the
-        <methodname>setEncoding()</methodname> method to change the encoding afterwards.
-    </para>
+    <sect3 id="zend.filter.set.stringtolower.encoding">
+        <title>Different encoded strings</title>
+
+        <para>
+            Per default it will only handle characters from the actual locale of your
+            server. Characters from other charsets would be ignored. Still, it's
+            possible to also lowercase them when the mbstring extension is available
+            in your environment. Simply set the wished encoding when initiating the
+            <classname>StringToLower</classname> filter. Or use the
+            <methodname>setEncoding()</methodname> method to change the encoding afterwards.
+        </para>
 
-    <programlisting language="php"><![CDATA[
+        <programlisting language="php"><![CDATA[
 // using UTF-8
 $filter = new Zend_Filter_StringToLower('UTF-8');
 
@@ -34,17 +63,18 @@ $filter = new Zend_Filter_StringToLower(array('encoding' => 'UTF-8'));
 $filter->setEncoding('ISO-8859-1');
 ]]></programlisting>
 
-    <note>
-        <title>Setting wrong encodings</title>
+        <note>
+            <title>Setting wrong encodings</title>
 
-        <para>
-            Be aware that you will get an exception when you want to set an encoding
-            and the mbstring extension is not available in your environment.
-        </para>
+            <para>
+                Be aware that you will get an exception when you want to set an encoding
+                and the mbstring extension is not available in your environment.
+            </para>
 
-        <para>
-            Also when you are trying to set an encoding which is not supported by your
-            mbstring extension you will get an exception.
-        </para>
-    </note>
+            <para>
+                Also when you are trying to set an encoding which is not supported by your
+                mbstring extension you will get an exception.
+            </para>
+        </note>
+    </sect3>
 </sect2>

documentation/manual/en/module_specs/Zend_Filter-StringToUpper.xml

@@ -7,23 +7,54 @@
         This filter converts any input to be uppercased.
     </para>
 
-    <programlisting language="php"><![CDATA[
+    <sect3 id="zend.filter.set.stringtoupper.options">
+        <title>Supported options for Zend_Filter_StringToUpper</title>
+
+        <para>
+            The following options are supported for
+            <classname>Zend_Filter_StringToUpper</classname>:
+        </para>
+
+        <itemizedlist>
+            <listitem>
+                <para>
+                    <emphasis><property>encoding</property></emphasis>: This option can be used to
+                    set an encoding which has to be used.
+                </para>
+            </listitem>
+        </itemizedlist>
+    </sect3>
+
+    <sect3 id="zend.filter.set.stringtoupper.basic">
+        <title>Basic usage</title>
+
+        <para>
+            This is a basic example for using the <classname>StringToUpper</classname> filter:
+        </para>
+
+        <programlisting language="php"><![CDATA[
 $filter = new Zend_Filter_StringToUpper();
 
 print $filter->filter('Sample');
 // returns "SAMPLE"
 ]]></programlisting>
 
-    <para>
-        Like the <classname>StringToLower</classname> filter, this filter handles
-        only characters from the actual locale of your server. Using different
-        character sets works the same as with <classname>StringToLower</classname>.
-    </para>
+    </sect3>
+
+    <sect3 id="zend.filter.set.stringtoupper.encoding">
+        <title>Different encoded strings</title>
+
+        <para>
+            Like the <classname>StringToLower</classname> filter, this filter handles
+            only characters from the actual locale of your server. Using different
+            character sets works the same as with <classname>StringToLower</classname>.
+        </para>
 
-    <programlisting language="php"><![CDATA[
+        <programlisting language="php"><![CDATA[
 $filter = new Zend_Filter_StringToUpper(array('encoding' => 'UTF-8'));
 
 // or do this afterwards
 $filter->setEncoding('ISO-8859-1');
 ]]></programlisting>
+    </sect3>
 </sect2>

documentation/manual/en/module_specs/Zend_Filter-StringTrim.xml

@@ -44,7 +44,6 @@ print $filter->filter(' This is (my) content: ');
             The above example returns 'This is (my) content:'. Notice that the whitespace characters
             have been removed.
         </para>
-
     </sect3>
 
     <sect3 id="zend.filter.set.stringtrim.types">
@@ -66,7 +65,6 @@ print $filter->filter(' This is (my) content:');
             The <methodname>getCharList()</methodname> return the values set for charlist.
         </para>
     </sect3>
-
 </sect2>
 <!--
 vim:se ts=4 sw=4 et:

documentation/manual/en/module_specs/Zend_Filter-StripNewLines.xml

@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Reviewed: no -->
+<sect2 id="zend.filter.set.stripnewlines">
+    <title>StripNewLines</title>
+
+    <para>
+        This filter modifies a given string and removes all new line characters within that string.
+    </para>
+
+     <sect3 id="zend.filter.set.strinpnewlines.options">
+        <title>Supported options for Zend_Filter_StripNewLines</title>
+
+        <para>
+            There are no additional options for <classname>Zend_Filter_StripNewLines</classname>.
+        </para>
+    </sect3>
+
+    <sect3 id="zend.filter.set.stripnewlines.basic">
+        <title>Basic usage</title>
+
+        <para>
+            A basic example of usage is below:
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$filter = new Zend_Filter_StripNewLines();
+
+print $filter->filter("This is (my)\n\rcontent: ');
+]]></programlisting>
+
+        <para>
+            The above example returns 'This is (my) content:'. Notice that all newline characters
+            have been removed.
+        </para>
+    </sect3>
+</sect2>
+<!--
+vim:se ts=4 sw=4 et:
+-->