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