C-SaCzech 2.1

Home
Další vývoj
Co je CSáček
Download
FAQ
Instalace
Dokumentace
Kredit
Kontakty
Podpora
Historie
Licence
Další info o češtině
  | ## Dokumentace Proč zvolit právě CSáček ? Návod k použití Základy - URL stránky Zachování kódu při odkazech Kóduje se pouze text a HTML Změna výchozího kódu Překódovávání "chráněných" stránek Vypisování konfigurace CSáčka Apache CSáček Jak se konfiguruje Apache verze Podpora SSL ISAPI CSáček Jak se konfiguruje ISAPI verze Objednávka ISAPI CSáčku Konfigurační direktivy Příkazy CSáčku Příklady použití Úvodní stránka Zpět k hlavní stránce ### CSáček nabízí možnost funkce jako CGI, FastCGI nebo Apache modul, na UN*Xu (NetBSD, Linux, Solaris, IRIX, Digital Unix), CGI a ISAPI na MS Windows NT pod Apache 1.3.X možnost používat CSáček jako DSO modul on-fly kompresi dokumentů, posílaných klientovi (kompresi podporuje např. Netscape 4.5+, lynx, MSIE 4.0+) podpora `META` tagu pro označení kódování češtiny v dokumentu podporu Unicode (UTF-8) podporu relativních odkazů i absolutních odkazů, automatické přepisování absolutních odkazů pro zachování výběru kódování možnost používat různé typy kódování češtiny ve zdrojových textech stránek; je dokonce možno použít víc kódů v rámci jedné stránky možnost kódovat i dynamicky vytvářené stránky (např. výsledky různých skriptů) překódování vstupu od klienta (data z formulářů) do kódování serveru podporu azbuky Zpět ### Základ - URL stránky Stránku napište v kódu, který odpovídá zvolenému implicitnímu kódu serveru (ve skutečnosti kódování stránky není omezeno). Vystavte ji, jak je obvyklé. Jediné, co se změní, bude URL, kterým je třeba se odkázat na stránku. Jestliže URL stránky bez překódování by bylo `http://www.kdesi.cz/cesta/stranka.html` bude URL téže stránky při požadavku jejího překódování do sedmibitového ASCII `http://www.kdesi.cz/toASCII/cesta/stranka.html` za předpokladu, že používáte Apache CSáček. Tento odkaz však předpokládá, že předem víte, jaký kód bude uživatel vyžadovat. To často nemusí být pravda. V takovém případě doporučuji spustit CSáček v módu `whichcode` - URL bude vypadat nějak takto: `http://www.kdesi.cz/whichcode/cesta/stranka.html` Na základě externí šablony bude vygenerována stránka, kde bude uživateli bude oznámeno, že cílový dokument obsahuje diakritická znaménka a umožní mu zvolit kód, který považuje za optimální. Druhá možnost je použít `toGUESS`. V tomto módu se CSáček pokusí zjistit, jaké kódování a jazyk klient podporuje a přesměruje klienta na URL, které odpovídá jeho jazykovým/kódovacím schopnostem. Momentálně každému klientovi z Česka vnutí `ISO-8859-2` (klient, který by nerozuměl tomuto kódování se dá považovat za nefunkční), ostatním pak `ASCII`. Pokud by měl uživatel tu smůlu, že používá nefunkčního klienta, může si typ kódování později změnit explicitně přes `whichcode`. V případě Apache modulu a ISAPI filteru se mód `toGUESS` používá implicitně v případě, že URL neobsahuje CSáček, tj. jedná se o jednoduché URL typu `http://www.nekde.cz/cosi.html`. Zjednodušuje se tak URL v obvyklém případě, kdy uživateli uhádnutý default vyhovuje. ### Zachování kódování při odkazech CSáček od verze 2.0 automaticky přepisuje odkazy v dokumentu tak, aby se v daném URL opět objevil a zachovala se tak informace o vybraném kódování. Nemusíte se tedy o odkazy jakýmkoli způsobem starat, CSáček vše upraví za Vás. Je nutno pouze zachovat opatrnost při skládání odkazů v JavaScriptu - tyto odkazy samozřejmě CSáček nemůže změnit. Pokud je to jen trochu možné, použijte tady relativní odkazy. Pokud se odkazujete na jiné servery s CSáčkem a chcete, aby se při odkazech zachovala informace o uživatelem vybraném kódování, musíte CSáčkovi seznam takových serverů sdělit. CSáček pak upravuje URL v dokumentech podobným způsobem, jako při odkazech v rámci "svého" serveru. Podrobněji viz popis konfiguračního příkazu Apache `csacekServers`. CSáček jako Apache modul automaticky přidá do seznamy všechny virtuální servery WWW serveru, na kterém běží. Samozřejmě lze na stránku napsat obvyklý seznam odkazů pro zobrazení dokumentu v ASCII, ISO-8859-2 či CP1250: `<A HREF="/toASCII/">ASCII/</A>` `<A HREF="/toISO-8859-2/">ISO-8859-2/</A>` `<A HREF="/toCP1250/">CP1250/</A>` ### Kóduje se pouze text a HTML CSáček kóduje pouze dokumenty typu `text/html` (HTML dokumenty) a obecně `text/*` (jako textová data). Dokumenty, které mají neznámý textový typ (např. `text/javascript`) jsou zpracovány jako `text/plain`, tedy nerozeznávají se tam žádné HTML značky a nepřepisuje se URL. Dokumenty netextových typů (tj. cokoliv co má MIME typ jiný než `text/*`) předá CSáček beze změny. Kvůli rychlosti zpracování CGI CSáček implicitně pokládá za "překódovatelné" soubory s příponou `.html`, `.htm`, `.txt`. O všechny ostatní dokumenty požádá zpět WWW server a rozhodne se, zda daný dokument kódovat nebo ne, podle informací, které server vrátí (zpracování přes další požadavek je samozřejmě pomalejší). Apache/ISAPI CSáček má informaci o typu souboru vždy jednoduše k dispozici, proto tam neexistuje žádný pevný seznam přípon a vše záleží jen na konfiguraci serveru. ### Změna výchozího kódu Implicitní výchozí kód, ve kterém budou psány dokumenty, určuje správce serveru při instalaci CSáčku. Mělo by se jednat o kód, ve kterém bude vytvářena většina stránek (nejlépe všechny). Pokud autor používá jiné kódování, má v základě dvě možnosti: Převést stránku do implicitního kódu. To je méně pohodlné a navíc to komplikuje pozdější úpravy na stránce (každá úprava bude vyžadovat nové překódování). Ponechat stránku v kódu původním a vyznačit jej. CSáček podporuje `META` tag a zařídí se podle informace, která je tam uvedena, tj. je-li tam `<META HTTP-Equiv="Content-Type"Content="text/html; charset=windows-1250">` CSáček správně pochopí, že obsah dokumentu je v kódování používaném na MS Windows a zařídí se podle toho. CSáček podporuje také jiný mechanismus vyznačení kódování textu - pomocí příkazu `MYCHARSET`. Vhodný je zejména tehdy, pokud různé části dokumentu obsahují text v různém kódování. Pokud máte celý dokument v jednom kódování, použijte raději příslušný `META` tag. Prohlížeč tak má informaci o kódování dokumentu i v případě, že dokument nedostane přes CSáček. Účinnost příkazu `MYCHARSET`, popř. `META` tagu začíná místem, kde byl uveden. Přestože CSáček povoluje použít `META` tag s vyznačením kódování několikrát, toto není platné užití podle HTML standardu. ### Podpora chráněných stránek Následující text platí pouze pro (Fast)CGI CSáček; pokud je CSáček součást WWW serveru (Apache modul nebo ISAPI filter), použijí se bezpečnostní mechanismy daného serveru bez toho, že by je CSáček nějak ovlivňoval. Při přímém předávání obsahu souboru CGI CSáček dává pozor, jestli se na "cestě" k němu nevyskytuje nějaký konfigurační soubor (standardně `.htaccess`). Pokud ano, o dokument požádá server. Bohužel pak nastane problém v tom, že WWW server většnou z bezpečnostních důvodů nepředává CGI skriptům login a heslo poslané klientem. Při zpětném požadavku o chráněný dokument tedy CGI CSáček nemůže tuto informaci poslat a přístup k dokumentu je tedy zamítnut. Lze samozřejmě upravit zdrojový kód serveru tak, aby tuto informaci CGI skriptům předával. Jedná se ale o možné bezpečnostní riziko a tedy toto nedoporučuji. Pokud potřebujete překódování veřejně nepřístupných stránek, použijte CSáček jako Apache modul. ### Vypisování konfigurace CSáčka Pokud do browseru zadáte URL na stránku na serveru s CSáčkem a připojíte k URL `?csacek_info`, CSáček vytvoří a vypíše krátkou informační HTML stránku s popisem konfigurace pro toto URL a seznamem zakompilovaných nastavení. Tato vlastnost je užitečná zejména při aktualizaci či ladění konfigurace CSáčku pro daný server. Tuto vlastnost lze při kompilaci vypnout. Zpět ## Apache CSáček CSáček na Apache byl původně na 1.2.4. Nyní je primárně vyvíjen na Apache 1.3.19 s tím, že je možné ho používat i na Apache 1.1.1 i Apache 1.2.X. Není nutné patchovat server, CSáček modul se do serveru přidává jako kterýkoli jiný modul. Pod Apache 1.3.X je ho možné dokonce (s pomocí `axps`) zkompilovat jako DSO modul a nahrávat do serveru dynamicky. ### Jak se konfiguruje Apache verze Seznam konfiguračních direktiv viz konfigurační direktivy CSáčku. Apache CSáček se nastavuje pomocí sady direktiv, uvedených v konfiguračních souborech serveru (globálním `httpd.conf` nebo případných `.htaccess`). CSáček lze nastavovat různě pro každý virtualní server i adresář, je třeba jen direktivů uvést v příslušné sekci `<Location>` či `<VirtualHost>`. Pokud je jako parametr direktivy řetezec obsahující mezery, je nutné jej celý uzavřít mezi uvozovky (může být případ `csacekTemplateDir`). Příklad z konfigurace: `csacekEngine On csacekDefaultCharset windows-1250` ### Podpora SSL #### Apache-SSL U modulu Apache-SSL stačí od verze 1.17 v souboru `apache_ssl.c` změnit `SSL_IS_OPTIONAL` na `TRUE`. Apache-SSL pak bude fungovat i bez CSáčku, pouze se přidá několik testů na obsah některých struktur. Tyto testy jsou nutné proto, aby CSáček byl schopen během své práce dočasně "vypnout" SSL. Komunikace s klientem (čtení vstupu od něj i výstup ze serveru) jsou stále v SSL, toto jen vypne SSL při vnitřním zpracování tak, aby CSáček data dostal nezakódovány. #### mod_ssl Od verze 2.1.2 funguje CSáček i společně s mod_ssl. Nejsou třeba žádné úpravy kódu. Od verze 2.1.9 funguje CSáček i v případě, že se nepoužívá autentifikace uživatelů. Pozor: Při použití `LoadModule` v konfiguraci serveru je třeba zařídit, aby se CSáček modul nahrál dříve než mod_ssl. Toto je nutné kvůli tomu, že CSáček potřebuje v určité fázi zpracování změnit vnitřní struktury spojení, ale příslušný kód musí být spuštěn po mod_ssl. Moduly jsou v každé fázi zpracování provolávány v opačném pořadí než byly nahrány, tedy CSáček musí být do serveru nahrán před mod_ssl. #### Stronghold Od verze 2.1.3 CSáček funguje i pod Strongholdem. Testováno na verzi Stronghold 2.4.2 pro NetBSD/i386. Zpět ## ISAPI CSáček V rámci vývoje webových stránek Masarykovy univerzity byl financován i vývoj CSáčku pro IIS, tj. ISAPI filtru. ISAPI CSáček je nyní dopracován a od verze 2.1 je k dispozici jako komerční software. ISAPI CSáček překódovává korektně výstup z ASP, CGI, server extensions (včetně FP extensions) a samozřejmě statické stránky, funguje i pri provozu s SSL a je velmi rychlý - podle namátkových testů asi dvakrát rychlejší než `CZFILTER`. Pokud máte zájem ISAPI CSáček vyzkoušet, je k dispozici časově omezená verze, která přestane fungovat přibližně po měsíci. Objednat CSáček lze na samostatné stránce. ### Jak se konfiguruje ISAPI verze Seznam konfiguračních direktiv viz konfigurační direktivy CSáčku. ISAPI CSáček je konfiguruje pomocí záznamu v MS Windows Registry. Jeho větev je `HKEY_LOCAL_MACHINE\Software\CSacek`. Záznam v CSáčkovském klíči Registry platí jako "globální". Je ale také možno nastavit vlastnosti CSáčka pro jednotlivé virtuální servery. Konfigurace pro každý virtuální server je uvedena v podklíči CSáček klíče - jako jméno klíče se použije název virtuálního serveru. Je možno uvést i port, od jména serveru je oddělen dvojtečkou. Pokud je port uveden, konfigurace platí jen při přístupu na tento konkrétní port, pokud ne, platí pro jakýkoli přístup na daný virtuální server. Příklad názvu podklíče: `www.muj.cz` `www.jiny.cz:8000` V konfiguraci virtuálního serveru mohou být uvedeny všechny direktivy stejně jako v globální. Hodnoty nastavení `csacekServers` jsou ale globální a sdílené všemi virtuálními servery - nemá význam mít nastavení různě pro různé servery. Po každé změně konfigurace je nutno přestartovat Web server - jen tak se zajistí, aby CSáček změněný záznam z registry znovu načetl. Zpět ## Konfigurace CSáčka Některé vlastnosti CSáčka lze ovlivnit vhodným nastavením. Pro CGI CSáčka to lze pouze v čase kompilace (možnost run-time konfigurace není pro CGI rozumná). Chování Apache CSáčku a ISAPI CSáčku lze ale poměrně jednoduchým způsobem ovlivnit i později - nastavením v kofiguraci serveru (Apache) nebo nastavením v registry (ISAPI). Zde je popis jednotlivých direktiv: `csacekChangeURL` On nebo Off Nastavuje, jestli se v dokumentu odkazy upravovat tak, aby šly "přes CSáček". Default: On `csacekCompress` On nebo Off Nastavuje, jestli se má použít komprese nebo ne. Default: On `csacekDefaultCharset` Nastavuje defaultní kódování serveru. CSáček bude předpokládat, že stránka je v tomto kódování, pokud si sama neřekne jinak. Textová data od klienta budou převedeny do tohoto kódování před předáním dat ostatním modulům. Default: `iso-8859-2` na Unixu a `windows-1250` na MS Windows `csacekEngine` On nebo Off Zapíná CSáček (a'la Apachovske `RewriteEngine`). Default: On `csacekImplicitWork` On nebo Off Pokud cílové kódování není v URL uvedeno (URL je typu `http://kdesi/cosi/neco.html`, tj. `bez toXXX`), CSáček se pokusí uhádnou klientem podporované kódování a automaticky do něj požadovaný dokument převede. Pokud se vám toto chování nehodí, lze implicitní překódování pomocí této direktivy vypnout. Default: On `csacekServers` Seznam "CSáček kompatibilních" serverů - v předávaných HTML dokumentech se odkazy na tyto servery automaticky upraví tak, aby se zachovalo uživatelem používané kódování a jazyková verze Jednotlivé názvy serverů se píšou navzájem oddělené čárkou. Je možné zadat i port (od jména serveru oddělený dvojtečkou) - pak se budou odkazy měnit jen pokud URL vede na daný port daného serveru. Default: Apache - všechny virtuální servery, ISAPI - servery, které mají vlastní konfiguraci v CSáček větvi v registry Příklad: `www.nekde.cz:900,www.cosi.cz` `csacekTemplateDir` Adresář se šablonami - momentálně pouze šablonou k `whichcode` (soubor `whichcode_template.html`). Default: `/www/csacek` na UN*Xu a `C:/CSacek` na MS Windows. `csacekTestJS` On nebo Off Experimentální vlastnost, v příští verzi může zmizet nebo se změnit. Zapíná heuristiku pro rozpoznávání "čistého" JavaScript dokumentu (default vypnuto). Pokud je dokument typu `text/html`, při zapnutí této direktivy CSáček prohlédne prvních 200 znaků dokumentu nebo první tři neprázdné řádky. Pokud se zde nalezne řetězec `//` nebo `/*` (JavaScript komentář) nebo znak `;` na konci řádku (případné mezery nebo tabelátory mezi znakem `;` a koncem řádku jsou ignorovány), dokument zpracovává jako `text/plain`, tedy HTML tagu (např. odkazy) nejsou přepisovány. Pozor - při neopatrném použití může tato heuristika dávat špatné výsledky. Mohou existovat platné HTML stránky, které splňují výše uvedené kritéria a nejedná se přitom o JavaScript zdrojový kód. Pokud možno tuto direktivu vždy aplikujte jen na omezený podstrom dokumentů a zkontrolujte, že absolutní odkazy a tagů `<A>`, `<FORM>` atd. jsou správně přepisovány při použití explicitního překódování (jako např. `/toASCII/`). CSáček je standardně "zapnutý", pokud ho chcete vypnout, je třeba ho explicitně vypnout pomocí `csacekEngine`. Stále se bude interně z URL odstraňovat CSáčková část (tj. pokud server bude požádán o `http://server/toASCII/dir/doc.html`, převede se požadavek interně na `http://server/dir/doc.html`), CSáček ale s dokumentem poslaným nazpátek klientovi nebude nic dělat. Direktivy, které jsou nadále podporovány v řadě 2.1.*, ale budou zrušeny ve verzi 3.0: csacekBarDef csacekDefaultPartname csacekIgnorePrefix csacekServer (csacekServers bude nadále podporováno) Zpět ## Seznam příkazů Příkazy v CSáčku se uzavírají mezi `<?` a `?>`. `?` je použito proto, že se jedna o speciální SGML "tag", určený pro vkládání příkazů jazyků vložených (embedded) do SGML dokumentu. Kvůli kompatibilitě s SaCzechem je podporováno také `<!--` a `-->`. Příklad použití: `<? SET EXECCMDS=YES ?>` Od verze 3.0 bude podporována pouze (nová) notace `<?csacek příkaz ?>`. Obecně platná pravidla: může být uveden pouze jediný příkaz příkaz včetně parametrů může být na několik řádků ve jméně příkazu nezáleží na velkých/malých písmenech (tj. např. `SET` se považuje za ekvivalentní s `SeT`) u názvů parametrů nezáleží na velkých/malých písmenech parametry příkazu se vyhodnocují obvyklým způsobem zleva doprava, jsou podporováný znaky " a ' s obvyklým HTML významem; zápis `\x` způsobí, že znak `x` nebude chápán jako speciální při zadání vzájemně protikladných parametrů platí poslední uvedený nastavení z příkazu má vždy přednost před defaultním nastavením pokud se příkaz nepozná, v dokumentu se ponechá ### Příkazy: MYCHARSET SET ### ... a popis: V následujícím popisu hranaté závorky označují části, které nemusí (ale mohou) být zadány. U každého příkazu je uvedena jeho syntax, jeden jednoduchý příklad použití, dále pak krátký popis, co daný příkaz dělá a poté případně přehled voleb či parametrů, které můžete příkazu zadat. U některých je uveden ještě odkaz na další, podrobnější příklady užití. `MYCHARSET` Syntax: `MYCHARSET=kódování` Příklad použití: `MYCHARSET=ISO-8859-2` říká CSáčku, že následující text je zapsán v zadaném kódování. může být uvedeno jméno kteréhokoli podporovaného kódování příkaz lze v dokumentu použít i několikrát, vztahuje se na něj omezení `PART`, `DOMAIN` a `CHARSET` `SET` Syntax: `SET volba1=hodnota1 ...` Příklad použití: `SET CHANGEURL=NO` Nastavuje některé vlastnosti zpracování textu. Rozpoznávané parametry mohou být nastaveny na `YES` nebo `NO`. Parametry:
  `CHECKURL` | nastavuje, jestli se má v následujícím textu u HTML značek, používajících URL (`A`, `BASE` atd.), toto URL přepisovat tak, aby vedlo přes CSáček; defaultně zapnuto
  `EXECCMDS` | nastavuje, jestli se v následujícím textu mají provádět CSáček příkazy; i v případě, že je provádění příkazů vypnuto se stále některé provádějí (např. `SET`) - jinak by nebylo možné příznak zase zapnout; defaultně zapnuto
### Zastaralé příkazy Následující příkazy jsou stále podporovány v řadě 2.1.*, ale budou odstraněny ve verzi 3.0: `BAR` `BARDEF` `PART` `DOMAIN` `CHARSET` `csacekServer` `csacekServers` (konfigurační direktiva zůstává) Zpět

This page is part of documentation of C-SaCzech. It has been created and is maintained by Jaromír Doleček, dolecek@sky.cz
$Id: csacek.html,v 1.96 2002/03/10 20:03:31 dolecek Exp $