granicus.if.org Git - apache/blob - docs/manual/mod/mod_xml2enc.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 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_xml2enc.xml.meta">
  24
  25 <name>mod_xml2enc</name>
  26 <description>Enhanced charset/internationalisation support for libxml2-based
  27 filter modules</description>
  28 <status>Base</status>
  29 <sourcefile>mod_xml2enc.c</sourcefile>
  30 <identifier>xml2enc_module</identifier>
  31 <compatibility>Version 2.4 and later.  Available as a third-party module
  32 for 2.2.x versions</compatibility>
  33
  34 <summary>
  35     <p>This module provides enhanced internationalisation support for
  36     markup-aware filter modules such as <module>mod_proxy_html</module>.
  37     It can automatically detect the encoding of input data and ensure
  38     they are correctly processed by the <a href="http://xmlsoft.org/"
  39     >libxml2</a> parser, including converting to Unicode (UTF-8) where
  40     necessary.  It can also convert data to an encoding of choice
  41     after markup processing, and will ensure the correct <var>charset</var>
  42     value is set in the HTTP <var>Content-Type</var> header.</p>
  43 </summary>
  44
  45 <section id="usage"><title>Usage</title>
  46     <p>There are two usage scenarios: with modules programmed to work
  47     with mod_xml2enc, and with those that are not aware of it:</p>
  48     <dl>
  49     <dt>Filter modules enabled for mod_xml2enc</dt><dd>
  50     <p>Modules such as <module>mod_proxy_html</module> version 3.1
  51     and up use the <code>xml2enc_charset</code> optional function to retrieve
  52     the charset argument to pass to the libxml2 parser, and may use the
  53     <code>xml2enc_filter</code> optional function to postprocess to another
  54     encoding.  Using mod_xml2enc with an enabled module, no configuration
  55     is necessary: the other module will configure mod_xml2enc for you
  56     (though you may still want to customise it using the configuration
  57     directives below).</p>
  58     </dd>
  59     <dt>Non-enabled modules</dt><dd>
  60     <p>To use it with a libxml2-based module that isn't explicitly enabled for
  61     mod_xml2enc, you will have to configure the filter chain yourself.
  62     So to use it with a filter foo provided by a module mod_foo to
  63     improve the latter's i18n support with HTML and XML, you could use</p>
  64     <pre><code>
  65     FilterProvider iconv    xml2enc Content-Type $text/html
  66     FilterProvider iconv    xml2enc Content-Type $xml
  67     FilterProvider markup   foo Content-Type $text/html
  68     FilterProvider markup   foo Content-Type $xml
  69     FilterChain     iconv markup
  70     </code></pre>
  71     <p>mod_foo will now support any character set supported by either
  72     (or both) of libxml2 or apr_xlate/iconv.</p>
  73     </dd></dl>
  74 </section>
  75
  76 <section id="api"><title>Programming API</title>
  77     <p>Programmers writing libxml2-based filter modules are encouraged to
  78     enable them for mod_xml2enc, to provide strong i18n support for your
  79     users without reinventing the wheel.  The programming API is exposed in
  80     <var>mod_xml2enc.h</var>, and a usage example is
  81     <module>mod_proxy_html</module>.</p>
  82 </section>
  83
  84 <section id="sniffing"><title>Detecting an Encoding</title>
  85     <p>Unlike <module>mod_charset_lite</module>, mod_xml2enc is designed
  86     to work with data whose encoding cannot be known in advance and thus
  87     configured.  It therefore uses 'sniffing' techniques to detect the
  88     encoding of HTTP data as follows:</p>
  89     <ol>
  90         <li>If the HTTP <var>Content-Type</var> header includes a
  91         <var>charset</var> parameter, that is used.</li>
  92         <li>If the data start with an XML Byte Order Mark (BOM) or an
  93         XML encoding declaration, that is used.</li>
  94         <li>If an encoding is declared in an HTML <code>&lt;META&gt;</code>
  95         element, that is used.</li>
  96         <li>If none of the above match, the default value set by
  97         <directive>xml2EncDefault</directive> is used.</li>
  98     </ol>
  99     <p>The rules are applied in order.  As soon as a match is found,
 100     it is used and detection is stopped.</p>
 101 </section>
 102
 103 <section id="output"><title>Output Encoding</title>
 104 <p><a href="http://xmlsoft.org/">libxml2</a> always uses UTF-8 (Unicode)
 105 internally, and libxml2-based filter modules will output that by default.
 106 mod_xml2enc can change the output encoding through the API, but there
 107 is currently no way to configure that directly.</p>
 108 <p>Changing the output encoding should (in theory, at least) never be
 109 necessary, and is not recommended due to the extra processing load on
 110 the server of an unnecessary conversion.</p>
 111 </section>
 112
 113 <section id="alias"><title>Unsupported Encodings</title>
 114 <p>If you are working with encodings that are not supported by any of
 115 the conversion methods available on your platform, you can still alias
 116 them to a supported encoding using <directive>xml2EncAlias</directive>.</p>
 117 </section>
 118
 119 <directivesynopsis>
 120 <name>xml2EncDefault</name>
 121 <description>Sets a default encoding to assume when absolutely no information
 122 can be <a href="#sniffing">automatically detected</a></description>
 123 <syntax>xml2EncDefault <var>name</var></syntax>
 124 <contextlist><context>server config</context>
 125 <context>virtual host</context><context>directory</context>
 126 <context>.htaccess</context></contextlist>
 127 <compatibility>Version 2.4.0 and later; available as a third-party
 128 module for earlier versions.</compatibility>
 129
 130 <usage>
 131     <p>If you are processing data with known encoding but no encoding
 132     information, you can set this default to help mod_xml2enc process
 133     the data correctly.  For example, to work with the default value
 134     of Latin1 (<var>iso-8859-1</var> specified in HTTP/1.0, use</p>
 135     <highlight language="config">xml2EncDefault iso-8859-1</highlight>
 136 </usage>
 137 </directivesynopsis>
 138
 139 <directivesynopsis>
 140 <name>xml2EncAlias</name>
 141 <description>Recognise Aliases for encoding values</description>
 142 <syntax>xml2EncAlias <var>charset alias [alias ...]</var></syntax>
 143 <contextlist><context>server config</context></contextlist>
 144
 145 <usage>
 146     <p>This server-wide directive aliases one or more encoding to another
 147     encoding.  This enables encodings not recognised by libxml2 to be handled
 148     internally by libxml2's encoding support using the translation table for
 149     a recognised encoding.  This serves two purposes: to support character sets
 150     (or names) not recognised either by libxml2 or iconv, and to skip
 151     conversion for an encoding where it is known to be unnecessary.</p>
 152 </usage>
 153 </directivesynopsis>
 154
 155 <directivesynopsis>
 156 <name>xml2StartParse</name>
 157 <description>Advise the parser to skip leading junk.</description>
 158 <syntax>xml2StartParse <var>element [element ...]</var></syntax>
 159 <contextlist><context>server config</context><context>virtual host</context>
 160 <context>directory</context><context>.htaccess</context></contextlist>
 161
 162 <usage>
 163     <p>Specify that the markup parser should start at the first instance
 164     of any of the elements specified.  This can be used as a workaround
 165     where a broken backend inserts leading junk that messes up the parser (<a
 166     href="http://bahumbug.wordpress.com/2006/10/12/mod_proxy_html-revisited/"
 167     >example here</a>).</p>
 168     <p>It should never be used for XML, nor well-formed HTML.</p>
 169 </usage>
 170 </directivesynopsis>
 171
 172 </modulesynopsis>
 173