C-SaCzech CSACEK_VERSION

 

C-SaCzech je zkratka vzniknuvší z C a SaCzech, a znamená C-Satrapa's Czech (tedy Céčkovská Satrapova čeština) Jako jméno se ujalo kratší a výstižné "CSáček".

Jedná se program, který umožňuje změnu kódování WWW dokumentů "on fly" podle přání uživatele. Stránky jsou uloženy v určitém typu kódování (ne nutně jednom) a CSáček je během odesílání uživateli změní tak, aby je klient dokázal správně zobrazit.

Proč verze v jazyce C, když původní sáček skvěle funguje ? Především proto, že verze v Perlu byla na můj vkus trochu pomalá. Moje myšlenka byla, že něco, co bude používat často hodně lidí, má být co nejefektivnější, nejrychlejší a málo náročné na systémové zdroje.
A tak vznikl C-SaCzech 1.0, jako potomek SaCzechu 2.0. Jeho pozdější verze s sebou přinesly mnohá rozšíření, takže není zaručena zpětná kompatibilita nově vytvořených stránek. Staré stránky budou fungovat bez potíží. S novými verzemi SaCzechu se C verze snaží držet krok, což se zatím daří.

CSáček by asi nevznikl bez páně Pavla Satrapy, jehož SaCzech byl předlohou při vytváření tohoto programu. Nikdy by taky nebyl tak dobrý jako je nyní bez podnětných připomínek a pomoci mnohých dalších lidí, z nichž bych chtěl asi nejvíce poděkovat Hynkovi Medovi.

CSáček je možno stáhnout na ftp serveru ftp://ftp.muni.cz/pub/localization/csacek/. CSáček 1.3 je momentálně k dispozici ve verzi pro Unix, ve zdrojové formě. Páně Zdeňka Pokorného port na NT je odvozen z CSáčku 1.23, verze 1.3 bude naportována na NT hned, jak budu mít chvíli (cca 2 dny) času. CSáček 1.23NT naleznete na tomtéž místě jako normální CSáček.

I když byl dán CSáček k téměř volnému použití, přesto platí jisté licenční podmínky. Prosím přečtěte si je dřív než budete CSáček používat.

Dokumentace

• Licence - kdo a jak může CSáček používat
• Proč vznikl ?
• Instalace
  • Přenos na jiný OS než Unix
• Návod k použití
• Příkazy CSáčku
• Historie
• Distribuce CSáčku - ftp archív obsahující distribuci
• Srovnávací testy CSáčku

• Přehled některých dalších stránek zabývajících se češtinou

Výběr kódování:
 

Licence

Upozornění:
Program C-SaCzech je dodáván zcela bez záruk. Autor neručí za jakékoli škody, vzniklé jeho používáním. Zdůrazňuji - autor je zříká VEŠKERÉ ODPOVĚDNOSTI za škody vzniklé přímým či nepřímým používáním CSáčku či kterékoli jeho součásti.

Copyright

All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software
   must display the following acknowledgement:
	This product includes software developed by Jaromir Dolecek, ICS MU 
	and contributors
4. Neither the name of Jaromir Dolecek nor the names of ICS MU
   may be used to endorse or promote products derived from this software
   without specific prior written permission.
5. On page, where users choose their encoding (normally the one
   generated by whichcode script) will be text:
        Coded by C-SaCzech.
   and link to program's home page (http://www.ics.muni.cz/~dolecek/c-saczech/)


THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

1. V dokumentaci a kódu zůstane zachována informace o původním autorovi a autorských právech.
2. Na stránce, nabízející volbu kódování (v původní distribuci generována skriptem whichcode), zůstane zachována informace o tom, že změna kódování je realizována programem C-SaCzech, a odkaz na domácí stránku programu (http://www.ics.muni.cz/~dolecek/c-saczech/).

Rád bych viděl, jak se CSáček šíří, budu tedy rád, pokud byste mi napsali krátkou zprávu na adresu dolecek@ics.muni.cz, jestliže jej budete používat. Budu potěšen ;-).

Zpět  

Proč vznikl ?

WWWdia mě osobně připadá až příliš náročný na instalaci (ani po houževnatém asi 2 hodinovém úsilí se mi ho nepodařilo dostat do použitelné běhající verze) a zbytečně komplexní a složitý. SaCzech se mi od prvního pohledu líbil, ale postupem času mi začalo vadit, že odezva s použitím překódování byla výrazně pomalejší než bez něj. A proto jsem se rozhodl napsat nějakou rychlejší verzi, a protože algoritmus překódovávání asi výrazně zlepšit už nelze, zvolil jsem nižší programovací jazyk - C.

Bylo (a stále je) s CSáčkem mnoho práce, ale záměr je splněn - CSáček funguje a je výrazně čipernější než SaCzech.

C-SaCzech CSACEK_VERSION nabízí

