MultiCharset Htmls Module

• Краткое описание
• Текущий статус и поддержка
• Где взять?
• Как установить?
• Директивы, добавляемые этим модулем к apache
• Полезные команды mime_module
• Имеющиеся ограничения
• Примеры конфигурации

Предуведомление

Что это такое

Статус и поддержка

В случае распространения модуля в составе какого-то тиражируемого программного продукта и/или пакета услуг (скажем, услуги по "установке программного обеспечения WWW-сервера"), необходимо связаться со мной и обговорить условия такого распространения.

При модификации необходимо сохранить упоминание о моем авторстве.

Модуль написан прежде всего для того, чтобы минимизировать поток приходящей ко мне электронной почты (я получил уже безумное количество вопросов "как хранить документы в нескольких кодировках"), никакой поддержки я никому не обещаю. Впрочем, если есть желающие за такую поддержку заплатить - это совсем другой разговор :).

С другой стороны, конструктивная критика и помощь в отладке приветствуются.

Где это взять

Как это собрать

Module mc_htmls_module     mod_mc_htmls.o

Внимание! Для использования этого модуля, Apache должен быть собран с mime_module. Я не вижу причин, по которым mime_module хотелось бы выкинуть, это так, предупреждение на всякий случай.

Как сконфигурировать сервер

FileCharset <name> <tablefile>

Default: никаких FileCharset
Context: server, virtual host
Использование: Описание правила перекодировки файла во внутреннюю кодировку сервера.

• <name> - имя charset (произвольный набор букв и цифр без пробелов), используется для дальнейших ссылок на это правило перекодировки
• <table> - имя файла с таблицей перекодировки относительно $serverroot. Таблица описывает перекодировку из "файла на диске" во внутреннее представление сервера (внутреннее представление - это кодировка русского языка, принятая в вашей системе, обычно это KOI8-R). Формат таблиц аналогичен используемому в Russian Apache

Если описано несколько FileCharset с одинаковым именем, то будет использоваться более раннее описание.
Пример:

• FileCharset cp1251 conf/win-koi.tab
  

описывает charset с именем cp1251 и перекодировкой во "внутреннее" представление по таблице $SERVER_ROOT/conf/win-koi.tab.

UseFileCharset <name> extension1 extension2

Default: никакого
Context: конфигурация сервера, virtual host, <Directory>, .htaccess.
Использование: связывает правило перекодировки с расширением файла.

• <name> - имя правила из директивы FileCharset
• extensionN - одно или несколько расширений файлов, которым нужно применять это правило. Расширение может включать ведущую точку.

В случае, когда одно расширение использовано в нескольких директивах с разными UseFileCharset на одном уровне видимости, то сработает более позднее описание. Порядок приоритета для описания на разных уровнях видомости обычный для Apache (см. документацию на Apache) - наибольший приоритет у .htaccess (если разрешено AllowOverride), наименьший - у server-wide конфигурации.
Пример

UseFileCharset koi8 .html .htm
UseFileCharset cp1251 .htmw .h1251
<Directory /some/where>
UseFileCharset cp1251 .html
</Directory>

- использовать для файлов .html и .htm таблицу, описанную в FileCharset koi8, а для .htmlw и .h1251 - описанную в FileCharset cp1251. В директории /some/where для файлов .html будет использована таблица cp1251.

DefaultFileCharset <name>

Default: никакого
Context: конфигурация сервера, virtual host, <Directory>, .htaccess.
Использование: Директива указывает серверу, какой FileCharset использовать для перекодировки файлов в случае, когда расширение файла не описано в UseFileCharset.

• <name> - название кодировки из директивы FileCharset

В случае, когда DefaultFileCharset не задан и файл не описывается UseFileCharset, поведение сервера отличается для двух различных ситуаций:

• Если включен режим RecodeAllFiles on (см ниже), то при неустановленом DefaultFileCharset управление передается дальше по цепочке обработчиков
• Если файл "подпал" под обработку в результате действия директивы AddHandler (cм полезные команды mime_module ниже), то файл просто не перекодируется.

Зарезервированное имя none отменяет DefaultFileCharset, унаследованный от директории верхнего уровня или глобальной конфигурации сервера. Прочий порядок наследования - обычный для Apache.
Пример:

DefaultFileCharset koi8
<Directory /some/where>
AllowOverride FileInfo
DefaultFileCharset cp1251
</Directory>
<Directory /another/place>
DefaultFileCharset none
</Directory>

- использовать DefaultCharset с именем koi8 для всего сервера, кроме директории /some/where, где использовать cp1251 и директории /another/place, для которой (и ее поддиректорий, если в них не указано иначе) отменить DefaultCharset совсем.

RecodeAllFiles on|off

