<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Директивы модуля ngx_http_charset_module"
        link="/ru/docs/http/ngx_http_charset_module.html"
        lang="ru">

<section name="" id="summary">

<para>
Модуль ngx_http_charset_module добавляет указанную кодировку
в строку "Content-Type" в заголовок ответа.
Кроме того, модуль может перекодировать данные из одной кодировки в другую
с некоторыми ограничениями:
<list type="bullet">

<listitem>
перекодирование осуществляется только в одну сторону — от сервера к клиенту,
</listitem>

<listitem>
перекодироваться могут только однобайтные кодировки
</listitem>

<listitem>
или однобайтные кодировки в UTF-8 и обратно.
</listitem>

</list>
</para>

</section>


<section name="Пример конфигурации" id="example">

<para>
<example>
    include         conf/koi-win;

    charset         windows-1251;
    source_charset  koi8-r;
</example>
</para>

</section>


<section name="Директивы" id="directives">

<directive name="charset">
<syntax><value>кодировка|off</value></syntax>
<default>off</default>
<context>http, server, location, if в location</context>

<para>
Директива charset добавляет в строку "Content-Type"
в заголовке ответа указанную кодировку.
Если эта кодировка отличается от указанной в директиве
<link id="source_charset"/>, то выполняется перекодирование.
</para>

<para>
Параметр "off" отменяет добавление кодировки в строку "Content-Type"
в заголовке ответа.
</para>

<para>
Кодировка может быть задана переменной:
<example>
charset     $charset;
</example>
</para>

<para>
В этом случае необходимо, чтобы все возможные значения переменной
присутствовали хотя бы один раз в любом месте конфигурации в виде
директив charset_map, charset, или source_charset.
Для кодировок utf-8, windows-1251 и koi8-r для этого достаточно
включить в конфигурацию файлы conf/koi-win, conf/koi-utf и conf/win-utf.
Для других кодировок можно просто сделать фиктивную таблцу перекодировки,
например:
<example>
charset_map  iso-8859-5  _ { }
</example>
</para>

</directive>


<directive name="charset_map">
<syntax><value>кодировка1 кодировка2 { ... }</value></syntax>
<default/>
<context>http</context>

<para>
Директива charset_map описывает таблицу перекодирования из одной
кодировки в другую.
Таблица для обратного перекодирования строится на основании тех же данных.
Коды символов задаются в шестнадцатеричном виде.
Неописанные символы в переделах 80-FF заменяются на "?".
При перекодировании из UTF-8 символы, отсутствующие в однобайтной кодировке,
заменяются на "&amp;#XXXX;".
</para>

<para>
Пример использования:
<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>
При описании таблицы перекодирования в UTF-8, значения этой кодировки должны
описываться во второй колонке, например:
<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>
Полные таблицы преобразования из koi8-r в windows-1251
и из koi8-r и windows-1251 в utf-8
входят в дистрибутив и находятся в файлах conf/koi-win, conf/koi-utf
и conf/win-utf.
</para>

</directive>


<directive name="charset_types">
<syntax><value>mime-тип [mime-тип ...]</value></syntax>
<default>text/html text/xml text/plain text/vnd.wap.wml
application/x-javascript application/rss+xml.
</default>
<context>http, server, location</context>

<para>
Директива (0.7.9) разрешает работу модуля в ответах с указанными MIME-типами
в дополнение к "text/html". По умолчанию используются
<list type="bullet">
<listitem>text/html</listitem>
<listitem>text/xml</listitem>
<listitem>text/plain</listitem>
<listitem>text/vnd.wap.wml</listitem>
<listitem>application/x-javascript</listitem>
<listitem>application/rss+xml</listitem>
</list>
</para>

</directive>


<directive name="override_charset">
<syntax><value>on|off</value></syntax>
<default>off</default>
<context>http, server, location, if в location</context>

<para>
Директива определяет, выполнять ли перекодирование для ответов,
полученных от проксированного сервера или от FastCGI-сервера,
если в них уже есть charset в строке "Content-Type" в заголовке ответа.
Если перекодирование разрешено, то в качестве исходной кодировки
используется кодировка, указанная в полученном ответе.
</para>

<para>
Необходимо отметить, что если ответ был получен в подзапросе,
то, независимо от директивы override_charset, всегда выполняется
перекодирование из кодировки ответа в кодировку основного запроса.
</para>

</directive>


<directive name="source_charset">
<syntax><value>кодировка</value></syntax>
<default/>
<context>http, server, location, if в location</context>

<para>
Директива source_charset задают исходную кодировку ответа.
Если эта кодировка отличается от указанной в директиве
<link id="charset"/>, то выполняется перекодирование.
</para>

</directive>

</section>

</module>