ZF-7001 - Document Zend_Mail::setHeaderEncoding with example and suggestions for edge-cases.

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

documentation/manual/en/module_specs/Zend_Mail-Encoding.xml

@@ -9,6 +9,24 @@
         call or assigned to the MIME part object later. 7Bit and 8Bit encoding currently only pass on the
         binary content data.
     </para>
+
+    <para>
+        Header Encoding, especially the encoding of the subject, is a tricky topic. Zend_Mime currently implements
+        its own algorithm to encode quoted printable headers according to RFC-2045.
+        This due to the problems of <code>iconv_mime_encode</code> and <code>mb_encode_mimeheader</code>
+        with regards to certain charsets. This algorithm only breaks the header at spaces, which might lead to headers
+        that far exceed the suggested length of 76 chars. For this cases it is suggested to switch to BASE64
+        header encoding as the following example describes:
+    </para>
+
+    <programlisting language="php"><![CDATA[
+// By default Zend_Mime::ENCODING_QUOTEDPRINTABLE
+$mail = new Zend_Mail('UTF-8');
+
+// Reset to Base64 Encoding.
+$mail->setHeaderEncoding(Zend_Mime::ENCODING_BASE64);
+]]></programlisting>
+
     <para>
         <classname>Zend_Mail_Transport_Smtp</classname> encodes lines starting with one dot or two dots so that the mail
         does not violate the SMTP protocol.