Default: off
Контекст: конфигурация сервера, виртуального сервера, directory, .htaccess.
Использование: Включение этой опции указывает серверу, что перекодировку нужно производить для всех файлов с Content-Type: text/html. При этом, для расширений файлов, описанных в директиве UseFileCharset перекодировка производится в соответствии с этой директивой, а для всех прочих - в соответствии с директивой DefaultFileCharset. Если DefaultFileCharset не установлена, то перекодировка не производится, а управление передается дальше по цепочке handler'ов для типа text/html.
ВНИМАНИЕ! У сервера может быть установлено несколько обработчиков типа text/html. Например, директива XBitHack включает обработку файлов с установленным executable bit как server-parsed (SHTML) документов. Порядок вызова обработчиков зависит от порядка их описания в файле Configuration сервера. Вследствие этого, при наличии более одного обработчика для text/html можно получить конфигурацию, которая ведет себя достаточно странно. Например, mod_mc_htmls в включенной опцией RecodeAllFiles может "отбирать" документы (или часть документов) от XBitHack, а может получиться и наоборот. Никакой сложности тут нет, просто нужно понимать что вы делаете :)

Если опция RecodeAllFiles выключена, то перекодировка производится только для документов, для которых установлен server-recoded handler. См описание использования команд mime_module ниже в этом документе.

StripHttpEquivs on|off

Default: off
Контекст: конфигурация сервера, виртуального сервера, directory, .htaccess.
Использование: Разрешает или запрещает удаление строчек <meta http-equiv ....> из заголовка документа. Эта директива введена для борьбы с очевидным противоречием - ряд HTML-редакторов ставит через HTTP-equiv Content-Type документов, в результате чего в HTTP-заголовках и в самом документе Content-Type может оказаться несогласованным. Это несогласование приводит к неприятным последствиям. Во-первых, ряд броузеров ошибочно предпочитают HTTP-Equiv HTTP-заголовкам, что неправильно. Во-вторых, если документ берется из локального кэша броузера, то http-заголовков он уже не содержит и броузер берет информацию о Content-Type из <META>.
Простейшим способом убрать это противоречие оказалось удаление всех <META HTTP-EQUIV из документа. Лучше, конечно, удалять его прямо в файле, но не все авторы HTML-документов на это способны. Для неспособных предназначена директива StripHttpEquivs. Эта директива работает только если документ обрабатывается данным модулем. Т.е. если включен режим RecodeAllFiles+DefaultFileCharset или расширение документа описано в директиве UseFileCharset.

Использование команд mime_module для управления перекодировками

AddType mimetype/sybtype extension extension

Это команда mime_module, которая используется для указания MIME-type файла с нестандартным расширением. Команда может быть использована как на server-wide уровне, так и для директорий, для которых разрешен Override FileInfo.
Пример:

• AddType text/html .htm8 .htm1251 .htmlw
  

- воспринимать файлы с расширением .htm8, .htm1251, .htmlw как имеющие тип text/html (т.е. так же как и *.html). Это нужно делать по двум причинам. Во-первых, от mime-type зависит интерпретация файлов броузером, во-вторых, обработчик по-умолчанию (при включенной опции RecodeAllFiles обрабатывает только файлы с типом text/html)

Имеющиеся ограничения

• В настоящее время поддерживаются только plain html. Т.е. ни SSI, ни CGI работать в кодировках, отличных от "внутренней кодировки сервера" работать не будут. Фактически, модуль подменяет только default_handler, т.е. тот кусок кода сервера, который работает, если никакие другие методы обработки для данного файла не определены.
• Поддерживается только работа под Unix. Код, обеспечивающий работу под OS/2 (EMX) не перенесен т.к. мне негде его тестировать
• При указании в теле документа ссылок (href) с использованием русских букв необходимо писать их именно как буквы. Конструкции вида
  <a href="script.cgi?value=%aa%bb%cc"> перекодироваться не будут. Это можно рассматривать и как feature.
• Аналогично, не перекодируются конструкции вида &code; (&Ecirc; и т.п.)

Примеры конфигурации

Простейшая конфигурация - перекодировать только файлы .htmlw

AddType text/html .htmlw
FileCharset cp1251 conf/win-koi.tab
UseFileCharset  cp1251 .htmlw
AddHandler server-recoded .htmlw

Перекодировать все файлы text/html, но .htm - по таблице win-koi, а все остальные - по таблице koi-koi. Откусывать <META HTTP-EQUIV

FileCharset koi8 conf/koi-koi.tab
FileCharset cp1251 conf/win-koi.tab
UseFileCharset cp1251 .htm
DefaultFileCharset koi8
RecodeAllFiles on
StripHttpEquivs on

(C) Alex Tutubalin, 1997