Mercurial > hg > nginx-site
changeset 350:55c1c4a1748f
English translation of ngx_http_charset_module.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Tue, 24 Jan 2012 10:15:25 +0000 |
parents | 302222923e34 |
children | a4fa80755eab |
files | xml/en/GNUmakefile xml/en/docs/http/ngx_http_charset_module.xml xml/en/docs/index.xml |
diffstat | 3 files changed, 214 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/GNUmakefile +++ b/xml/en/GNUmakefile @@ -49,6 +49,7 @@ REFS = \ http/ngx_http_auth_basic_module \ http/ngx_http_autoindex_module \ http/ngx_http_browser_module \ + http/ngx_http_charset_module \ http/ngx_http_empty_gif_module \ http/ngx_http_fastcgi_module \ http/ngx_http_flv_module \
new file mode 100644 --- /dev/null +++ b/xml/en/docs/http/ngx_http_charset_module.xml @@ -0,0 +1,208 @@ +<?xml version="1.0"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_http_charset_module" + link="/en/docs/http/ngx_http_charset_module.html" + lang="en"> + +<section id="summary"> + +<para> +The <literal>ngx_http_charset_module</literal> module adds the specified +charset to the <header>Content-Type</header> response header field. +In addition, the module can convert data from one charset to another, +with some limitations: +<list type="bullet"> + +<listitem> +conversion is performed one way — from server to client, +</listitem> + +<listitem> +only single-byte charsets can be converted +</listitem> + +<listitem> +or single-byte charsets to/from UTF-8. +</listitem> + +</list> +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> + include conf/koi-win; + + charset windows-1251; + source_charset koi8-r; +</example> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="charset"> +<syntax><value>charset</value> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> +<context>if in location</context> + +<para> +Adds the specified charset to the <header>Content-Type</header> +response header field. +If this charset is different from the charset specified +in the <link id="source_charset"/> directive, a conversion is performed. +</para> + +<para> +The parameter <literal>off</literal> cancels the addition of charset +to the <header>Content-Type</header> response header field. +</para> + +<para> +A charset can be defined with a variable: +<example> +charset $charset; +</example> +In such a case, all possible values of a variable need to be present +in the configuration at least once in the form of the +<link id="charset_map"/>, <link id="charset"/>, or +<link id="source_charset"/> directives. +For <literal>utf-8</literal>, <literal>windows-1251</literal>, and +<literal>koi8-r</literal> charsets it is sufficient to include the files +<path>conf/koi-win</path>, <path>conf/koi-utf</path>, and +<path>conf/win-utf</path> into configuration. +For other charsets, simply making a fictitious conversion table works, +for example: +<example> +charset_map iso-8859-5 _ { } +</example> +</para> + +</directive> + + +<directive name="charset_map"> +<syntax block="yes"><value>charset1</value> <value>charset2</value></syntax> +<default/> +<context>http</context> + +<para> +Describes the conversion table from one charset to another. +A reverse conversion table is built using the same data. +Character codes are given in hexadecimal. +Missing characters in the range 80-FF are replaced with “<literal>?</literal>”. +When converting from UTF-8, characters missing in a one-byte charset +are replaced with “<literal>&#XXXX;</literal>”. +</para> + +<para> +Example: +<example> +charset_map koi8-r windows-1251 { + C0 FE ; # small yu + C1 E0 ; # small a + C2 E1 ; # small b + C3 F6 ; # small ts + ... +} +</example> +</para> + +<para> +When describing a conversion table to UTF-8, codes for the UTF-8 charset should +be given in the second column, for example: +<example> +charset_map koi8-r utf-8 { + C0 D18E ; # small yu + C1 D0B0 ; # small a + C2 D0B1 ; # small b + C3 D186 ; # small ts + ... +} +</example> +</para> + +<para> +Full conversion tables from <literal>koi8-r</literal> to +<literal>windows-1251</literal>, and from <literal>koi8-r</literal> and +<literal>windows-1251</literal> to <literal>utf-8</literal> +are provided in the distribution files <path>conf/koi-win</path>, +<path>conf/koi-utf</path>, and <path>conf/win-utf</path>. +</para> + +</directive> + + +<directive name="charset_types"> +<syntax><value>mime-type</value> ...</syntax> +<default>text/html text/xml text/plain text/vnd.wap.wml +application/x-javascript application/rss+xml</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>0.7.9</appeared-in> + +<para> +Enables module processing in responses with the specified MIME types +in addition to “<literal>text/html</literal>”. +</para> + +</directive> + + +<directive name="override_charset"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> +<context>if in location</context> + +<para> +Determines if a conversion should be performed for answers +received from a proxied or FastCGI server, +if the answers already carry a charset in the <header>Content-Type</header> +response header field. +If conversion is enabled, a charset specified in the received +response is used as a source charset. +<note> +It should be noted that if a response was received in a subrequest +then conversion from the response charset to the main request charset +is always performed regardless of the <literal>override_charset</literal> +directive setting. +</note> +</para> + +</directive> + + +<directive name="source_charset"> +<syntax><value>charset</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> +<context>if in location</context> + +<para> +Defines the source charset of a response. +If this charset is different from the charset specified +in the <link id="charset"/> directive, a conversion is performed. +</para> + +</directive> + +</section> + +</module>
--- a/xml/en/docs/index.xml +++ b/xml/en/docs/index.xml @@ -95,6 +95,11 @@ ngx_http_browser_module</a> </item> <item> +<a href="/en/docs/http/ngx_http_charset_module.xml"> +ngx_http_charset_module</a> +</item> + +<item> <a href="/en/docs/http/ngx_http_empty_gif_module.xml"> ngx_http_empty_gif_module</a> </item>