granicus.if.org Git - apache/blob - docs/manual/mod/mod_charset_lite.xml

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