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