• jednoduché vytváření odkazů - zvládá relativní odkazy
• je možno (narozdíl od WWWdia) používat relativní odkazy na obrázky
• možno používat různé kódy 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 výstup z {cgi|atapi}-skriptů
• lépe využívá systémových zdrojů, což se projeví zejména pokud je WWW server hojně zatížen či navšťevován (provedl jsem pár srovnávacích testů)
  • potřebuje výrazně méně paměti než Perl skript (na mém NetBSD potřebuje perl 5.003 ke spuštení 413k {376k textový segment}, CSáček 30k {24k textový segment}, bez sdílených knihoven)
  • tráví v režimu jádra méně času (ve srovnání se SaCzech)
  • celkový čas běhu je menší
• možnost psaní vícejazyčných verzí dokumentu v jednom souboru
• možnost měnit obsah dokumentu podle domény, odkud se pristupuje
• možnost filtrovat vstup/vystup do/z CSáčku skrz jiné programy
• podporu SSI (shtml dokumenty)
• podpora ochrany přístupu pomocí lokálních konfiguračních souborů (často .htaccess)
• možnost automatického generování lišty s nabídkou kódování
• podstatně jednodušší instalace než WWWdia

C-SaCzech postrádá

• kódovou samoobsluhu (např. WWWdia má)
• jednoduchost a okamžitou konfigurovatelnost skriptu

Budoucnost ...

A co čeká CSáček do budoucna ? Port pro NT by se měl stát přímo součástí CSáčku a bude se vyvíjet zároveň s Unixovou verzí. To samé by bylo vhodné udělat pro OpenVMS, ale bude to asi trochu složitější, protože na žádný OpenVMS systém nemám přístup.
Rád bych také trochu pročistil kód, ještě CSáček zrychlil (jestli to bude možné) a udělal jej trochu intuitivnějším a nynější jednotlivé izolované příkazy sloučil do jazyka podobajícího se C. Také by bylo třeba zahrnout podporu Unicode a snad některých dalších oblíbených kodérů.

Zpět  

Instalace

Distribuce zdrojového kódu programu je uložena v souboru csaczechXXX.tar.gz (kde XXX je označení verze), který můžete získat na URL

ftp://ftp.muni.cz/pub/UNIX/localization/

gunzip < csaczechXX.tar.gz | tar xvf -

tar xvzf csaczechXX.tar.gz

Níže je uveden přehled proměnných a voleb, kterými můžete určit chování budoucího CSáčku. Pokud Vám vyhovuje standardní nastavení nebo jsou pro vás dostatečné popisy přímo v souborech config.h a Makefile, můžete tuto část přeskočit. Proměnné jsou v pořadí,v jakém je najdete v příslušných souborech.

Proměnné ovlivňující chování budoucího C-SaCzechu (nastavuje se v config.h):

FILESEPARATOR

Znak, který chcete použít jako oddělovač jmen souborů v DEFAULTFILE.

Default - ,

DEFAULTFILE

Seznam souborů, které se zobrazí, jestliže je zadán pouze adresář. Nejrozumnější je, pokud je stejný jako seznam jmen za DirectoryIndex v konfiguračním souboru pro httpd. Použije se pouze při volání metodou file, popř. guess.

Default - index.html,welcome.html,Welcome.html,default.htm.

CGIPATH

Cesta k CGI skriptům. Obsahem této proměnné by měl být začátek cesty (část uváděná bezprostředně za jménem serveru) ke konverzním skriptům, která se uvádí v odkazech. Jestliže konverzní skripty uložíte do obecného adresáře, obsahujícího ostatní CGI skripty a budete se na ně odkazovat pomocí URL

http://www.kdesi.cz/cgi-bin/toASCII

můžete ponechat implicitní hodnotu "/cgi-bin". Je třeba uvést celou cestu, bez závěrečného lomítka. Tato hodota se používá při metodě guess k určení, zda požadovaný dokument je cgi skipt.

Default - /cgi-bin

CGISUFFIX

Přípona CGI skirptů. Pokud váš server vyžaduje, aby CGI skripty byly vyznačovány určitou konkrétní příponou (nejčastěji .cgi), uveďte ji jako hodnotu této proměnné. Je-li server dostatečně inteligentní na to, aby poznal CGI skript podle cesty, doporučuji ponechat jako hodnotu proměnné prázdný řetězec.

Default - nenastaveno.

DEFSOURCE

Implicitní kódování zdrojových textů stránek. Zde uveďte kódování, ve kterém bude pravděpodobně vytvořena většina Vašich stránek. Jestliže si stránka nepředepíše zdrojový kód, bude jako výchozí pro její překódování použit tento kód. Platné názvy kódů zjistíte prohlédnutím souboru nazvy nebo (lépe) cstools.h. Nedělá se rozdíl mezi velkými a malými písmeny.

Default - ISO-8859-2.

GETMETHOD

Způsob, kterým má C-SaCzech získávat kódované texty. Můžete si vybrat jednu z následujících alternativ (musí být vypsáno malými písmeny):

file

Soubory budou vyzvedávány přímo ze systému souborů počítače. Tento způsob je efektivní a rychlý, ale umožňuje kódovat jen texty, které jsou přítomny v podobě souborů. Nelze např. kódovat výstupy z CGI skriptů.

http

