granicus.if.org Git - apache/blob - docs/manual/mod/mod_xml2enc.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
   4 <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
   5 <!--
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7               This file is generated from xml source: DO NOT EDIT
   8         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   9       -->
  10 <title>mod_xml2enc - Apache HTTP Server Version 2.5</title>
  11 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  12 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  13 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
  14 <script src="../style/scripts/prettify.min.js" type="text/javascript">
  15 </script>
  16
  17 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  18 <body>
  19 <div id="page-header">
  20 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  21 <p class="apache">Apache HTTP Server Version 2.5</p>
  22 <img alt="" src="../images/feather.png" /></div>
  23 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  24 <div id="path">
  25 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Modules</a></div>
  26 <div id="page-content">
  27 <div id="preamble"><h1>Apache Module mod_xml2enc</h1>
  28 <div class="toplang">
  29 <p><span>Available Languages: </span><a href="../en/mod/mod_xml2enc.html" title="English">&nbsp;en&nbsp;</a></p>
  30 </div>
  31 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Enhanced charset/internationalisation support for libxml2-based
  32 filter modules</td></tr>
  33 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Base</td></tr>
  34 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>xml2enc_module</td></tr>
  35 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_xml2enc.c</td></tr>
  36 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Version 2.4 and later.  Available as a third-party module
  37 for 2.2.x versions</td></tr></table>
  38 <h3>Summary</h3>
  39
  40     <p>This module provides enhanced internationalisation support for
  41     markup-aware filter modules such as <code class="module"><a href="../mod/mod_proxy_html.html">mod_proxy_html</a></code>.
  42     It can automatically detect the encoding of input data and ensure
  43     they are correctly processed by the <a href="http://xmlsoft.org/">libxml2</a> parser, including converting to Unicode (UTF-8) where
  44     necessary.  It can also convert data to an encoding of choice
  45     after markup processing, and will ensure the correct <var>charset</var>
  46     value is set in the HTTP <var>Content-Type</var> header.</p>
  47 </div>
  48 <div id="quickview"><h3>Topics</h3>
  49 <ul id="topics">
  50 <li><img alt="" src="../images/down.gif" /> <a href="#usage">Usage</a></li>
  51 <li><img alt="" src="../images/down.gif" /> <a href="#api">Programming API</a></li>
  52 <li><img alt="" src="../images/down.gif" /> <a href="#sniffing">Detecting an Encoding</a></li>
  53 <li><img alt="" src="../images/down.gif" /> <a href="#output">Output Encoding</a></li>
  54 <li><img alt="" src="../images/down.gif" /> <a href="#alias">Unsupported Encodings</a></li>
  55 </ul><h3 class="directives">Directives</h3>
  56 <ul id="toc">
  57 <li><img alt="" src="../images/down.gif" /> <a href="#xml2encalias">xml2EncAlias</a></li>
  58 <li><img alt="" src="../images/down.gif" /> <a href="#xml2encdefault">xml2EncDefault</a></li>
  59 <li><img alt="" src="../images/down.gif" /> <a href="#xml2startparse">xml2StartParse</a></li>
  60 </ul>
  61 <h3>Bugfix checklist</h3><ul class="seealso"><li><a href="https://www.apache.org/dist/httpd/CHANGES_2.4">httpd changelog</a></li><li><a href="https://bz.apache.org/bugzilla/buglist.cgi?bug_status=__open__&amp;list_id=144532&amp;product=Apache%20httpd-2&amp;query_format=specific&amp;order=changeddate%20DESC%2Cpriority%2Cbug_severity&amp;component=mod_xml2enc">Known issues</a></li><li><a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&amp;component=mod_xml2enc">Report a bug</a></li></ul><h3>See also</h3>
  62 <ul class="seealso">
  63 <li><a href="#comments_section">Comments</a></li></ul></div>
  64 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  65 <div class="section">
  66 <h2><a name="usage" id="usage">Usage</a></h2>
  67     <p>There are two usage scenarios: with modules programmed to work
  68     with mod_xml2enc, and with those that are not aware of it:</p>
  69     <dl>
  70     <dt>Filter modules enabled for mod_xml2enc</dt><dd>
  71     <p>Modules such as <code class="module"><a href="../mod/mod_proxy_html.html">mod_proxy_html</a></code> version 3.1
  72     and up use the <code>xml2enc_charset</code> optional function to retrieve
  73     the charset argument to pass to the libxml2 parser, and may use the
  74     <code>xml2enc_filter</code> optional function to postprocess to another
  75     encoding.  Using mod_xml2enc with an enabled module, no configuration
  76     is necessary: the other module will configure mod_xml2enc for you
  77     (though you may still want to customise it using the configuration
  78     directives below).</p>
  79     </dd>
  80     <dt>Non-enabled modules</dt><dd>
  81     <p>To use it with a libxml2-based module that isn't explicitly enabled for
  82     mod_xml2enc, you will have to configure the filter chain yourself.
  83     So to use it with a filter foo provided by a module mod_foo to
  84     improve the latter's i18n support with HTML and XML, you could use</p>
  85     <pre><code>
  86     FilterProvider iconv    xml2enc Content-Type $text/html
  87     FilterProvider iconv    xml2enc Content-Type $xml
  88     FilterProvider markup   foo Content-Type $text/html
  89     FilterProvider markup   foo Content-Type $xml
  90     FilterChain     iconv markup
  91     </code></pre>
  92     <p>mod_foo will now support any character set supported by either
  93     (or both) of libxml2 or apr_xlate/iconv.</p>
  94     </dd></dl>
  95 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  96 <div class="section">
  97 <h2><a name="api" id="api">Programming API</a></h2>
  98     <p>Programmers writing libxml2-based filter modules are encouraged to
  99     enable them for mod_xml2enc, to provide strong i18n support for your
 100     users without reinventing the wheel.  The programming API is exposed in
 101     <var>mod_xml2enc.h</var>, and a usage example is
 102     <code class="module"><a href="../mod/mod_proxy_html.html">mod_proxy_html</a></code>.</p>
 103 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 104 <div class="section">
 105 <h2><a name="sniffing" id="sniffing">Detecting an Encoding</a></h2>
 106     <p>Unlike <code class="module"><a href="../mod/mod_charset_lite.html">mod_charset_lite</a></code>, mod_xml2enc is designed
 107     to work with data whose encoding cannot be known in advance and thus
 108     configured.  It therefore uses 'sniffing' techniques to detect the
 109     encoding of HTTP data as follows:</p>
 110     <ol>
 111         <li>If the HTTP <var>Content-Type</var> header includes a
 112         <var>charset</var> parameter, that is used.</li>
 113         <li>If the data start with an XML Byte Order Mark (BOM) or an
 114         XML encoding declaration, that is used.</li>
 115         <li>If an encoding is declared in an HTML <code>&lt;META&gt;</code>
 116         element, that is used.</li>
 117         <li>If none of the above match, the default value set by
 118         <code class="directive">xml2EncDefault</code> is used.</li>
 119     </ol>
 120     <p>The rules are applied in order.  As soon as a match is found,
 121     it is used and detection is stopped.</p>
 122 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 123 <div class="section">
 124 <h2><a name="output" id="output">Output Encoding</a></h2>
 125 <p><a href="http://xmlsoft.org/">libxml2</a> always uses UTF-8 (Unicode)
 126 internally, and libxml2-based filter modules will output that by default.
 127 mod_xml2enc can change the output encoding through the API, but there
 128 is currently no way to configure that directly.</p>
 129 <p>Changing the output encoding should (in theory, at least) never be
 130 necessary, and is not recommended due to the extra processing load on
 131 the server of an unnecessary conversion.</p>
 132 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 133 <div class="section">
 134 <h2><a name="alias" id="alias">Unsupported Encodings</a></h2>
 135 <p>If you are working with encodings that are not supported by any of
 136 the conversion methods available on your platform, you can still alias
 137 them to a supported encoding using <code class="directive">xml2EncAlias</code>.</p>
 138 </div>
 139 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 140 <div class="directive-section"><h2><a name="xml2EncAlias" id="xml2EncAlias">xml2EncAlias</a> <a name="xml2encalias" id="xml2encalias">Directive</a></h2>
 141 <table class="directive">
 142 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Recognise Aliases for encoding values</td></tr>
 143 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>xml2EncAlias <var>charset alias [alias ...]</var></code></td></tr>
 144 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
 145 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 146 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_xml2enc</td></tr>
 147 </table>
 148     <p>This server-wide directive aliases one or more encoding to another
 149     encoding.  This enables encodings not recognised by libxml2 to be handled
 150     internally by libxml2's encoding support using the translation table for
 151     a recognised encoding.  This serves two purposes: to support character sets
 152     (or names) not recognised either by libxml2 or iconv, and to skip
 153     conversion for an encoding where it is known to be unnecessary.</p>
 154
 155 </div>
 156 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 157 <div class="directive-section"><h2><a name="xml2EncDefault" id="xml2EncDefault">xml2EncDefault</a> <a name="xml2encdefault" id="xml2encdefault">Directive</a></h2>
 158 <table class="directive">
 159 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets a default encoding to assume when absolutely no information
 160 can be <a href="#sniffing">automatically detected</a></td></tr>
 161 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>xml2EncDefault <var>name</var></code></td></tr>
 162 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 163 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 164 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_xml2enc</td></tr>
 165 <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Version 2.4.0 and later; available as a third-party
 166 module for earlier versions.</td></tr>
 167 </table>
 168     <p>If you are processing data with known encoding but no encoding
 169     information, you can set this default to help mod_xml2enc process
 170     the data correctly.  For example, to work with the default value
 171     of Latin1 (<var>iso-8859-1</var> specified in HTTP/1.0, use</p>
 172     <pre class="prettyprint lang-config">xml2EncDefault iso-8859-1</pre>
 173
 174
 175 </div>
 176 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 177 <div class="directive-section"><h2><a name="xml2StartParse" id="xml2StartParse">xml2StartParse</a> <a name="xml2startparse" id="xml2startparse">Directive</a></h2>
 178 <table class="directive">
 179 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Advise the parser to skip leading junk.</td></tr>
 180 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>xml2StartParse <var>element [element ...]</var></code></td></tr>
 181 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 182 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>
 183 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_xml2enc</td></tr>
 184 </table>
 185     <p>Specify that the markup parser should start at the first instance
 186     of any of the elements specified.  This can be used as a workaround
 187     where a broken backend inserts leading junk that messes up the parser (<a href="http://bahumbug.wordpress.com/2006/10/12/mod_proxy_html-revisited/">example here</a>).</p>
 188     <p>It should never be used for XML, nor well-formed HTML.</p>
 189
 190 </div>
 191 </div>
 192 <div class="bottomlang">
 193 <p><span>Available Languages: </span><a href="../en/mod/mod_xml2enc.html" title="English">&nbsp;en&nbsp;</a></p>
 194 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&amp;A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
 195 <script type="text/javascript"><!--//--><![CDATA[//><!--
 196 var comments_shortname = 'httpd';
 197 var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_xml2enc.html';
 198 (function(w, d) {
 199     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 200         d.write('<div id="comments_thread"><\/div>');
 201         var s = d.createElement('script');
 202         s.type = 'text/javascript';
 203         s.async = true;
 204         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
 205         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 206     }
 207     else {
 208         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
 209     }
 210 })(window, document);
 211 //--><!]]></script></div><div id="footer">
 212 <p class="apache">Copyright 2016 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 213 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
 214 if (typeof(prettyPrint) !== 'undefined') {
 215     prettyPrint();
 216 }
 217 //--><!]]></script>
 218 </body></html>