C-SaCzech 1.3.1

 

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/WWW/csacek/.

Ve Zpravodaji ÚVT vyšlo krátké povídání o tom, co CSáček 1.3 umí a jak se to používá.

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
• Chyby CSáčku - neboť chybám se bohužel nevyhne nic ;-(

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

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

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, 
	Institute of Computer Science, Masaryk University, Brno
	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.

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 1.3.1 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 i dynamicky vytvářené stránky (např. výsledky různých skriptů), přičemž zajišťuje správné předání parametrů (podpora metody GET i POST)
• menší spotřebu paměti než Perl skript, přitom rychlejší a stejně kvalitní překódování; oceníte zejména na hodně navštěvovaných WWW serverech
• možnost psaní vícejazyčných verzí dokumentu v jednom souboru
• možnost měnit obsah dokumentu podle domény, odkud se pristupuje
• podpora ochrany přístupu do podadresářů WWW serveru
• automatické generování lišty s nabídkou kódování
• tak user friendly instalaci, jak je to jen možné

C-SaCzech postrádá

• kódovou samoobsluhu
• jednoduchost a okamžitou konfigurovatelnost skriptu - kód je místy dost "škaredý" a nepřehledný

Budoucnost ...

A co čeká CSáček do budoucna ? Je nyní zkompilovatelný "out of box" pro Unix i NT, hodilo by se něco takového udělat i pro OpenVMS port.
Dále je třeba silně pročistit kód, hodila by se podpora Unicode, možná také emulace některých jiných oblíbených kodérů. A pokud se naskytne něco dalšího, co se mi bude zdát užitečné, bude umět snad i něco dalšího.

Zpět  

Instalace

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

ftp://ftp.muni.cz/pub/localization/WWW/csacek/

gunzip < csaczechXX.tar.gz | tar xvf -

tar xvzf csaczechXX.tar.gz

Je třeba nastavit potřebné proměnné tak, aby vše odpovídalo vašemu systému a záměrům. Některé proměnné (např.SHELL) v NT Makefajlu nejsou, protože jsou silně unixově orientované a většinou slouží pro generování skriptu whichcode.

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 pohodlně 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):

SEPARATOR

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,index.cgi,index.htm,welcome.html,Welcome.html,default.htm".

HTTP_SUFFIXES

Jestliže přijde požadavek o překódování dokumentu s příponou uvedenou v tomto seznamu, dokument se nevyzvedává z filesystému, ale použije se metoda http.

Default - ".shtml,.phtml,.idc,.asp,.pl".

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.

Metoda kódování

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. Použije se metoda http, jestliže je začátek cesty ke kódované informaci (část URL, uvedená za voláním skriptu) shodný s CGIPATH, obsahuje CGISUFFIX, dokument má jednu z přípon uvedených v HTTP_SUFFIXES 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 v 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 . Specifický pro Unix. Na NT doporučuji nedefinovat (skript whichcode zde není použitelný).

Default - nastaveno.

BARWHICHCODENAME

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

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-->).
Dále lze měnit obsah dokumentu podle domény či IP adresy stroje, odkud vzdálený uživatel přistupuje. Sytax viz DOMAIN, používá se podobným způsobem jako PART, adresu je možno zadat v doménovém tvaru i jako čisté IP. Jako "doménu" lze zapsat samozřejmě zapsat i plné jméno stroje.

Default - nastaveno.

RESTRICTDOMAINS

Od 1.3.1 sloučeno dohromady s 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

CSáček filtry nadále (od verze 1.3.1) nejsou podporovány.

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 speciální adresa, která se používá na spojení se stejným počítačem jako proces běží. 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.

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.

REDIRECT_IF_URL_IS_DIR

Pokud bylo zadáno URL ukazující na adresář, je vhodné (kvůli následným reltivním odkazům), aby končilo na /. Pokud to tak není, CSáček přesměruje klienta na správné URL končící na lomítko. Vyzkoušeno a funguje (zdá se) bez problémů. Celkem asi neexistuje důvod proč to zakázat, ale pro jistotu je ta možnost.

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. Specifický pro Unix.

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). Specifický pro Unix.

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. Specifický pro Unix.

LN

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

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. Specifický pro Unix.

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 ;-) Specifický pro Unix.

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. Specifický pro Unix.

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. Pro NT je vhodné zvolit .cgi nebo .exe, nastavení pro Unix záleží na místní instalaci.

COMPILEDIR

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

Nastaveno na: ./compile.

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. Specifický pro Unix.

... a instalace pokračuje

make

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

A nyní už jen stačí přesunout soubory z podadresáře $COMPILEDIR 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

No a to už se blížím k závěru. Moje streamové funkcičky kupodivu fungovaly. Odlađoval jsem je radší u sebe na NetBSD, protože si nemůžu pomoct, ale dělání čehokoli na NT mi připadá jako škrábání pravou nohou za levým uchem. Možná to vyhovuje někomu, kdo neví co chce udělat, ale nesnáším, když vím co chci a systém mi nedovolí to udělat jednoduše. Tfuj.
Při závěrečném dolađování jsem došel na zajímavou perličku. Fce stat() se chová poněkud zvláštně - systém sice dokáže stat()nout cesta\adresar, ale nedokáže cesta\adresar\. Takže jsem si pro NT naimplementoval malý wrapper, jménem xstat(), který před voláním stat() odstraní závěrečné backslashe.

Veškeré OS dependant věci jsou v compat.c a compat.h. Pokud budete nuceni něco portovat na NT, doporučuju se na to podívat, ušetříte si mnoho starostí. Pracoval jsem na NT serveru 4.0 s MS VC++ 4.0, takže ony informace jsou v době psaní této části (16.2.1997) vcelku aktuální.

