Modul mod_czech

Popis modulu:

Modul mod_czech umožňuje webovskému serveru Apache interně konvertovat odesílané textové dokumenty do klientem podporované znakové sady - tj. bez nutnosti spouštět kódovací CGI program, jehož volání k výkonu serveru zrovna nepřispívá. Modul mod_czech se nejprve pokusí automaticky detekovat typ klienta, a poté mu vyžádaný dokument pošle překódovaný do správné znakové sady (ZS). Neznámému klientovi pošle dokument v ASCII, nebo si od něj volbu ZS explicitně vyžádá. Kontext (zvolená znaková sada) je s takovým klientem udržován připojováním prefixu k URL dokumentů (např. "href=/win/index.htm").

Modul je schopen překódovat textové dokumenty (HTML, plain text apod.), "Server Side Includes" (SSI, shtml, phtml) dokumenty, vstupy i výstupy CGI programů, data z formulářů i všechna ostatní serverem zpracovávaná textová data. Prefixy se přidávaji k dokumentům pouze v případě, že si to klient na stránce pro změnu ZS explicitně vyžádal. Při spouštění CGI programů se do environmentu přidávají další proměnné, z kterých může spouštěný program zjistit např. název ZS, v které data od serveru přijímá, a ZS, v které má svůj výstup serveru předat.

Základní informace, mailový archiv a aktuální verze modulu mod_czech naleznete na adrese http://www.intersoft.cz/mod_czech/. Nejnovější verze modulu (včetně alfa a beta verzí) jsou k dispozici na adrese ftp://atrey.karlin.mff.cuni.cz/pub/local/mj/mcz. Vývoj můžete sledovat v konferenci mod_czech@intersoft.cz. Přihlásíte se zasláním mailu, který v těle dopisu obsahuje text subscribe mod_czech, na adresu majordomo@intersoft.cz.

Autoři: Jakub Dadák, Martin Mareš a Martin Plechšmíd.

Direktivy:

Ve verzi 3.0.0 se změnila mimo jiné celá konfigurační část modulu. Protože byla předělána i celá kódovací část, přestal být modul závislý právě jen na českém jazyce. Z obou těchto důvodů jsme názvy naprosté většiny původních direktiv změnili, některé direktivy jsme zrušili a nové přidali. Až na pár výjimek (aby nemusely být upravovány i všechny .htaccess soubory) už není většina direktiv z verze 2.4.0 podporována!

Prefixy a postfixy, udržování kontextu:

Detekce a nastavení znakové sady:

Konfigurace modulu:

Direktivy kvůli zpětné kompatibilitě

Mod_czech poskytuje CGI-skriptům a ostatním modulům informace o použitých znakových sadách, a to nastavením vlastních proměnných prostředí (environment variables).

Heslář:

klient

Klientem je míněn jakýkoliv program komunikující s vaším WWW serverem. Většinou to bývá webovský prohlížeč (browser), ale ne nutně vždy.

kontext (kódovací kontext)

V jaké formě  vrátí server klientovi vyžádaný dokument, závisí na různých okolnostech - na kontextu. (Např., různým klientům jsou dokumenty posílané v různých znakových sadách.) Žádanou formu dokumentů si ale může explicitně (z nabídky) zvolit i sám uživatel. Uživatelem vybraný kontext je udržován (pamatován) prostřednictvím prefixů.

prefix

Prefixy vkládá server do absolutních URL, aby si jejich prostřednictvím udržel přehled o preferencích a volbách, které uživatel provedl. V prefixech může být zakódována např. informace o znakové sadě, do níž má server všechny klientem vyžádané textové dokumenty překódovat.

Prefixy se do absolutních URL vkládají na začátek cesty, hned za název serveru a číslo portu. Další informace ve FAQ.

postfix

Postfixy v URL umožňují autorům HTML stránek  např. určit znakovou sadu, do níž má být odkazovaný dokument překódován, až si jej uživatel vyžádá.
Postfixy plní podobnou úlohu jako prefixy, ale dají se využít i v relativních odkazech. Všechny postfixy jsou serverem konvertovány na odpovídající prefixy.

uživatel

Pod uživatelem máme na mysli člověka, který sedí u svého WWW prohlížeče a čte si stránky umístěné na vašem webovském serveru.

