mod_charset_lite.xml revision db965e00e32a191217813eba97d8978887942501
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
3016c72ae8173bcfc0989ff1b297d4f27f445108lgentis<!-- $LastChangedRevision$ -->
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor Licensed to the Apache Software Foundation (ASF) under one or more
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor contributor license agreements. See the NOTICE file distributed with
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor this work for additional information regarding copyright ownership.
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor The ASF licenses this file to You under the Apache License, Version 2.0
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor (the "License"); you may not use this file except in compliance with
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor the License. You may obtain a copy of the License at
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor Unless required by applicable law or agreed to in writing, software
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor distributed under the License is distributed on an "AS IS" BASIS,
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor See the License for the specific language governing permissions and
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor limitations under the License.
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor<description>Specify character set translation or recoding</description>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <p><module>mod_charset_lite</module> allows the server to change
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor the character set of responses before sending them to the client.
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor In an EBCDIC environment, Apache always translates HTTP protocol
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor content (e.g. response headers) from the code page of the Apache
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor process locale to ISO-8859-1, but not the body of responses. In
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor any environment, <module>mod_charset_lite</module> can be used to
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor specify that response bodies should be translated. For example,
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor if files are stored in EBCDIC, then
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <module>mod_charset_lite</module> can translate them to
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor ISO-8859-1 before sending them to the client.</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
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <module>mod_charset_lite</module> is deployed. These character
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor set names are not standardized and are usually not the same as
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor the corresponding values used in http headers. Currently, APR
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor can only use iconv(3), so you can easily test your character set
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor names using the iconv(1) program, as follows:</p>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor iconv -f charsetsourceenc-value -t charsetdefault-value
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <section><title>Mismatch between character set of content and translation
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor rules</title>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <p>If the translation rules don't make sense for the content,
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor translation can fail in various ways, including:</p>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <li>The translation mechanism may return a bad return code,
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor and the connection will be aborted.</li>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <li>The translation mechanism may silently place special
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor characters (e.g., question marks) in the output buffer when
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor it cannot translate the input buffer.</li>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor<directivesynopsis>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor<context>virtual host</context><context>directory</context>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor</contextlist>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <p>The <directive>CharsetSourceEnc</directive> directive specifies the
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor source charset of files in the associated container.</p>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <p>The value of the <var>charset</var> argument must be accepted
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor as a valid character set name by the character set support in
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <glossary>APR</glossary>. Generally, this means that it must be
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor supported by iconv.</p>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <Directory /export/home/trawick/apacheinst/htdocs/convert><br />
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor CharsetSourceEnc UTF-16BE<br />
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor CharsetDefault ISO-8859-1<br />
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor </Directory>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <p>The character set names in this example work with the iconv
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor translation support in Solaris 8.</p>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor Specifying the same charset for both <directive module="mod_charset_lite">CharsetSourceEnc</directive>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor and <directive module="mod_charset_lite">CharsetDefault</directive> disables translation. The charset
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor need not match the charset of the response, but it must be a valid charset on the system.
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor</directivesynopsis>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor<directivesynopsis>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor<context>virtual host</context><context>directory</context>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor</contextlist>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <p>The <directive>CharsetDefault</directive> directive specifies the
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor charset that content in the associated container should be
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor translated to.</p>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <p>The value of the <var>charset</var> argument must be accepted
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor as a valid character set name by the character set support in
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <glossary>APR</glossary>. Generally, this means that it must be
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor supported by iconv.</p>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <Directory /export/home/trawick/apacheinst/htdocs/convert><br />
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor CharsetSourceEnc UTF-16BE<br />
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor CharsetDefault ISO-8859-1<br />
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor </Directory>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor Specifying the same charset for both <directive module="mod_charset_lite">CharsetSourceEnc</directive>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor and <directive module="mod_charset_lite">CharsetDefault</directive> disables translation. The charset
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor need not match the charset of the response, but it must be a valid charset on the system.
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor</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 ImplicitAdd</default>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor<context>virtual host</context><context>directory</context>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor</contextlist>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <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>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <dd>The <code>DebugLevel</code> keyword allows you to specify
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor the level of debug messages generated by
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <module>mod_charset_lite</module>. By default, no messages are
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor generated. This is equivalent to <code>DebugLevel=0</code>.
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor With higher numbers, more debug messages are generated, and
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor server performance will be degraded. The actual meanings of
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor 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
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <module>mod_charset_lite</module> should implicitly insert its
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor filter when the configuration specifies that the character
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor set of content should be translated. If the filter chain is
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor explicitly configured using the <directive module="mod_mime"
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor >AddOutputFilter</directive> directive, <code>NoImplicitAdd</code>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor should be specified so that <module>mod_charset_lite</module>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor doesn't add its filter.</dd>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <dt><code>TranslateAllMimeTypes | NoTranslateAllMimeTypes</code></dt>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <dd>Normally, <module>mod_charset_lite</module> will only perform
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor translation on a small subset of possible mimetypes. When the
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor <code>TranslateAllMimeTypes</code> keyword is specified for a given
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor configuration section, translation is performed without regard for
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor mimetype.</dd>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor</directivesynopsis>
3e6b8c7840a46cdccd46b7a4b1902c2bc82f6cc2gryzor</modulesynopsis>