V tomto režimu práce C-SaCzech získává kódované dokumenty od svého serveru prostřednictvím HTTP protokolu. Tedy zahraje si na WWW klienta, odstraní své vlastní jméno z dotazu, který mu byl položen, a položí serveru tento modifikovaný dotaz. Data, která získá jako odpověď, posoudí a buď překóduje (jestliže se jedná o text, přesněji MIME typ text/html nebo text/plain) nebo propustí beze změny.

Tento způsob je podstatně méně efektivní (obsloužení každého dotazu vyvolává jeden dotaz navíc), umožňuje však překódovat vše, co je na serveru k dispozici - včetně výstupů z CGI skriptů.

Zvolíte-li tuto variantu, nemá žádný význam nastavení proměnné DEFAULTFILE a příznaků TIMESERVICES a IFMODIFIEDSINCE.

guess

C-SaCzech se pokusí automaticky určit pro každý dotaz, kterou z výše uvedených metod má použít. Využívá k tomu hodnotu proměnné CGIPATH a CGISUFFIX.Jestliže je začátek cesty ke kódované informaci (část URL, uvedená za voláním skriptu) shodný s CGIPATH nebo obsahuje CGISUFFIX, použíje pro získání dokumentu metoda http. http se použije i tehdy, jestliže se žádá o dokument .shtml nebo v některém adresáři obsaženém v proměnné prostředí PATH_TRANSLATED se nachází soubor s názvem uvedeným u SECURE. V opačném případě jej vyzvedne přímo ze systému souborů.

Metoda guess se tedy snaží o rozumný kompromis mezi předchozími alternativami.

Default - guess.

TIMESERVICES

Jedná se o první z příznaků. Jestliže je definována, znamená to, že se lze spolehnout výsledky funkce stat programovacího jazyka C, kterou C-SaCzech využívá pro získání informací o velikosti a době vzniku souboru.

Default - nastaveno.

IFMODIFIEDSINCE

Má skript reagovat na hlavičku If-Modified-Since? Pokud vámi používaný server nepředává CGI skriptům informace z HTTP hlaviček dotazu (v proměnných prostředí HTTP_hlavička), nedostává C-SaCzech potřebné informace. V takovém případě volbu vypněte.

Default - nastaveno.

SECURE

Pokud je definováno, otestuje se, zda v některém adresáři z PATH_TRANSLATED není soubor omezující přístup a sloužící většinou k autorizaci přístupu. Jméno souboru, který se takto používá záleží na tom, jaký httpd funguje na Vašem serveru, případné dotazy na to, jaký to je, směrujte na Vašeho systémového administrátora.

Default - ".htaccess"

DECODEQUERY

Definujte tuto proměnnou, pokud chcete, aby C-SaCzech překódovával i parametr z příkazové řádky.

Default - nenastaveno.

ADDBAR

Pokud je nastavena tato proměnná, C-SaCzech bude reagovat na text <!--BAR--> (popř.<!--BAR E-->) tak, že v daném místě vypíše text, umožňující změnu kódování dokumentu; podle toho, která varianta je použita, doplní buď českou hlavičku a závěr (obsah proměnných HEADBARTEX a TAILBARTEXT), nebo anglický (EHEADBARTEX a ETAILBARTEXT).

Default - nastaveno.

ALLWAYSADDBAR

Pokud je tato proměnná nastavena, C-SaCzech vypíše lištu vždy; pokud text neobsahuje řetězec <!--BAR-->, vypíše ji na konci dokumentu. Samozřejmě pouze tehdy, pokud daný dokument překódovává (takže obrázky jsou v pohodě) nebo se nejedná pouze o chybové hlášení.

Default - nenastaveno.

LONGNAMEBAR

Pokud je nastavena, v nabídce kódování se zobrazí celá jména kódů a ne pouze trojpísmenné zkratky.

Default - nenastaveno.

HEADBARTEXT, EHEADBARTEXT

Text, který se vypíše před lištu s nabídkou překódování. HEADBARTEXT se vypíše v české verzi, EHEADBARTEXT v anglické.

Default - viz defaultni config.h.

TAILBARTEXT, ETAILBARTEXT

Text, který se vypíše za lištu s nabídkou překódování. Standartně je to "<HR>", tedy vodorovná linka. Opět TAILBARTEXT je pro českou lištu, ETAILBARTEXT pro anglickou.

Default - "<HR>".

ADDWHICHCODE

Pokud je nastavena, v automaticky generované nabídce kódování se zobrazí i obsah proměnné BARWHICHCODENAME, který bude odkazem na volbu pomocí standartního whichcode. Má smysl pouze tehdy, pokud je nastaveno ADDBAR .

Default - nastaveno.

BARWHICHCODENAME

Text, který se vypíše do lišty.

Default - "whichcode".

MULTIPART

Nastavením této proměnné bude zkompilovaný C-SaCzech podporovat více různých dokumenů v jednom dokumentu; jak to funguje se můžete podívat na tento příklad. C-SaCzech bude reagovat na <--PART XXXXX--> odpovídajícím tak, že podle názvu zjistí, zda má danou část vypsat (pokud byl spuštěn jako např. toASCII.eng.cgi, bude vypisovat části <--PART eng-->).

Default - nastaveno.

