home *** CD-ROM | disk | FTP | other *** search
/ Chip 2004 November / CMCD1104.ISO / Software / Complet / Apache / apache_2.0.52-win32-x86-no_ssl.msi / Data.Cab / F278263_mod_charset_lite.xml < prev    next >
Extensible Markup Language  |  2004-04-17  |  8KB  |  199 lines
  1. <?xml version="1.0"?>
  2. <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
  3. <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
  4. <!-- $Revision: 1.6.2.4 $ -->
  5.  
  6. <!--
  7.  Copyright 2002-2004 The Apache Software Foundation
  8.  
  9.  Licensed under the Apache License, Version 2.0 (the "License");
  10.  you may not use this file except in compliance with the License.
  11.  You may obtain a copy of the License at
  12.  
  13.      http://www.apache.org/licenses/LICENSE-2.0
  14.  
  15.  Unless required by applicable law or agreed to in writing, software
  16.  distributed under the License is distributed on an "AS IS" BASIS,
  17.  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18.  See the License for the specific language governing permissions and
  19.  limitations under the License.
  20. -->
  21.  
  22. <modulesynopsis metafile="mod_charset_lite.xml.meta">
  23.  
  24. <name>mod_charset_lite</name>
  25. <description>Specify character set translation or recoding</description>
  26. <status>Experimental</status>
  27. <sourcefile>mod_charset_lite.c</sourcefile>
  28. <identifier>charset_lite_module</identifier>
  29.  
  30. <summary>
  31.     <p>This is an <strong>experimental</strong> module and should
  32.     be used with care. Experiment with your
  33.     <module>mod_charset_lite</module> configuration to ensure that it
  34.     performs the desired function.</p>
  35.  
  36.     <p><module>mod_charset_lite</module> allows the administrator to
  37.     specify the source character set of objects as well as the
  38.     character set they should be translated into before sending to the
  39.     client. <module>mod_charset_lite</module> does not translate the
  40.     data itself but instead tells Apache what translation to
  41.     perform. <module>mod_charset_lite</module> is applicable to EBCDIC
  42.     and ASCII host environments. In an EBCDIC environment, Apache
  43.     normally translates text content from the code page of the Apache
  44.     process locale to ISO-8859-1. <module>mod_charset_lite</module>
  45.     can be used to specify that a different translation is to be
  46.     performed. In an ASCII environment, Apache normally performs no
  47.     translation, so <module>mod_charset_lite</module> is needed in
  48.     order for any translation to take place.</p>
  49.  
  50.     <p>This module provides a small subset of configuration
  51.     mechanisms implemented by Russian Apache and its associated
  52.     <code>mod_charset</code>.</p>
  53. </summary>
  54.  
  55. <section id="problems"><title>Common Problems</title>
  56.  
  57.     <section><title>Invalid character set names</title>
  58.  
  59.       <p>The character set name parameters of <directive
  60.       module="mod_charset_lite">CharsetSourceEnc</directive> and
  61.       <directive module="mod_charset_lite">CharsetDefault</directive>
  62.       must be acceptable to the translation mechanism used by APR on the
  63.       system where <module>mod_charset_lite</module> is deployed.  These
  64.       character set names are not standardized and are usually not the
  65.       same as the corresponding values used in http headers.  Currently,
  66.       APR can only use iconv(3), so you can easily test your character
  67.       set names using the iconv(1) program, as follows:</p>
  68.  
  69.       <example>
  70.         iconv -f charsetsourceenc-value -t charsetdefault-value
  71.       </example>
  72.     </section>
  73.  
  74.     <section><title>Mismatch between character set of content and translation
  75.     rules</title>
  76.  
  77.       <p>If the translation rules don't make sense for the content,
  78.       translation can fail in various ways, including:</p>
  79.  
  80.       <ul>
  81.       <li>The translation mechanism may return a bad return code,
  82.       and the connection will be aborted.</li>
  83.  
  84.       <li>The translation mechanism may silently place special
  85.       characters (e.g., question marks) in the output buffer when
  86.       it cannot translate the input buffer.</li>
  87.       </ul>
  88.     </section>
  89. </section>
  90.  
  91. <directivesynopsis>
  92. <name>CharsetSourceEnc</name>
  93. <description>Source charset of files</description>
  94. <syntax>CharsetSourceEnc <var>charset</var></syntax>
  95. <contextlist><context>server config</context>
  96. <context>virtual host</context><context>directory</context>
  97. <context>.htaccess</context>
  98. </contextlist>
  99. <override>FileInfo</override>
  100.  
  101. <usage>
  102.     <p>The <directive>CharsetSourceEnc</directive> directive specifies the
  103.     source charset of files in the associated container.</p>
  104.  
  105.     <p>The value of the <var>charset</var> argument must be accepted
  106.     as a valid character set name by the character set support in
  107.     APR. Generally, this means that it must be supported by
  108.     iconv.</p>
  109.     
  110.     <example><title>Example</title>
  111.       <Directory /export/home/trawick/apacheinst/htdocs/convert><br />
  112.       <indent>
  113.         CharsetSourceEnc  UTF-16BE<br />
  114.         CharsetDefault    ISO-8859-1<br />
  115.       </indent>
  116.       </Directory>
  117.     </example>
  118.  
  119.     <p>The character set names in this example work with the iconv
  120.     translation support in Solaris 8.</p>
  121. </usage>
  122. </directivesynopsis>
  123.  
  124. <directivesynopsis>
  125. <name>CharsetDefault</name>
  126. <description>Charset to translate into</description>
  127. <syntax>CharsetDefault <var>charset</var></syntax>
  128. <contextlist><context>server config</context>
  129. <context>virtual host</context><context>directory</context>
  130. <context>.htaccess</context>
  131. </contextlist>
  132. <override>FileInfo</override>
  133.  
  134. <usage>
  135.     <p>The <directive>CharsetDefault</directive> directive specifies the
  136.     charset that content in the associated container should be
  137.     translated to.</p>
  138.  
  139.     <p>The value of the <var>charset</var> argument must be accepted
  140.     as a valid character set name by the character set support in
  141.     APR. Generally, this means that it must be supported by
  142.     iconv.</p>
  143.  
  144.     <example><title>Example</title>
  145.       <Directory /export/home/trawick/apacheinst/htdocs/convert><br />
  146.       <indent>
  147.         CharsetSourceEnc  UTF-16BE<br />
  148.         CharsetDefault    ISO-8859-1<br />
  149.       </indent>
  150.       </Directory>
  151.     </example>
  152. </usage>
  153. </directivesynopsis>
  154.  
  155. <directivesynopsis>
  156. <name>CharsetOptions</name>
  157. <description>Configures charset translation behavior</description>
  158. <syntax>CharsetOptions <var>option</var> [<var>option</var>] ...</syntax>
  159. <default>CharsetOptions DebugLevel=0 NoImplicitAdd</default>
  160. <contextlist><context>server config</context>
  161. <context>virtual host</context><context>directory</context>
  162. <context>.htaccess</context>
  163. </contextlist>
  164. <override>FileInfo</override>
  165.  
  166. <usage>
  167.     <p>The <directive>CharsetOptions</directive> directive configures certain
  168.     behaviors of <module>mod_charset_lite</module>. <var>Option</var> can
  169.     be one of</p>
  170.  
  171.     <dl>
  172.       <dt><code>DebugLevel=<var>n</var></code></dt>
  173.  
  174.       <dd>The <code>DebugLevel</code> keyword allows you to specify
  175.       the level of debug messages generated by
  176.       <module>mod_charset_lite</module>. By default, no messages are
  177.       generated. This is equivalent to <code>DebugLevel=0</code>.
  178.       With higher numbers, more debug messages are generated, and
  179.       server performance will be degraded. The actual meanings of
  180.       the numeric values are described with the definitions of the
  181.       DBGLVL_ constants near the beginning of
  182.       <code>mod_charset_lite.c</code>.</dd>
  183.  
  184.       <dt><code>ImplicitAdd | NoImplicitAdd</code></dt>
  185.  
  186.       <dd>The <code>ImplicitAdd</code> keyword specifies that
  187.       <module>mod_charset_lite</module> should implicitly insert its
  188.       filter when the configuration specifies that the character
  189.       set of content should be translated. If the filter chain is
  190.       explicitly configured using the <directive module="mod_mime"
  191.       >AddOutputFilter</directive> directive, <code>NoImplicitAdd</code>
  192.       should be specified so that <module>mod_charset_lite</module>
  193.       doesn't add its filter.</dd>
  194.     </dl>
  195. </usage>
  196. </directivesynopsis>
  197.  
  198. </modulesynopsis>
  199.