znaková sada

mod_czech aktuálně podporuje následující znakové sady:

• US-ASCII
• ISO-8859-1
• UTF-8 (Unicode UTF-8)
• ISO-8859-2
• windows-1250
• x-mac-ce (Macintosh CE)
• CP852 (PC Latin-2)
• x-kam-cs (bratři Kameničtí)
• CSN_369103 (KOI8CS)

Kromě těchto znakových sad  modul rozeznává ještě pseudo-znakovou sadu (x-)no-code, která se používá v direktivách  v případě, že dokumenty nemají být modulem žádným způsobem konvertovány (modul si jich nemá všímat).
S výhodou lze užívat synonyma názvů znakových sad. Další informace ve FAQ.

AddCharsetAlias

Syntaxe: AddCharsetAlias charset alias [alias ...]
Kontext: konfigurace serveru, virtuální server, adresář, .htaccess
Implicitně: prázdný seznam
Status: rozšiřující
Modul: mod_czech

Direktiva vytvoří nový název (synonymum) pro existující znakovou sadu charset. Nový alias lze použít kdekoliv v konfiguračních souborech, kde je možné užít název znakové sady.

AddCharsetAlias iso-8859-2 iso

Viz též AddCharsetPrefix a AddPostfix.

AddCharsetPrefix

Syntaxe: AddCharsetPrefix charset prefix [prefix ...]
Kontext: konfigurace serveru, virtuální server
Implicitně: prázdný seznam
Status: rozšiřující
Modul: mod_czech

Direktiva vytvoří nový prefix pro znakovou sadu charset.

AddCharsetPrefix us-ascii asc

Viz též AddCharsetAlias a AddPostfix.

AddCharsetToContentType

Syntaxe: AddCharsetToContentType On | Off
Kontext: konfigurace serveru, virtuální server, adresář, .htaccess
Implicitně: AddCharsetToContentType On
Status: rozšiřující
Modul: mod_czech

Direktiva určuje, zda v HTTP hlavičce přidávat do položky Content-Type parametr charset.

Přidávání charsetu by mělo být vždy zapnuté. V případě znakových sad us-ascii a iso-8859-1 se informace o charsetu do Content-Type nepřidávají, takže hodnota On by neměla vadit ani starším prohlížečům, které tomuto parametru nerozumějí. Přidávání parametru charset je přesto možné vypnout i pro jednotlivé prohlížeče:

BrowserMatch Mozilla/1 no_ct_charset

AddPostfix

Syntaxe: AddPostfix prefix postfix [postfix ...]
Kontext: konfigurace serveru, virtuální server
Implicitně: prázdný seznam
Status: rozšiřující
Modul: mod_czech

Tato direktiva vytvoří nový postfix. Kdykoliv pak server tento postfix najde v URL klientem vyžádaného dokumentu, nahradí jej odpovídajícím prefixem a klientovu žádost na toto nové URL přesměruje.

Příklad:

AddPostfix win CP1250

URL http://server/cesta/document.html.CP1250 bude potom serverem přeměrováno na http://server/win/cesta/document.html.

Poznámka: Parametr prefix nemusí být registrovaný žádnou z direktiv AddXxxPrefix.

Viz též AddCharsetAlias a AddCharsetPrefix.

AddModCzechServer

Syntaxe: AddModCzechServer server_name [port ...]
Kontext: konfigurace serveru, virtuální server, adresář, .htaccess
Implicitně: aktivní server a všechny jeho virtuální servery
Status: rozšiřující
Modul: mod_czech

Direktiva přidá webovský server s názvem server_name do seznamu serverů, s nimiž se má udržovat kódovací kontext. Je-li uveden i seznam portů, bude se kontext udržovat jen při odkazech na uvedené porty.

To znamená, že ke všem HTTP odkazům na tento server (vč. redirekcí) bude připojován prefix odpovídající explicitně zvolené znakové sadě. Nebyla-li znaková sada zvolena explicitně, nemá tato direktiva vliv.

AddModCzechServer www.intersoft.cz

Poznámka: Udržovat kódovací kontext mezi různými počítači je důležité např. při spojení více webovských serverů dohromady v lokální síti, kde každý server obsluhuje jinou část webovského stromu.

