mod_charset_lite.html revision dff77f20d3ca0296e740d4369989e57949a06e92
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<HTML>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <HEAD>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <TITLE>Apache module mod_charset_lite</TITLE>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster </HEAD>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <BODY
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster BGCOLOR="#FFFFFF"
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster TEXT="#000000"
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster LINK="#0000FF"
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster VLINK="#000080"
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster ALINK="#FF0000"
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster >
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<!--#include virtual="header.html" -->
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <H1 ALIGN="CENTER">Module mod_charset_lite</H1>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<p>This module provides the ability to specify character set
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster translation or recoding.</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<P><A
8af80418ba1ec431c8027fa9668e5678658d3611Allan FosterHREF="module-dict.html#Status"
8af80418ba1ec431c8027fa9668e5678658d3611Allan FosterREL="Help"
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster><STRONG>Status:</STRONG></A> Experimental
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<BR>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<A
8af80418ba1ec431c8027fa9668e5678658d3611Allan FosterHREF="module-dict.html#SourceFile"
8af80418ba1ec431c8027fa9668e5678658d3611Allan FosterREL="Help"
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster><STRONG>Source File:</STRONG></A> mod_charset_lite.c
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<BR>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster<A
8af80418ba1ec431c8027fa9668e5678658d3611Allan FosterHREF="module-dict.html#ModuleIdentifier"
8af80418ba1ec431c8027fa9668e5678658d3611Allan FosterREL="Help"
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster><STRONG>Module Identifier:</STRONG></A> charset_lite_module
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster</P>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <H2>Summary</H2>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <P>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster This is an <STRONG>experimental</STRONG> module and should be used with
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster care. Experiment with your <CODE>mod_charset_lite</CODE> configuration to
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster ensure that it performs the desired function.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster </P>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <P>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <CODE>mod_charset_lite</CODE> allows the administrator to specify the
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster source character set of objects as well as the character set they should
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster be translated into before sending to the client.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <CODE>mod_charset_lite</CODE> does not translate the data itself but
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster instead tells Apache what translation to perform.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <CODE>mod_charset_lite</CODE> is applicable to EBCDIC and ASCII
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster host environments. In an EBCDIC environment, Apache normally translates
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster text content from the code page of the Apache process locale to
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster ISO-8859-1. <CODE>mod_charset_lite</CODE> can be used to specify that
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster a different translation is to be performed. In an ASCII environment,
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster Apache normally performs no translation, so <CODE>mod_charset_lite</CODE>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster is needed in order for any translation to take place.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster </P>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <p>This module will only work if <code>APACHE_XLATE</code> is defined
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster at compile time.</p>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <P>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster This module provides a small subset of configuration mechanisms
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster implemented by Russian Apache and its associated <CODE>mod_charset</CODE>.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster </P>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <H2>Directives</H2>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <UL>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <LI><A HREF="#charsetsourceenc">CharsetSourceEnc</A>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <LI><A HREF="#charsetdefault">CharsetDefault</A>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster <LI><A HREF="#charsetoptions">CharsetOptions</A>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster </LI>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster </UL>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster
<H2>Common Problems</H2>
<H3>Invalid character set names</H3>
<P>
The character set name parameters of CharsetSourceEnc and CharsetDefault
must be acceptable to the translation mechanism used by APR on the system
where mod_charset_lite is deployed. These character set names are not
standardized and are usually not the same as the corresponding values used
in http headers. Currently, APR can only use iconv(3), so you can easily
test your character set names using the iconv(1) program, as follows:
</P>
<PRE>
iconv -f charsetsourceenc-value -t charsetdefault-value
</PRE>
<H3>Mismatch between character set of content and translation rules</H3>
<P>
If the translation rules don't make sense for the content, translation
can fail in various ways, including:
</P>
<UL>
<LI>
The translation mechanism may return a bad return code, and the connection
will be aborted.
<LI>
The translation mechanism may silently place special characters (e.g., question
marks) in the output buffer when it cannot translate the input buffer.
</UL>
<HR>
<H2><A NAME="charsetsourceenc">CharsetSourceEnc</A></H2>
<P>
<A
HREF="directive-dict.html#Syntax"
REL="Help"
><STRONG>Syntax:</STRONG></A> CharsetSourceEnc <EM>charset</EM>
<BR>
<A
HREF="directive-dict.html#Default"
REL="Help"
><STRONG>Default:</STRONG></A> <EM>None</EM>
<BR>
<A
HREF="directive-dict.html#Context"
REL="Help"
><STRONG>Context:</STRONG></A> directory, virtual host
<BR>
<A
HREF="directive-dict.html#Override"
REL="Help"
><STRONG>Override:</STRONG></A> <EM>FileInfo</EM>
<BR>
<A
HREF="directive-dict.html#Status"
REL="Help"
><STRONG>Status:</STRONG></A> Experimental
<BR>
<A
HREF="directive-dict.html#Module"
REL="Help"
><STRONG>Module:</STRONG></A> mod_charset_lite
<BR>
<P>
The <CODE>CharsetSourceEnc</CODE> directive specifies the source charset
of files in the associated container.
</P>
<P>
The value of the <EM>charset</EM> argument must be accepted as a valid
character set name by the character set support in APR. Generally, this
means that it must be supported by iconv.
</P>
Example:
<PRE>
&lt;Directory "/export/home/trawick/apacheinst/htdocs/convert"&gt;
CharsetSourceEnc UTF-16BE
CharsetDefault ISO8859-1
&lt;/Directory&gt;
</PRE>
The character set names in this example work with the iconv
translation support in Solaris 8.
<P>
<hr>
<H2><A NAME="charsetdefault">CharsetDefault</A></H2>
<P>
<A
HREF="directive-dict.html#Syntax"
REL="Help"
><STRONG>Syntax:</STRONG></A> CharsetDefault <EM>charset</EM>
<BR>
<A
HREF="directive-dict.html#Default"
REL="Help"
><STRONG>Default:</STRONG></A> <EM>None</EM>
<BR>
<A
HREF="directive-dict.html#Context"
REL="Help"
><STRONG>Context:</STRONG></A> directory, virtual host
<BR>
<A
HREF="directive-dict.html#Override"
REL="Help"
><STRONG>Override:</STRONG></A> <EM>FileInfo</EM>
<BR>
<A
HREF="directive-dict.html#Status"
REL="Help"
><STRONG>Status:</STRONG></A> Experimental
<BR>
<A
HREF="directive-dict.html#Module"
REL="Help"
><STRONG>Module:</STRONG></A> mod_charset_lite
<BR>
<P>
The <CODE>CharsetDefault</CODE> directive specifies the charset that
content in the associated container should be translated to.
</P>
<P>
The value of the <EM>charset</EM> argument must be accepted as a valid
character set name by the character set support in APR. Generally, this
means that it must be supported by iconv.
</P>
Example:
<PRE>
&lt;Directory "/export/home/trawick/apacheinst/htdocs/convert"&gt;
CharsetSourceEnc UTF-16BE
CharsetDefault ISO8859-1
&lt;/Directory&gt;
</PRE>
<P>
<hr>
<H2><A NAME="charsetoptions">CharsetOptions</A></H2>
<P>
<A
HREF="directive-dict.html#Syntax"
REL="Help"
><STRONG>Syntax:</STRONG></A> CharsetOptions <EM>option</em>
[<em>option</em>] ...
<BR>
<A
HREF="directive-dict.html#Default"
REL="Help"
><STRONG>Default:</STRONG></A> <EM>DebugLevel=0</EM> <EM>NoImplicitAdd</EM>
<BR>
<A
HREF="directive-dict.html#Context"
REL="Help"
><STRONG>Context:</STRONG></A> directory, virtual host
<BR>
<A
HREF="directive-dict.html#Override"
REL="Help"
><STRONG>Override:</STRONG></A> <EM>FileInfo</EM>
<BR>
<A
HREF="directive-dict.html#Status"
REL="Help"
><STRONG>Status:</STRONG></A> Experimental
<BR>
<A
HREF="directive-dict.html#Module"
REL="Help"
><STRONG>Module:</STRONG></A> mod_charset_lite
<BR>
<P>
The <CODE>CharsetOptions</CODE> directive configures certain behaviors
of <CODE>mod_charset_lite</CODE>. <EM>Option</EM> can be one of
<DL>
<DT>DebugLevel=<EM>n</EM>
<DD>
The <SAMP>DebugLevel</SAMP> keyword allows you to specify the level of
debug messages generated by <CODE>mod_charset_lite</CODE>. By default, no
messages are generated. This is equivalent to <SAMP>DebugLevel=0</SAMP>.
With higher numbers, more debug messages are generated, and server
performance will be degraded. The actual meanings of the numeric values
are described with the definitions of the DBGLVL_ constants near the
beginning of <CODE>mod_charset_lite.c</CODE>.
<DT>ImplicitAdd | NoImplicitAdd
<DD>
The <SAMP>ImplicitAdd</SAMP> keyword specifies that
<CODE>mod_charset_lite</CODE> should implicitly insert its filter when
the configuration specifies that the character set of content should be
translated. If the filter chain is explicitly configured using the
AddOutputFilter directive, <SAMP>NoImplicitAdd</SAMP> should be specified so
that <CODE>mod_charset_lite</CODE> doesn't add its filter.
</DL>
</P>
<!--#include virtual="footer.html" -->
</BODY>
</HTML>