PARSE_DOCUMENT

Podpora dokumentů používajících SSI (příkazy <!--#exec, <!--#include). CSáček také provede odpovídající příkazy v případě, že to httpd neumí nebo není nastaven tak, aby uměl. Pozor, toto nastavení může obejít systěmovou konfiguraci, takže pokud je nějaký důvod proč to není na Vašem serveru tak jistě tytéž důvody hovoří pro to, aby se SSI zakázaly i v CSáčku. Pozor - jestliže WWW server SSI umí a v CSáčku je zakážete, většinou se stejně neprovedou.
Pokud chcete povolit jen některý ze dvou podporovaných příkazů, můžete tak udělat správným (ne)nastavenim následujících dvou příznaků.

Default - nastaveno.

ENABLEEXEC

Viz PARSE_DOCUMENT. Povolí příkaz "<!--#exec". CSáček CSACEK_VERSION umí provést jen exec cmd.

Default - nastaveno.

ENABLEINCLUDE

Viz PARSE_DOCUMENT. Povolí příkaz "<!--#include". CSáček CSACEK_VERSION umí provést jen include file.

Default - nastaveno.

USECHARSET

Pokud definováno, CSáček připíše kódovaným dokumentům do hlavičky k údaji Content-type kromě správného typy dokumentu i nepovinný parametr "charset"; některé prohlížeče, které umí MIME se pak podle tohoto parametru dovedou zařídit a zobrazit ve správném kódování.

Default - nastaveno.

STATUSHACK

Některé httpd (např. NCSA httpd, Apache httpd) mají problémy s parsováním hlavičky dokumentu, jestliže se v části Status: uvede i typ serveru (tzn. předává se i HTTP/1.0). Pokud definujete tuto proměnnou, status se předává tak, aby první uvedený text za "Status:" bylo číslo.
Tuto proměnnou se doporučuje definovat.

Default - nastaveno.

CSACEKFILTERS

Umožní používat "CSáček filtry" k filtrování vstupu/výstupu do/z CSáčku. Tzv. "CSáček filtr" může být kterýkoli program který čte ze standartního vstupu a zapisuje na standartní výstup. Bližší informace u popisu příkazu.

Default - nenastaveno.

NPH

Pouze a jenom k testovacím účelům, nedoporučuji definovat dokud opravdu nevíte co děláte. Pokud definováno, CSáček se chová jako by se jeho hlavičky už neměl httpd parsovat -> Status: je bez klíčového slova Status:, přeskakuje se úvodní "nph-" ve SCRIPT_NAME.

Default - nenastaveno.

LOCALHOSTHACK

Pokud je definováno, CSáček se místo se serverem uvedeným v proměnné prostředí SERVER_NAME kontaktuje s počítačem na kterém byl spuštěn. V drtivé většině případů se jedná o tentýž stroj, takže je to korektní. Spojení se ale takto naváže rychleji a také komunikace by měla být rychlejší (nebylo testováno). CSáček se pokusí navázat spojení na IP adresu 127.0.0.1 což je většinou správné spojení na počítač na kterém jede (aspoň na Unixu). Definováním tohoto příznaku většinou nic neztratíte (když nepomůže aspoň neuškodí ;-).

Default - nastaveno.

CSACEK_REPORT

Pokud nastavíte tento příznak, CSáček vypíše svoji konfiguraci, pokud mu jako query podstrčíte parametr csacek_report nebo csacek_info. Celkem užitečné (aspoň se dá kdykoliv zjistit, co momentální verze umí a co ne).

Default - nastaveno.

CSACEK_BANNER

Pokud je definováno, CSáček na začátek dokumentů, které kóduje, napíše krátké info, že to udělal. Pokud vám to vyloženě vadí, můžete to samozřejmě zakázat.

Default - nastaveno.

RESTRICTDOMAINS

Od verze 1.3_BETA je možno měnit obsah dokumentu podle domény či stroje, odkud vzdálený uživatel přistupuje. Jedná se o příkaz DOMAIN, používá se podobným způsobem jako příkaz PART, adresu je možno zadat v doménovém tvaru i jako čisté IP.

Default - nastaveno.

CSACEK_HELP

Jestliže je definováno a dáte CSáčku parametr ?csacek_help, CSáček vygeneruje krátkou stránku s popisem příkazů, které podporuje.

Default - nastaveno.

CSACEK_HOMEPAGE

Jestliže je definováno a dáte CSáčku parametr ?csacek_homepage, CSáček přesměruje klienta na domácí stránku programu.

Default - nastaveno.

Proměnné používané pouze v čase kompilace (soubor Makefile):

CC

Tato proměnná obsahuje jméno kompilátoru, který bude použit pro vytvoření spustitelného C-SaCzechu. cc je standartní a programy jím zkompilované by měly běžet bez problémů. gcc je lepší, ale některé WWW servery odmítají spustit jím zkompilované programy. Na systémech BSD/OS se používá cc nebo shlicc, pokud chcete aby program používal sdílené knihovny.

Nastaveno na: cc

CFLAGS

Zde jsou uvedeny parametry předané kompilátoru uvedenému v ${CC}. Jedna se většinou o volbu optimalizace, popř. i jiné důležité parametry (jako třeba -fno-strength-reduce pokud používáte pro kompilaci nepatchnutý gcc 2.7.2 a používáte -O2).

LFLAGS

zde jsou uvedeny knihovny, které se musí nalinkovat, aby překlad proběhl úspěšně. Na SunOS a SCO Unix je třeba přidat -lsocket -lnsl, na UnixWare (a možná i jinde) ještě navíc -lresolv.

OS_TYPE

Typ operačního systému, na kterém CSáček budete chtít kompilovat. Prozatím jediná platná hodnota je unix.

Nastaveno na: unix

LN

Příkaz, kterým se na vašem souboru udělá symbolický (měkký) link.

SHELL

Jméno shellu, který se má použít ve skriptu whichcode. Má cenu pouze pro Unix (pod NT pokud vím nelze přímo ve skriptu nastavit, pod čím se má spustit). Podporované shelly (respektive ty, které vím, že fungují) jsou: sh, ksh, bash, ash, zsh, pdksh, csh nefunguje, není a nebude podporován.

Nastaveno na: /bin/sh

STRIP

Zkompilovaný binární soubor obsahuje některé informace, které jsou poté většinou zbytečné (tabulku symbolů atd. používají se při ladění programu). Pokud tedy CSáček budujete pro normální používání, nechte jako obsah strip, jinak echo. Ušetříte títo způsobem asi 3k na disku ;-)