AddSourceCharset

Syntaxe: AddSourceCharset charset extension [extension ...]
Kontext: konfigurace serveru, virtuální server, adresář, .htaccess
Implicitně: prázdný seznam
Status: rozšiřující
Modul: mod_czech

Server (v mod_mime) zjišťuje mime-typ, jazyk a jiné charakteristiky vyžádaných souborů podle jejich přípon (extenzí). Direktiva AddSourceCharset umožňuje serveru získat z extenzí souboru i informaci o znakové sadě, ve které je dokument vytvořen. Přípona extension značí soubor vytvořený v znakové sadě charset.

Příklad:

AddSourceCharset windows-1250 win
/usr/local/www-root/path/muj_text.html.win

Poznámka: Máte-li povolené "multiviews" (direktivou Options +multiviews), může si uživatel vyžádat soubor z příkladu i bez uvedení kódovací přípony win:

http://muj_server/path/muj_text.html

Viz též SourceCharset, AllowMETASourceCharset.

AllowHtmlParsing

Syntaxe: AllowHtmlParsing On | Off
Kontext: konfigurace serveru, virtuální server, adresář, .htaccess
Implicitně: AllowHtmlParsing On
Status: rozšiřující
Modul: mod_czech

Direktiva serveru umožňuje provádět v HTML dokumentech, kromě prostého překódování znakové sady, ještě další úpravy, které jsou nutné např. k udržení kódovacího kontextu.

Aby explicitně zvolený kontext bylo možné udržet i v případě, že uživatel následuje absolutní odkazy, které vedou z HTML souborů, musí server do všech absolutních odkazů doplňovat příslušné prefixy. Dále musí zajistit, aby název znakové sady, uváděný v HTML dokumentech v direktivě <META>, odpovídal znakové sadě, do které byl dokument překódován.

Podrobněji lze "parsování" HTML ovládat direktivami PrependPrefixes a AllowMETASourceCharset.

AllowMETASourceCharset

Syntaxe: AllowMETASourceCharset On | Off
Kontext: konfigurace serveru, virtuální server, adresář, .htaccess
Implicitně: AllowMETASourceCharset On
Status: rozšiřující
Modul: mod_czech

Některé HTML editory přidávají na začátek vytvořených dokumentů informaci (ve formě HTML tagu <META>) o znakové sadě, v níž byl dokument napsán. Direktiva AllowMETASourceCharset umožní serveru tuto informaci využít a dát jí přednost před nastavením direktivou SourceCharset.

Poznámka: Znakovou sadu, ve které je HTML dokument napsán, lze měnit i přímo uvnitř dokumentu, ale tuto metodu nedoporučujeme používat. K tomuto účelu modul podporuje speciální HTML komentář <!--mycharset="charset"-->. Server komentář odstraní a předpokládá, že následující část dokumentu je psána v nové znakové sadě charset.

Tag <!--mycharset="charset"--> je zahrnut jen pro usnadnění přechodu z kódovacího programu SaCzech. Vhodná kombinace sekcí <Files> (při využití "divokých karet") s direktivou SourceCharset, používání kódovacích přípon definovaných direktivou AddSourceCharset, případně HTML tag <META> poskytnou obdobné nebo lepší služby. Viz FAQ.

Direktiva AllowMETASourceCharset vyžaduje AllowHTMLParsing On.

CacheEncodedDocs

Syntaxe: CacheEncodedDocs On | Off
Kontext: konfigurace serveru, virtuální server, adresář, .htaccess
Implicitně: CacheEncodedDocs On
Status: rozšiřující
Modul: mod_czech

Direktiva povolí či zakáže cacheování překódovávaných dokumentů. Je-li cacheování povoleno, může se stát, že klient z cache dostane vyžádaný dokument ve špatné znakové sadě. Na druhou stranu, zákaz cacheování způsobí, že uživatelé si při opakovaném čtení budou muset dokument stahovat ze serveru vždy znovu a znovu. (Kromě toho, že jim to bude nepříjemné, zbytečně se tím zvýší tok dat v Internetu.)

