mod_charset_lite.xml revision 6b040c2a2a566388097aab66dff8c3c94e853f22
721fdd19e2abef2e8dc46eb5c022ef14efe3367estoddard<?xml-stylesheet type="text/xsl" href="/style/manual.xsl"?>
e942c741056732f50da2074b36fe59805d370650slive<modulesynopsis>
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd<description>specify character set translation or recoding</description>
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd <p>This is an <strong>experimental</strong> module and should
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd be used with care. Experiment with your
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd <code>mod_charset_lite</code> configuration to ensure that it
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd performs the desired function.</p>
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd <p><module>mod_charset_lite</module> allows the administrator to
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd specify the source character set of objects as well as the
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd character set they should be translated into before sending to the
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd client. <module>mod_charset_lite</module> does not translate the
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd data itself but instead tells Apache what translation to
7db9f691a00ead175b03335457ca296a33ddf31bnd perform. <module>mod_charset_lite</module> is applicable to EBCDIC
721fdd19e2abef2e8dc46eb5c022ef14efe3367estoddard and ASCII host environments. In an EBCDIC environment, Apache
721fdd19e2abef2e8dc46eb5c022ef14efe3367estoddard normally translates text content from the code page of the Apache
1e5b300cc68389a18fe3762b1b980b0c86712ba1stoddard process locale to ISO-8859-1. <module>mod_charset_lite</module>
721fdd19e2abef2e8dc46eb5c022ef14efe3367estoddard can be used to specify that a different translation is to be
721fdd19e2abef2e8dc46eb5c022ef14efe3367estoddard performed. In an ASCII environment, Apache normally performs no
721fdd19e2abef2e8dc46eb5c022ef14efe3367estoddard translation, so <module>mod_charset_lite</module> is needed in
721fdd19e2abef2e8dc46eb5c022ef14efe3367estoddard order for any translation to take place.</p>
88c775368960b64afcdfd93a812f466a109746baerikabele <p>This module provides a small subset of configuration
15f37a157fbbf107658ed82ec30c348a9b6e518end mechanisms implemented by Russian Apache and its associated
3ec4de296cf8eb31d8a59811b58720efafccf109patrikj module="mod_charset_lite">CharsetSourceEnc</directive> and
97a9a944b5887e91042b019776c41d5dd74557aferikabele <directive module="mod_charset_lite">CharsetDefault</directive>
62e52789bfc10a5fd0a433af77e77c8ebbbed6c2rederpj must be acceptable to the translation mechanism used by APR on the
15f37a157fbbf107658ed82ec30c348a9b6e518end system where <module>mod_charset_lite</module> is deployed. These
97a9a944b5887e91042b019776c41d5dd74557aferikabele character set names are not standardized and are usually not the
62e52789bfc10a5fd0a433af77e77c8ebbbed6c2rederpj same as the corresponding values used in http headers. Currently,
15f37a157fbbf107658ed82ec30c348a9b6e518end APR can only use iconv(3), so you can easily test your character
15f37a157fbbf107658ed82ec30c348a9b6e518end set names using the iconv(1) program, as follows:</p>
62e52789bfc10a5fd0a433af77e77c8ebbbed6c2rederpj iconv -f charsetsourceenc-value -t charsetdefault-value
15f37a157fbbf107658ed82ec30c348a9b6e518end<section><title>Mismatch between character set of content and translation
62e52789bfc10a5fd0a433af77e77c8ebbbed6c2rederpj rules</title>
88c775368960b64afcdfd93a812f466a109746baerikabele <p>If the translation rules don't make sense for the content,
1e5b300cc68389a18fe3762b1b980b0c86712ba1stoddard translation can fail in various ways, including:</p>
1e5b300cc68389a18fe3762b1b980b0c86712ba1stoddard <li>The translation mechanism may return a bad return code,
1e5b300cc68389a18fe3762b1b980b0c86712ba1stoddard and the connection will be aborted.</li>
1e5b300cc68389a18fe3762b1b980b0c86712ba1stoddard <li>The translation mechanism may silently place special
1e5b300cc68389a18fe3762b1b980b0c86712ba1stoddard characters (e.g., question marks) in the output buffer when
1e5b300cc68389a18fe3762b1b980b0c86712ba1stoddard it cannot translate the input buffer.</li>
1e5b300cc68389a18fe3762b1b980b0c86712ba1stoddard<directivesynopsis>
1e5b300cc68389a18fe3762b1b980b0c86712ba1stoddard<context>virtual host</context><context>directory</context>
1e5b300cc68389a18fe3762b1b980b0c86712ba1stoddard</contextlist>
1e5b300cc68389a18fe3762b1b980b0c86712ba1stoddard <p>The <directive>CharsetSourceEnc</directive> directive specifies the
1e5b300cc68389a18fe3762b1b980b0c86712ba1stoddard source charset of files in the associated container.</p>
d860c376b575fdd8b315452b603b972657776365stoddard <p>The value of the <em>charset</em> argument must be accepted
1e5b300cc68389a18fe3762b1b980b0c86712ba1stoddard as a valid character set name by the character set support in
1e5b300cc68389a18fe3762b1b980b0c86712ba1stoddard APR. Generally, this means that it must be supported by
15f37a157fbbf107658ed82ec30c348a9b6e518end <Directory "/export/home/trawick/apacheinst/htdocs/convert"><br />
15f37a157fbbf107658ed82ec30c348a9b6e518end CharsetSourceEnc UTF-16BE<br />
15f37a157fbbf107658ed82ec30c348a9b6e518end CharsetDefault ISO8859-1<br />
15f37a157fbbf107658ed82ec30c348a9b6e518end </Directory>
15f37a157fbbf107658ed82ec30c348a9b6e518end <p>The character set names in this example work with the iconv
15f37a157fbbf107658ed82ec30c348a9b6e518end translation support in Solaris 8.</p>
15f37a157fbbf107658ed82ec30c348a9b6e518end</directivesynopsis>
15f37a157fbbf107658ed82ec30c348a9b6e518end<directivesynopsis>
15f37a157fbbf107658ed82ec30c348a9b6e518end<context>virtual host</context><context>directory</context>
15f37a157fbbf107658ed82ec30c348a9b6e518end</contextlist>
15f37a157fbbf107658ed82ec30c348a9b6e518end <p>The <directive>CharsetDefault</directive> directive specifies the
15f37a157fbbf107658ed82ec30c348a9b6e518end charset that content in the associated container should be
62e52789bfc10a5fd0a433af77e77c8ebbbed6c2rederpj translated to.</p>
15f37a157fbbf107658ed82ec30c348a9b6e518end <p>The value of the <em>charset</em> argument must be accepted
15f37a157fbbf107658ed82ec30c348a9b6e518end as a valid character set name by the character set support in
15f37a157fbbf107658ed82ec30c348a9b6e518end APR. Generally, this means that it must be supported by
15f37a157fbbf107658ed82ec30c348a9b6e518end iconv.</p>
15f37a157fbbf107658ed82ec30c348a9b6e518end <Directory "/export/home/trawick/apacheinst/htdocs/convert"><br />
15f37a157fbbf107658ed82ec30c348a9b6e518end CharsetSourceEnc UTF-16BE<br />
721fdd19e2abef2e8dc46eb5c022ef14efe3367estoddard CharsetDefault ISO8859-1<br />
721fdd19e2abef2e8dc46eb5c022ef14efe3367estoddard </Directory>
62e52789bfc10a5fd0a433af77e77c8ebbbed6c2rederpj</directivesynopsis>
15f37a157fbbf107658ed82ec30c348a9b6e518end<directivesynopsis>
15f37a157fbbf107658ed82ec30c348a9b6e518end<syntax>CharsetOptions <em>option</em> [<em>option</em>] ...</syntax>
15f37a157fbbf107658ed82ec30c348a9b6e518end<context>virtual host</context><context>directory</context>
62e52789bfc10a5fd0a433af77e77c8ebbbed6c2rederpj</contextlist>
62e52789bfc10a5fd0a433af77e77c8ebbbed6c2rederpj <p>The <directive>CharsetOptions</directive> directive configures certain
62e52789bfc10a5fd0a433af77e77c8ebbbed6c2rederpj behaviors of <module>mod_charset_lite</module>. <em>Option</em> can
62e52789bfc10a5fd0a433af77e77c8ebbbed6c2rederpj be one of</p>
62e52789bfc10a5fd0a433af77e77c8ebbbed6c2rederpj <dd>The <code>DebugLevel</code> keyword allows you to specify
62e52789bfc10a5fd0a433af77e77c8ebbbed6c2rederpj the level of debug messages generated by
62e52789bfc10a5fd0a433af77e77c8ebbbed6c2rederpj <module>mod_charset_lite</module>. By default, no messages are
62e52789bfc10a5fd0a433af77e77c8ebbbed6c2rederpj generated. This is equivalent to <code>DebugLevel=0</code>.
721fdd19e2abef2e8dc46eb5c022ef14efe3367estoddard With higher numbers, more debug messages are generated, and
15f37a157fbbf107658ed82ec30c348a9b6e518end server performance will be degraded. The actual meanings of
15f37a157fbbf107658ed82ec30c348a9b6e518end the numeric values are described with the definitions of the
15f37a157fbbf107658ed82ec30c348a9b6e518end DBGLVL_ constants near the beginning of
721fdd19e2abef2e8dc46eb5c022ef14efe3367estoddard <dd>The <code>ImplicitAdd</code> keyword specifies that
721fdd19e2abef2e8dc46eb5c022ef14efe3367estoddard <module>mod_charset_lite</module> should implicitly insert its
721fdd19e2abef2e8dc46eb5c022ef14efe3367estoddard filter when the configuration specifies that the character
62e52789bfc10a5fd0a433af77e77c8ebbbed6c2rederpj set of content should be translated. If the filter chain is
62e52789bfc10a5fd0a433af77e77c8ebbbed6c2rederpj explicitly configured using the AddOutputFilter directive,
15f37a157fbbf107658ed82ec30c348a9b6e518end <module>mod_charset_lite</module> doesn't add its filter.</dd>
721fdd19e2abef2e8dc46eb5c022ef14efe3367estoddard</directivesynopsis>
15f37a157fbbf107658ed82ec30c348a9b6e518end</modulesynopsis>