Nastaveno na: strip

CGIPATH

Pravdépodobně budete chtít nastavit stejnou hodnotu jako v config.h. V souboru Makefile se užívá pro určení hodnory proměnné CGIPATH ve skriptech whichcode, whichcode.eng.

SUFFIX

Uveďte, pokud chcete, aby generované soubory měly nějakou příponu (např. .cgi). Není závislá na hodnotě CGISUFFIX, nastavené v config.h.

COMPILEDIR

Kam se mají uložit zkompilované binárky, soubory obsahující symbolické linky a soubory whichcode. Může být i adresář, kde máte ostatní CGI skripty, ušetříte si takl jeden krok při instalaci.

CSACEK_CODES

Seznam kódů, mezi kterými CSáček umí převádět. Když se v závěrečné fázi kompilace budou vytváňet symbolické odkazy na soubor, který bude oním "centrálním" převodníkem, vytvoří se pouze odkazy se jmény z tohoto seznamu. Ve většině případů asi není třeba přenastavit.

PARTLIST

Seznam názvů částí (viz příkaz PART), které chcete na vašem systému používat.

Nastaveno na: eng.

CZ_WHICHCODE, ENG_WHICHCODE, WHICHCODE_DIR

WHICHCODE_DIR obsahuje adresář, ve kterém jsou defaultní základy ke skriptům whichcode a whichcode.eng. Podívejte se tam a podle toho, který vám vyhovuje nastavte příslušně i proměnné CZ_WHICHCODE a ENG_WHICHCODE.

... a instalace pokračuje

make

Pokud si přejete, můžete nyní ještě upravit komentáře ve vytvořeném $COMPILEDIR/whichcode.

A nyní už jen stačí přesunout soubory z podadresáře compile do adresáře s ostatními CGI skripty tak, aby je httpd mohl spustit a "HURÁ", CSáček by měl být připraven k používání.

  Zpět

Přenos do jiného operačního systému

Dohromady podtrženo a sečteno: je to jistý oříšek, ale při troše námahy a možnosti přístupu na Unixovou i cílovou platformu řešitelný.

  Zpět

Návod k použití

Obsah

• Základy - URL stránky
• Zachování kódu při odkazech
• Nekódovat obrázky!
• Změna výchozího kódu
• Lišta s nabídkou kódování
• Vícejazyčné dokumenty
• Podpora autorizaci přístupu
  • Překódovávání chráněných (veřejně nepřístupných) souborů
• Podpora SSI a shtml
• Napojení CSáčku na jiné programy
• Zjištění zakompilovaných defaultů a on-line help

Základy - URL stránky

http://www.kdesi.cz/cesta/stranka.html

http://www.kdesi.cz/cgi-bin/toXXXX/cesta/stranka.html

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 použít skript whichcode a URL

http://www.kdesi.cz/cgi-bin/whichcode/cesta/stranka.html

Zachování kódu při odkazech

<A HREF="kapitola1.html">První kapitola</A>

  Trik - můžete použít v dokumentu značku <BASE> na rozskokové stránce (ta, na kterou čtenáři většinou dojdou bez prekódování). Všechna relativní URL vztažena k lokátoru, definovanému touto značkou, nikoli k URL, pod kterým klient získal stránku.

Příklad:
stránka http://kdesi/~ja/moje.html může obsahovat značku <BASE HREF=http://kdesi/cgi-bin/to__CHARSET__/~ja/moje.html>. Pokud čtenář použije některý relativní link, je přinucen vybrat si kódování a dál už se mu stránky zobrazují v tom "jeho".

Absolutní odkazy je třeba řešit jinak. Tady používá CSáček metodu podobnou programu WWWdia. Do textu můžete na kterékoli místo (včetně cest) vložit řetězec