Na dokumenty posílané protokolem HTTP/1.1 nemá direktiva vliv, tato verze protokolu již umožňuje s cachí podmínky cacheování dohodnout. Podrobnější informace k tomu v FAQ.

CzechModule

Syntaxe: CzechModule On | Off
Kontext: konfigurace serveru, virtuální server, adresář, .htaccess
Implicitně: CzechModule On
Status: rozšiřující
Modul: mod_czech

Direktiva umožňuje vypnout veškeré funkce modulu mod_czech.

Poznámka: Tato direktiva, pokud je použita v sekci <Directory> nebo v souboru .htaccess, nezabrání serveru ve zpracování prefixů a postfixů v URL v žádostech klientů. Výsledek zpracování těchto prefixů a postfixů je však ignorován.

EncodeContentType

Syntaxe: EncodeContentType content-type
Kontext: konfigurace serveru, virtuální server, adresář, .htaccess
Implicitně: EncodeContentType application/x-www-form-urlencoded
Status: rozšiřující
Modul: mod_czech

Direktiva přidá content-type do seznamu mime-typů, které má modul překódovávat, tj. měnit jejich znakovou sadu tak, aby odpovídala požadavkům a schopnostem klientů. (Server kóduje jak klientem vyžádaný dokument, tak před tím i data v těle klientovy žádosti (např. data z formulářů), poslaná metodou POST nebo PUT).

Přiklad:

EncodeContentType text/html

Poznámka: Překódovávání lze v různé míře zabránit direktivami

SourceCharset no-code
FormDataEncoding Off
CzechModule Off

FallbackCharset

Syntaxe: FallbackCharset charset | chcp
Kontext: konfigurace serveru, virtuální server, adresář, .htaccess
Implicitně: FallbackCharset chcp
Status: rozšiřující
Modul: mod_czech

Jestliže server nepozná, v které znakové sadě klient dokumenty vyžaduje, rozhodne se na základě této direktivy. Buďto dokumenty překóduje do znakové sady charset, nebo (při zvoleném chcp) pošle klientovi stránku s nabídkou možných kódování.

Viz GuessCharset.

FormDataCharset

Syntaxe: FormDataCharset charset
Kontext: konfigurace serveru, virtuální server, adresář, .htaccess
Implicitně: FormDataCharset iso-8859-2
Status: rozšiřující
Modul: mod_czech

Určí znakovou sadu, do které se mají všechna data posílaná klientem (např. údaje z HTML formulářů) překódovat. CGI skripty i ostatní moduly Apache dostanou data již překódovaná.

FormDataEncoding

Syntaxe: FormDataEncoding On | Off
Kontext: konfigurace serveru, virtuální server, adresář, .htaccess
Implicitně: FormDataEncoding On
Status: rozšiřující
Modul: mod_czech

Direktiva umožňuje zakázat překódovávání dat v těle žádosti zaslané klientem (metodou POST nebo PUT). Je-li kódování povoleno, překóduje modul data z WWW formulářů a data MIME-typů nastavených direktivou EncodeContentType do znakové sady zvolené direktivou FormDataCharset.

FormURLEncoding

Syntaxe: FormURLEncoding On | Off
Kontext: konfigurace serveru, virtuální server, adresář, .htaccess
Implicitně: FormURLEncoding On
Status: rozšiřující
Modul: mod_czech

Direktiva umožňuje zakázat překódování URL řetězce poslaného klientem. I URL řetězec může obsahovat (%-kódované) ne-ascii znaky.

Viz též FormDataEncoding.

GuessCharset

Syntaxe: GuessCharset On | Off
Kontext: konfigurace serveru, virtuální server, adresář, .htaccess
Implicitně: GuessCharset On
Status: rozšiřující
Modul: mod_czech

Direktiva určuje, zda se má server v případě, že klient v HTTP hlavičce neposlal položku Accept-Charset, pokusit "uhádnout" požadovanou znakovou sadu sám. Jestliže v "hádání" neuspěje nebo má hádání zakázané (GuessCharset Off), řídí se server direktivou FallbackCharset.

Algoritmus určování požadované znakové sady je následující:

1. Poslal klient v HTTP hlavičce položku Accept-Charset? Jestli ano, použij.
2. Jestli ne, ale je povolený GuessCharset, tak zkus charset odhadnout.
3. Jestliže bylo hádání neúspěšné, řiď se podle FallbackCharset.
4. V nejhorším případě zvol us-ascii.

Při hádání požadované znakové sady se server řídí obsahem env. proměnných browser_charset a ignore_charset. Ke správnému nastavení těchto proměnných slouží apachovské direktivy BrowserMatch a BrowserMatchNoCase, např.

BrowserMatchNoCase .*\(X11 browser_charset=iso-8859-2
BrowserMatch Mozilla/4 ignore_charset=iso-8859-1,utf-8

Proměnná browser_charset může nabývat stejných hodnot jako argument direktivy FallbackCharset.
Někteří klienti vkládají do HTTP položky Accept-Charset nesmyslné údaje. Proměnná ignore_charset obsahuje seznam znakových sad (oddělených čárkami), které má server v položce Accept-Charset ignorovat.

Ukázky použití najdete v ukázkové konfiguraci dodané s modulem.

PrependPrefixes

Syntaxe: PrependPrefixes On | Off
Kontext: konfigurace serveru, virtuální server, adresář, .htaccess
Implicitně: PrependPrefixes On
Status: rozšiřující
Modul: mod_czech

Direktiva umožňuje zakázat přidávání prefixů pro udržení kódovacího kontektu s klientem, u kterého nebyla detekována jeho znaková sada. V tomto případě se spoléhá pouze na automatickou detekci klienta, která je ale poměrně úspěšná. Zákazem prefixů se uživatelům znemožní explicitní volba znakové sady!

Poznámky:

• Automatická detekce znakové sady bývá neúspěšná zvláště při přístupech na váš server z ciziny, kde se nedá očekávat, že mají nainstalované naše lokální prostředí. Blíže k tomuto tématu v FAQ.
• Dokument v původním tvaru (bez úprav HTML tagů, ale zároveň bez překódování) může klient získat i jinými způsoby.

SetLastModified

Syntaxe: SetLastModified On | Off
Kontext: konfigurace serveru, virtuální server, adresář, .htaccess
Implicitně: SetLastModified On
Status: rozšiřující
Modul: mod_czech

Při hodnotě On nastavuje server v HTTP hlavičce překódovaných dokumentů položku Last-modified na aktuální datum. Aby správně fungovalo cachování, musí být SetLastModified Off.

SourceCharset

Syntaxe: SourceCharset charset
Kontext: konfigurace serveru, virtuální server, adresář, .htaccess
Implicitně: SourceCharset iso-8859-2
Status: rozšiřující
Modul: mod_czech

Direktiva serveru oznamuje, že všechny dokumenty (na serveru | v daném adresáři | lokaci - podle kontextu) jsou uloženy v znakové sadě charset. Z této znakové sady pak mod_czech dokumenty překódovává do znakové sady vyžádané klientem.

Kódování, v němž jsou na serveru dokumenty uloženy, lze ale určit i pro každý soubor zvlášť:

1. extenzí souboru (viz direktiva AddSourceCharset),
2. speciálními HTML tagy (viz direktiva AllowMETASourceCharset).

Direktivy kvůli zpětné kompatibilitě:

Aby vám při přechodu ze starších verzí modulu mod_czech na verzi 3.x nevznikaly velké problémy, zůstaly zachovány direktivy, které bylo možné užít v souborech .htaccess:

SourceCzechCodePageLocal a FormDataCPTargetLocal.

Funkční část související s direktivami LookupCzechExtensions a LookupCzechExtensionsLocal byla přesunuta do nového modulu mod_subst.

Proměnné prostředí

Mod_czech nastavuje některé proměnné prostředí (environment variables), a ukládá do nich informace o znakových sadách, které se týkají právě zpracovávaného dokumentu.

(Poznámka: Z důvodů zpětné kompatibility byly ponechány i proměnné CZECH_OUTPUT_CP a CZECH_INPUT_CP. Nedoporučujeme je však používat v nově vytvořených skriptech.)

Nejširší použití mají, samozřejmě, především proměnné INPUT_CHARSET a OUTPUT_CHARSET. Zbývající proměnné mohou např. pomoci odhalit, že uživatel vyplnil formulář bez hacku a carek.