mod_charset_lite.xml revision 1d9308ed0075062953a246d16bcda888a1be1ade
530eba85dbd41b8a0fa5255d3648d1440199a661slive<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
e942c741056732f50da2074b36fe59805d370650slive<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
5f5d1b4cc970b7f06ff8ef6526128e9a27303d88nd<!-- $LastChangedRevision$ -->
08cb74ca432a8c24e39f17dedce527e6a47b8001jerenkrantz Copyright 2002-2005 The Apache Software Foundation or its licensors, as
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd Licensed under the Apache License, Version 2.0 (the "License");
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd you may not use this file except in compliance with the License.
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd You may obtain a copy of the License at
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd Unless required by applicable law or agreed to in writing, software
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd distributed under the License is distributed on an "AS IS" BASIS,
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd See the License for the specific language governing permissions and
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd limitations under the License.
c1ce37b2dcce132ff0abf6a15f5225a0e89af5e4slive<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
cee399b097f61ab31c81399957f1293b55e1a984nd <module>mod_charset_lite</module> 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
cee399b097f61ab31c81399957f1293b55e1a984nd 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
cee399b097f61ab31c81399957f1293b55e1a984nd module="mod_charset_lite">CharsetSourceEnc</directive> and
cee399b097f61ab31c81399957f1293b55e1a984nd <directive module="mod_charset_lite">CharsetDefault</directive>
1d9308ed0075062953a246d16bcda888a1be1adeslive must be acceptable to the translation mechanism used by
1d9308ed0075062953a246d16bcda888a1be1adeslive <module>mod_charset_lite</module> is deployed. These character
1d9308ed0075062953a246d16bcda888a1be1adeslive set names are not standardized and are usually not the same as
1d9308ed0075062953a246d16bcda888a1be1adeslive the corresponding values used in http headers. Currently, APR
1d9308ed0075062953a246d16bcda888a1be1adeslive can only use iconv(3), so you can easily test your character set
1d9308ed0075062953a246d16bcda888a1be1adeslive names using the iconv(1) program, as follows:</p>
cee399b097f61ab31c81399957f1293b55e1a984nd iconv -f charsetsourceenc-value -t charsetdefault-value
cee399b097f61ab31c81399957f1293b55e1a984nd </example>
cee399b097f61ab31c81399957f1293b55e1a984nd </section>
cee399b097f61ab31c81399957f1293b55e1a984nd <section><title>Mismatch between character set of content and translation
6b040c2a2a566388097aab66dff8c3c94e853f22slive rules</title>
cee399b097f61ab31c81399957f1293b55e1a984nd <p>If the translation rules don't make sense for the content,
cee399b097f61ab31c81399957f1293b55e1a984nd 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>
cee399b097f61ab31c81399957f1293b55e1a984nd </section>
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>
cee399b097f61ab31c81399957f1293b55e1a984nd <p>The value of the <var>charset</var> argument must be accepted
6b040c2a2a566388097aab66dff8c3c94e853f22slive as a valid character set name by the character set support in
1d9308ed0075062953a246d16bcda888a1be1adeslive <glossary>APR</glossary>. Generally, this means that it must be
1d9308ed0075062953a246d16bcda888a1be1adeslive supported by iconv.</p>
cee399b097f61ab31c81399957f1293b55e1a984nd <Directory /export/home/trawick/apacheinst/htdocs/convert><br />
cee399b097f61ab31c81399957f1293b55e1a984nd CharsetSourceEnc UTF-16BE<br />
cee399b097f61ab31c81399957f1293b55e1a984nd CharsetDefault ISO-8859-1<br />
cee399b097f61ab31c81399957f1293b55e1a984nd </Directory>
cee399b097f61ab31c81399957f1293b55e1a984nd </example>
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>
cee399b097f61ab31c81399957f1293b55e1a984nd <p>The value of the <var>charset</var> argument must be accepted
6b040c2a2a566388097aab66dff8c3c94e853f22slive as a valid character set name by the character set support in
1d9308ed0075062953a246d16bcda888a1be1adeslive <glossary>APR</glossary>. Generally, this means that it must be
1d9308ed0075062953a246d16bcda888a1be1adeslive supported by iconv.</p>
cee399b097f61ab31c81399957f1293b55e1a984nd <Directory /export/home/trawick/apacheinst/htdocs/convert><br />
cee399b097f61ab31c81399957f1293b55e1a984nd CharsetSourceEnc UTF-16BE<br />
cee399b097f61ab31c81399957f1293b55e1a984nd CharsetDefault ISO-8859-1<br />
cee399b097f61ab31c81399957f1293b55e1a984nd </Directory>
cee399b097f61ab31c81399957f1293b55e1a984nd </example>
6b040c2a2a566388097aab66dff8c3c94e853f22slive</directivesynopsis>
6b040c2a2a566388097aab66dff8c3c94e853f22slive<directivesynopsis>
cee399b097f61ab31c81399957f1293b55e1a984nd<description>Configures charset translation behavior</description>
cee399b097f61ab31c81399957f1293b55e1a984nd<syntax>CharsetOptions <var>option</var> [<var>option</var>] ...</syntax>
cee399b097f61ab31c81399957f1293b55e1a984nd<default>CharsetOptions DebugLevel=0 NoImplicitAdd</default>
6b040c2a2a566388097aab66dff8c3c94e853f22slive<context>virtual host</context><context>directory</context>
6b040c2a2a566388097aab66dff8c3c94e853f22slive</contextlist>
6b040c2a2a566388097aab66dff8c3c94e853f22slive <p>The <directive>CharsetOptions</directive> directive configures certain
cee399b097f61ab31c81399957f1293b55e1a984nd behaviors of <module>mod_charset_lite</module>. <var>Option</var> 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
cee399b097f61ab31c81399957f1293b55e1a984nd explicitly configured using the <directive module="mod_mime"
cee399b097f61ab31c81399957f1293b55e1a984nd >AddOutputFilter</directive> directive, <code>NoImplicitAdd</code>
cee399b097f61ab31c81399957f1293b55e1a984nd should be specified so that <module>mod_charset_lite</module>
cee399b097f61ab31c81399957f1293b55e1a984nd doesn't add its filter.</dd>
6b040c2a2a566388097aab66dff8c3c94e853f22slive</directivesynopsis>
7db9f691a00ead175b03335457ca296a33ddf31bnd</modulesynopsis>