__CHARSET__

<A HREF="http://www.jinde.cz/cgi-bin/to__CHARSET__/jinacesta/str.html">odkaz</A>

<A HREF="http://www.saczechserver.cz/cgi-bin/toKEYBCS2/jinacesta/str.html">odkaz</A>

Jelikož jsou názvy kódů shodné s programem WWWdia, mohou se na sebe navzájem korektně odkazovat stránky, jejichž servery používají různé implementace češtiny. Absolutní URL, uvedené výše, lze použít i na stránce, která je překódovávána programem WWWdia. Potřebujete-li naopak skočit ze stránky kódované pomocí C-SaCzechu nebo SaCzechu na stránku v pomocí WWWdia, použijte pro tento odkaz URL

<A HREF="http://www.diaserver.cz/cgi-bin/charset/jestecesta/str.html?charset=__CHARSET__">odkaz</A>

Nekódovat obrázky!

Díky tomuto mechanismu můžete na své stránky vkládat relativní odkazy na obrázky, zvuky a další druhy dat, kterým by překódování rozhodně neprospělo.

Jestliže se na stránce vyskytne značka

<IMG SRC="obraz.gif">

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.

K vyznačení původního kódu dokumentu se používá HTML komentář v přesně definovaném tvaru

<!--MYCHARSET=kód-->

Například <!--MYCHARSET=CP1250-->. Počínaje řádkem, obsahujícím tento komentář (doporučuji jej uvést na samostatném řádku na začátku dokumentu), bude za výchozí kód dokumentu považován kód CP1250.

Pro milovníky patologických případů:

• V jednom komentáři nesmí být nic jiného než specifikace MYCHARSET=kód.
• Použijete-li několik komentářů, obsahujících MYCHARSET, použije se první z nich
• Účinnost MYCHARSET začíná řádkem, na kterém se vyskytuje.

Lišta s nabídkou kódování

<--BAR-->

Pokud chcete docílit speciálního tvaru lišty, máte dvě možnosti. Jedna je zadat parametry přímo v příkazu BAR a druhá použít příkazu BARDEF, který je identický s BAR až na to, že nezpůsobí vypsání lišty. V obou příkazech jsou zadané parametry platné i pro všechny následující příkazy BAR. S výhodou lze takto např. předefinovat tvar lišty a nechat C-SaCzech vypsat lištu na konci dokumentu (k použití příkazu BAR viz. příklad).

Vícejazyčné dokumenty

Jak se to používá ? Části označíme tak, že na začátek dáme speciální příkaz, podle kterého C-SaCzech pozná, že zde začíná nová část. Např.

<--PART ENG-->

Je rezervováno jedno jméno, a to ALL. Část pojmenovaná jako ALL bude vypsána vždy, stejně jako část dokumentu do prvního výskytu příkazu PART.

Je třeba zajitit, aby se k dokumentům, které jsou takto napsány, nedostal uživatel, aniž by přešel přes CSáček. Protože bez překódování může být onen text poněkud nečitelný ...

Syntax je dále rozebírána v seznamu příkazů

Podpora autorizaci přístupu

Potenciální problémy s překódováváním chráněných souborů jsou diskutovány níže.

Překódovávání chráněných (veřejně nepřístupných) souborů

Podpora SSI a shtml

Napojení CSáčku na jiné programy

• buď a) spustí zadaný program tak, aby nejprve on četl dokument, přetvořil ho podle svých představ a svůj výsledek předával CSáčku,
• nebo b) napojí spuštěný program na svůj výstup, takže co udělá CSáček ještě dále zpracuje jiný program

Zjištění zakompilovaných defaultů a on-line help

Zpět

Seznam příkazů

<!--BAR E LONG-->

• příkazy mohou mít víc parametrů, na pořadí nezáleží, v názvech příkazů nezáleží na velkých/malých písmenech
• jsou-li uvedeny vzájemně protikladné volby, platí poslední uvedená
• platnost příkazu začíná na řádku následujícím za řádkem, na kterém je uveden
• na jednom řádku se rozpozná maximálně jeden příkaz
• volby u příkazu mají přednost před standartním nastavením
• pokud je na řádku nějaký příkaz, neopisuje se na výstup

Seznam:

• MYCHARSET
• BAR, BARDEF
• PART
• DOMAIN
• NOCODE
• CODE
• #exec
• #include
• #csacekfilter

... a popis:

MYCHARSET

Syntax: <!--MYCHARSET=kód-->

Příklad použití: <!--MYCHARSET=ISO-8859-2-->

• říká CSáčku, že následující text je zapsán v kódování kód. Kódování můžete v dokumentu měnit bez omezení.
• Jako názvy kódů lze použít ISO-8859-1, ISO-8859-2, CP1250, KEYBCS2, CP852, KOI8-CS, MAC. Případně je možno použít některý z aliasů, úplný seznam je k nalezení v souboru cstools.c, který je součástí distribuce.

BAR, BARDEF

Syntax: <!--BAR[DEF] [parametry]-->

Příklad použití: <!--BAR SHORT NOWHICH SEP=" o "-->