Každopádně - CSáček je nyní k dispozici pro Unix i NT zároveň. Co bude fungovat na Unixu bude vždy fungovat i na NT a naopak. Jediná vyjímka je momentálné skript whichcode, který je na NT samozřejmě nepoužitelný. Ale chystám se jej stejně přepsat do perlu, tak pak udělám změny do kódu tak, aby se dal použít i na NT (především aby se psala správná linka do lišty).

A co OpenVMS ? Hodilo by se jeho port taktéž nějak vložit do kódu, ale bohužel nemám přístup k žádnému stroji s OpenVMS, takže bude asi dost problematické ladění. Existuje port CSáčku 1.23, který má na svědomí pan Martin Bílý, viz Budoucnost ....

  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ů
• 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

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

... 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
• NOHEAD - nebude vypsána hlavička (HEADBARTEXT)
• HEAD - opět zapne vypisování hlavičky lišty
• NOTAIL - nebude vypsán závěr (obsah TAILBARTEXT)
• TAIL - opět zapne vypisování závěru lišty
• HEADTEXT - hlavička v české verzi lišty; použití ve tvaru HEADTEXT="text"; text může být libovolný text, může obsahovat i HTML značky; pokud je uzavřen v uvozovkách, může obsahovat i mezery a tabelátory
• EHEADTEXT - hlavička v anglické verzi lišty; použití EHEADTEXT="text"
• TAILTEXT - závěr lišty; př. TAILTEXT="text"
• ETAILTEXT - závěr englické lišty; použití ETAILTEXT="text"
• 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 ignorují.

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.

Zpět

Historie

Verze 1.2Y jsou vývojové verze, které už byly překonány verzí 1.3. Verze 1.3.X budou především opravovat chyby a bude pročištěn kód.

Vývoj

verze 1.3.1 (únor 1996)

• CSáček je nadále ve verzi pro NT i Unix
• opravena chyba s připisováním znaku ^Q do QUERY_STRING při určité délce předaného QUERY_STRING
• opravena chyba dealokace pole ve freecmdarr() (ovlivnila příkazy typu PART, které mají víc parametrů)
• opravena chyba v connect_server() - špatné mapování adresy na IP adresu (projeví se pokud CSáček nebyl zkompilován s LOCALHOSTHACK)
• při kompilaci je možno zadat seznam přípon označujících soubory, které se mají vždy kódovat metodou http - viz HTTP_SUFFIXES
• CSáček filtry byly odstraněny a nadále nejsou podporovány; pokud bude poptávka, snad se jednou zas objeví v jiné formě
• RESTRICTDOMAINS a MULTIPART bylo sloučeno dohromady pod hlavičkou MULTIPART
• je-li aktivní NOCODE, příkazy PART, DOMAIN se ignorují
• byly rozšíženy možnosti definování lišty s nabídkou kódování přímo v dokumentu; lze dynamicky měnit hlavičku české i anglické verze, závěr a pojmenování linky na volbu pomocí whichcode
• z CSáčku byl odstraněn kód, starající se o SSI; nechává se nyní zcela na straně serveru
• volba NPH spolu se souvisejícím kódem je také minulostí
• pokud požadované URL ukazuje na adresář a nekončí na /, CSáček klienta přesmeruje na URL/

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ů

  Zpět

Chyby CSáčku

• Verze 1.3

  1. na některých stránkách nelze používat PART (stránka se nezobrazí a vypíše se zpráva o chybe serveru)

  Chyba nastává při uvolňování alokované paměti při rozeznávání parametrů PART. Proměnná arr ukazující na pole argumentů je před dealokováním zvýšena iteracemi for() při uvolňování jednotlivých položek pole.

  2. funkce connect_server() špatně mapuje jméno počítače na IP adresu, Chyba se projeví (pokud CSáček nebyl zkompilován s možností LOCALHOSTHACK) tím, že se nedokáže spojit se serverem (píře - Cannot connect to server XXX, port YY).

  Chyba vznikla špatným pochopením obsahu struct hostent->h_addr. Dík za objevení a opravnený kód patří panu Vladimírovi Horákovi <vhor@cuni.cz>.

  Obě chyby řeší tento patch, který se aplikuje v adresáři s rozbaleným CSáčkem příkazem patch < _cesta_/patch-1.3-01.

  3. někdy se stává, že překódováním přes CSáček se ke QUERY_STRING přidá znak ^Q.

  Chyba je způsobena tím, že se alokuje málo místa pro zkopírování obsahu QUERY_STRING pro vnitřní potřeby CSáčku. Chybu opravuje tento patch.

  Zpět

Zajímavosti a linky na stránky o různých konverzních programech a češtině na WWW

• WWWdia - ftp - program pro změnu kódování stránek při přenosu uživateli
• SaCzech - program pro změnu kódování stránek při přenosu uživateli
• OBO - program pro udržování dvou a více jazyčného dokumentu v jednom souboru
• kod - ftp - program pro změnu kódování stránek při přenosu uživateli

• Čárka, háček a WWW - článek J. Schmidta v Computer Echo 6/95
• Stránka Ondřeje Bojara - popisující možnosti pro používání češtiny na WWW stránkách
• CSáček - kódování češtiny na Webovských stránkách - mé malé dílko pro Zpravodaj ÚVT MU

• ftp://toy.zcu.cz/pub/kiv-local/luki/published/cs-encodings-faq

Zpět