Příkaz BAR slouží k automatickému vypsání lišty s nabídkou kódování. V lišté se objeví seznam kódů, které CSáček zvládá a každý z nich je odkaz na aktuální stránku, převedenou do příslušného kódu. Parametry nemusíte uvést, BAR bez parametrů vypíše lištu v takovém tvaru, jak je právě nastaveno.

BARDEF má stejné volby a parametry jako BAR, s tím rozdílem, že lištu nevypíše, pouze nastaví vnitřní proměnné CSáčku pro pozdější použití na stránce.

Význam jednotlivých parametrů:

• ALWAYS - řekne CSáčku, že na konci dokumentu má vypsat lištu s nabídkou překódování
• NOBAR - lištu na konci dokumentu nevypíše automaticky
• WHICH, WHICHCODE - připíš do lišty i odkaz na výběr kódování pomocí whichcode
• NOWHICH, NOWHICHCODE - odkaz na whichcode do lišty nedávej
• LONG - chci používat dlouhá jména typů kódů
• SHORT - chci používat trojpísmenné zkratky
• E - anglická verze lišty
• CZ - česká verze lišty
• SEP - oddělovač názvů kódů v liště; používá se ve tvaru SEP="oddělovač"; standartně pomlčka pro LONG a mezera pro SHORT
• NOTITLE - nebude vypsána hlavička (HEADBARTEXT)
• NOBACK - nebude vypsán závěr (obsah TAILBARTEXT)
• DEFAULT - nastavení parametrů lišty do tvaru, který byl definován při instalaci jako standardní; zrušení veškerých změn provedených předcházejícími příkazy BAR nebo BARDEF

Zde je několik dalších příkladů, pokud se už tento dokument filtruje přes CSáček, uvidíte také jak ona generovaná lišta vypadá.

PART

Syntax: <!--PART [jméno_části1 jméno_části2 ...]-->

Příklad použití: <!--PART ENG-->

Následující část textu do výskytu dalšího příkazu PART je předána pouze pokud některé jméno části odpovídá příponě CGI skriptu, kterým se dokument filtruje; například pokud je odkaz ve tvaru: http://server/cgi-bin/toXXX.eng/cosi, předá se vše v dokumentu /cosi mezi <!--PART ENG--> a dalším příkazem PART. Kromě částí uzavřené mezi příkazy PART s odpovídajícím parametrem se také předá vše do prvního výskytu příkazu PART. Pokud jméno části není uvedeno, text za <!--PART--> se předá na výstup pouze pokud u filtrujícího CGI skriptu nebyla uvedena přípona, tzn. odkaz vypadal nějak takto: http://server/cgi-bin/toXXX/cosi. Ve jméně části nezáleží na velkých/malých písmenech (MoJe se vyhodnotí jako ekvivalentní části moje).

Význam jednotlivých parametrů:

• ALL - tato část bude vypsána vždy

Zde je uveden malý příklad; příklad bude funkční pouze pokud již máte nainstalovaný CSáček v angločeské verzi nebo si prohlížíte domácí stránku.

DOMAIN

Syntax: <!--DOMAIN označení_domény_1 [označení_domény2 ...]-->

Příklad použití: <!--DOMAIN ics.muni.cz 147.251-->

Syntaxe je podobná jako u PART. Části mezi jednotlivými příkazy DOMAIN se vypíší pouze tehdy, když vzdálený uživatel přistupuje z některé ze zadaných domén. V uvedeném příkladě tehdy, pokud vzdálený uživatel přistupuje ze stroje v doméně ics.muni.cz nebo s IP adresou začínající na 147.251 (.muni.cz).

NOCODE

Syntax: <!--NOCODE-->

Příklad použití: <!--NOCODE-->

Od řádku na kterém byl tento příkaz se dokument nebude překódovávat; využití například v dokumentech v čistém ASCII (např. anglické) ke zrychlení překladu nebo v částech, které nechcete překódovávat z jakéhokoli jiného důvodu. Příkazy PART a DOMAIN se v takto nekódovaných částech stále rozeznávají.

CODE

Syntax: <!--CODE-->

Příklad použití: <!--CODE-->

Od výskytu tohoto příkazu se dokument bude opět kódovat; inverzní volba s NOCODE.

#exec

Syntax: <!--#exec cmd="prog [parametry]"-->

Příklad použití: <!--#exec cmd="moje.cgi -v -n 34"-->

standartní příkaz SSI; Csáček z čistě praktických důvodů nepodporuje parametr cgi= (vyvolalo by to další dotaz na WWW server -> zbytečná zátěž navíc).
Vloží do dokumentu výstup z programu "prog" spuštěného s parametry "parametry". "prog" nesmí být absolutní cesta a nesmí obsahovat část ../. Na tento příkaz je třeba dávat pozor, umožňuje uživatelům spouštět programy pod identifikací uživatele stejnou jako WWW server, to mimo jiné znamená, že takto spuštěný program má přístup všude, kam má přístup lokální WWW server.

#include

Syntax: <!--#include file="soubor"-->

Příklad použití: <!--#include file="vsuvka.txt"-->

standartní příkaz SSI; CSáček nepodporuje parametr virtual="XX" z podobných důvodů jako nepodporuje cgi= u #exec.
Vloží do dokumentu jiný dokument. soubor opět nesmí být absolutní cesta ani nesmí obsahovat ../. Musí se jednat o exitující soubor (pokud je to program, vloží se jeho text, nespustí se).

#csacekfilter

Syntax: <!--#csacekfilter cmd="prog [parametry]" [align=after|before]-->

Příklad použití:
  <!--#csacekfilter cmd="cgi/muj.cgi -f -o ghost" align=before-->

CSáčekfiltrem může být kterýkoli program, který čte ze standardního vstupu a píše na standardní výstup. Dělá to, že filtruje buď vstup nebo výstup do/z CSáčku, viz také podrobnější popis.

Tento příkaz podle hodnoty parametru align nainstaluje prog jako csáčekfiltr buď před (align=before) a nebo za (align=after) CSáček. Pokud volitelný parametr nepoužijete, je to jako byste dali align=before. prog opět nesmí být absolutní cesta ani nesmí obsahovat ../.
Nainstalování filtru před CSáček je dvakrát náročnější na systémové zdroje než nainstalování za, výhledově se bude měnit syntax volání a pravděpodobně bude omezen počet filtrů před CSáčkem na jeden.

Zpět

Historie

Verze označené X.YZ a X.Y_*{ALPHA|BETA|BETAZ} jsou vývojové nestabilní verze. Doporučuji nepoužívat, leda v případě krajní nouze ;-)

Vývoj

verze 1.3 (srpen-listopad 1996)

• podpora SSI a shtml
• možnost více defaultních souborů (tzn. souborů, které se poskytnou pokud se zadá jako požadovaný dokument jméno adresáře)
• u kódovaných dokumentů předáván parametr "charset" u Content-type
• podpora autorizace přístupu
• zavedení CSáček filtrů
• optimalizovány nároky na paměť - na mnoha místech odstraněny statické buffery, nahrazeny pointry a dynamickou alokací
• animované GIFy zůstávají animované i po dokončení první smyčky
• zjednodušena struktura funkcí, opraveno mnoho drobných chyb, nejdůležitější asi správný přenos obrázků, předávání správného statutu, fungující podpora metody POST a PUT, zpracování hlavičky If-Modified-Since, uděláno více "blbuvzdorné", všude kde se může vyskytnout chyba je detekována a ohlášena, a mnoho dalšího
• možnost zjištění zakompilované konfigurace CSáčku (?csacek_report)
• on-line help (?csacek_help)

verze 1.23 (začátek června 1996) - dost chybový, doporučuji když tak jen vybrat opravenou verzi cstools.h

• podpora skriptů volaných metodou POST
• lépe zachovává HTTP hlavičky
• opraveno chybné překódovávání některých znaků
• opraven whichcode.sl

verze 1.22 (konec května 1996)

• možnost nastavení (téměř) jakéhokoli tvaru automaticky generované lišty s nabídkou kódování přímo v dokumentu
• podpora vícejazyčných dokumentů - možnost mít v jednom dokumentu víc různých částí a dynamicky vybírat, které zobrazit

verze 1.21 (konec května 1996)

• součástí automaticky generované lišty s nabídkou kódování může být i možnost přepnout kódování pomocí původního whichcode.
• opraveno špatné používání metody FILE (koliduje s definicí FILE ve stdio.h); názvy metod jsou nyní opět malými písmeny

verze 1.2 (konec května 1996)

• automatické vložení lišty s nabídkou kódování (podrobnosti viz Instalace)
• kódovací tabulky rozšířeny o většinu ostatních znaků s diakritikou (i např. a se stříškou apod.)
• opraven whichcode.src, aby vytvořený whichcode byl zpracovatelný i bashem; podporované shelly viz Instalace.

verze 1.1 (květen 1996)

• opraveno špatné nahrazování řetězce __CHARSET__ při metodě http
• kódovací tabulky rozšířeny o slovenské znaky
• chybové hlášky jsou "sytémovější" - v hlavičce vrací (po vzoru SaCzechu 2.1) i Status s platným kódem.
• __CHARSET__ rozpoznáván i v HTML hlavičkách při metodě http (umožňuje zachování kódu i v obrázcích s klikou)
• lze překódovat i parametry, zadané programu (obsah proměnné QUERY_STRING)
• zdokonaleno rozhodování, která metoda se má použít při guess tak, že metoda http se použije i tehdy, když požadované URL obsahuje CGISUFFIX.

verze 1.0 (květen 1996)

• možnost získávat kódované dokumenty prostřednictvím HTTP
• podpora HTTP hlaviček Last-Modified, Content-Size a If-Modified-Since při zpracování souborů
• možnost opatřit konverzní sadu příponou (např. .cgi) pokud to systém vyžaduje
• při metodě HTTP nebo GUESS je volanému skriptu předáván i dotaz (QUERY_STRING)
• korektní chování při chybně zadaném URL (neexistující soubor)
• je možno používat více jmen kódů (aliasy);
• součástí distribuce je which.src s příklady kódů