Mendelova zemědělská a lesnická univerzita v Brně Provozně ekonomická fakulta
Transformace TeX dokumentace na XML tvar Diplomová práce
Vedoucí práce: RNDr. Ing. Milan Šorm, Ph.D.
Bc. Tomáš Hanzelka
Brno 2006
Děkuji vedoucímu práce RNDr. Ing. Milanu Šormovi, Ph.D. za rady a připomínky k této práci. Dále chci poděkovat dokumentátorce UIS Ing. Jitce Šedé za cenné podněty při realizace této práce.
Prohlašuji, že jsem tuto diplomovou práci vyřešil samostatně s použitím literatury, kterou uvádím v seznamu.
Abstract Hanzelka, T. Transformation of TEX documentation to XML format. Brno, 2006 Thesis deals with practical solution of converting user’s documentation from TEX to XML. Initiatory part of this thesis is about role of documentation when some information system is developed and what are the benefits of this documentation when someone use it. There also is a summary of related technologies. Next part summarizes needed knowledge of used formats and existing tools for work with TEX and XML files. Last part of the thesis describes design of solution in Perl language and its realization.
Abstrakt Hanzelka, T. Transformace TEX dokumentace na XML tvar. Diplomová práce. Brno, 2006 Práce se zabývá praktickým řešením problémů při převodu uživatelské dokumentace z TEX formátu do XML. Část práce se věnuje roli dokumentace při vývoji informačního systému a praktickému přínosu této dokumentace při jeho používání i s přehledem používaných technologií. Dále práce přínáší přehled potřebných znalostí, souvisejících s problematikou převádění mezi formáty. Zabývá se možnými variantamo řešení tohoto konkrétního problému s poukazem na již existující nástroje pro zpracování TEX a XML dokumentů. Poslední část práce popisuje navržené a realizované řešení v programovacím jazyku Perl.
3 Softwarová dokumentace 3.1 Uživatelská dokumentace . . . . 3.2 Programátorská dokumentace . 3.3 Nástroje pro psaní dokumentace 3.4 Shrnutí kapitoly . . . . . . . . . 4 Značkovací jazyk XML 4.1 Předchůdci XML . . . . . 4.2 Vznik XML . . . . . . . . 4.3 Vlastnosti XML . . . . . . 4.4 Formáty spojené s XML . 4.5 Nástroje pro práci s XML
. . . . .
. . . . .
. . . . .
. . . .
. . . . .
. . . .
. . . . .
. . . .
. . . . .
. . . .
. . . . .
. . . .
. . . . .
. . . .
. . . . .
. . . .
. . . . .
. . . .
. . . . .
. . . .
. . . . .
. . . .
. . . . .
. . . .
. . . . .
. . . .
. . . . .
. . . .
. . . . .
. . . .
. . . . .
. . . .
. . . . .
. . . .
. . . . .
. . . .
. . . . .
. . . .
. . . . .
. . . .
. . . . .
. . . .
. . . . .
. . . .
10 10 13 17 21
. . . . .
22 22 22 23 24 27
5 Regulární výrazy 31 5.1 Vznik regulárních výrazů . . . . . . . . . . . . . . . . . . . . . . . . . 31 5.2 Formální definice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 5.3 Implementace a rozšíření . . . . . . . . . . . . . . . . . . . . . . . . . 32 6 Analýza převodu dokumentace UIS 6.1 Univerzitní informační systém MZLU 6.2 Dokumentace UIS v současné době . 6.3 Požadované vlastnosti řešení . . . . . 6.4 Možné varianty a výběr řešení . . . . 7 Popis a hodnocení zvoleného řešení 7.1 Popis řešení . . . . . . . . . . . . . . 7.2 Omezení zvoleného řešení . . . . . . . 7.3 Možná zlepšení řešení do budoucna . 7.4 Doporučení pro práci s dokumentací .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
36 36 36 37 38
. . . .
41 41 44 45 46
8 Závěr
48
9 Literatura
50
Přílohy
51
A Přepínače programu
52 5
B Výchozí konfigurace programu
53
C Ukázka dokumentace v TeX formátu
57
D Ukázka vygenerované dokumentace v XML formátu
60
E Ukázka XSLT stylu
62
F Ukázka převodu do formátu XHTML - zdroj
64
G Ukázka převodu do formátu XHTML - na obrazovce
66
6
1 1.1
Úvod a cíl práce Úvod do problematiky
V současné době se každý člověk potkává s počítačem a více či méně složitými informačními systémy. Tyto systémy mají obecně jednu vlastnost spojenou s celým počítačovým oborem – velmi rychle a snadno se nahrazují novými, rychlejšími a „lepšímiÿ. Stejně rychle jak se mění tyto systémy, měl by se je uživatel naučit používat, což není vždy právě snadné. K jednoduššímu poznávání těchto systémů či jejich nových vlastností je proto vydáván speciální materiál, tzv. dokumentace. Dokumentace zjednodušuje práci všem zúčastněným – jak uživatelům systému, tak jejich správcům. Při dobře zpracované dokumentaci uživatelé netápou, jak udělat požadovaný úkon. Dokáží se rychle zorientovat a nedělají zbytečné chyby při používání systému, což platí především pro nově příchozí uživatele, kteří k systému přistupují poprvé, pro ně je přehledná a účelná dokumentace pravým pokladem. Jen v případě, že je dobře popsána a vysvětlena funkčnost a smysl informačního systému, je jeho používaní pro uživatele přínosem. V opačném případě se stává často noční můrou a uživatel „soubojemÿ se systémem ztrácí drahocenný čas a k jeho dalšímu používání má odpor. Také správcům systému, kteří se starají o jeho správný chod, je dokumentace velmi užitečná. I když oni sami to většinou – pokud mají nějakou psát – často popírají. Například nejsou zahlceni častými (a většinou stále stejnými) dotazy uživatelů, na které se jim pak se už po tolikáté nechce odpovídat. I pro zkušeného správce je praktický manuál, jak udělat nějakou konkrétní věc, která byla právě implementovaná, nebo kterou správce používá zřídka. Mendelova zemědělská a lesnická univerzita v Brně provozuje od roku 2001 pro zabezpečení svého chodu vlastní informační systém. Tento Univerzitní informační systém (UIS) obsahuje většinu agend spojených s chodem univerzity a každodenně je používán tisíci studenty a zaměstnanci. Nutnost existence dokumentace je pro práci tolika lidí nezbytná, hlavně díky nemalé rozsáhlosti celého systému. V současné době existuje dokumentace pro uživatele ve formě několika souborů formátu Adobe Portable Format (PDF), které jsou volně ke stažení na Internetu. Toto řešení je jednoduše použitelné pro všechny uživatele, kteří tyto soubory mohou přečíst či vytisknout. Má však své nedostatky a omezení. Hlavním nedostatkem je oddělení dokumentace od samotného systému, uživatel si musí tuto dokumentaci sám stáhnout a jiným programem prohlédnout, což je pomalé a nepraktické. Ani není možné v dokumentaci kvalitně vyhledávat, navíc všechny části dokumentace jsou od sebe striktně oddělené a není je možné nějak propojit. Tématem mé práce je vyřešení těchto problémů převodem do formátu eXtensible Markup Language (XML). Tento univerzální značkovací jazyk umožňuje snadnou a automaticky generovanou konverzi do dalších formátů. Je tedy jakýmsi polotovarem, určeným k dalšímu převodu do podoby ke konečnému využití.
7
Posledním krokem řešení problému je pak existence stylu pro převod z XML do formy webových stránek, které budou přístupné z prohlížeče. Tyto webové stránky pak půjdou propojovat mezi sebou pomocí hypertextových odkazů a také prohledávat ze stejného uživatelské rozhraní, s jakým jsou uživatelé zvyklí pracovat. Stejně tak je plánováno použití XML dokumentů k vytvoření nového interaktivního typu dokumentace – kontextové nápovědy, která bude tématicky zaměřena na tu část, kterou pro právě prováděnou uživatel akci bude potřebovat. Tato poslední část však přesahuje cíle této práce a bude jen stručně naznačena tak, aby bylo zřejmé možné využití XML tvaru dokumentace.
1.2
Cíl práce
Cílem této práce je navrhnout a realizovat řešení pro automatický převod uživatelské dokumentace Univerzitního informačního systému Mendelovy zemědělské a lesnické univerzity v Brně z dokumentů ve formátu TEX do značkovacího jazyka XML. Pro úspěšné dosažení cíle jsem bylo potřeba nastudovat problematiku spojenou s tvorbou a automatickým generováním dokumentace a postup jakým tato dokumentace vzniká přímo na univerzitě. Dále v souvislosti s praktickým řešením bylo nutné pochopit strukturu a výhody použití obou zmiňovaných formátů. Ze získaných poznatů pak navrhout funkční řešení. V souvislosti s převodem bylo také nutné navrhnout začlenění již existujících nástrojů, které se používají pro práci s danými formáty. Podmínkou také je, aby řešení bylo možné dále přizpůsobovat novým požadavkům a aby se dalo po dokončení integrovat do stávajícího informačního systému. V závěru práce bude shrnuto jak se podařilo daný problém vyřešit, úskalí spojená s praktickým používáním navrženého řešení a nastínění dalšího možného rozvoje do budoucna.
8
2
Definice pojmů
Tato práce je věnována problému převodu mezi dvěma formáty, které jsou používané v oboru informačních technologií. Při hledání řešení daného problému se nemůžeme vyhnout používání některých odborných pojmů. Tato krátká kapitola některé z nich definuje tak, aby byl následující výklad co nejsrozumitelnější. Popis anglických výrazů uvádím také proto, že jejich český překlad často neexistuje nebo není tak výstižný. Informační technologie Zde uvádím hlavně kvůli časté záměně s technikou, která ovšem je jen fyzickou částí informačních technologií. Informační technologie kromě techniky v sobě zahrnují také dodávaný software, metody, postupy a dokumentaci sloužící k chodu nějakého informačního systému nebo programu. Informační technologie pak pomocí tohoto souboru nástrojů řeší širší problémy, např. tisk knihy nebo správu knihovního katalogu. Internet Internetem rozumíme celosvětovou počítačovou síť, ve které zapojené počítače spolu komunikují pomocí daného protokolu. Přenos informací je možný mezi jakýmikoliv dvěma počítači do této sítě připojenými. Tuto síť pak lidé používají k nepřebernému množství různých služeb na ní provozovaných. Odhaduje se, že uživatelů této sítě je již přibližně jedna miliarda. World Wide Web (WWW) Nejrozšířenější službou na Internetu je World Wide Web (WWW). Tato služba umožňuje zveřejňovat dokumenty ve formátu HTML, takzvané stránky. Tyto stránky, kromě toho že mají nějaký obsah (text, obrázky, video), mohou být mezi sebou propojené pomocí odkazů. Ve spojení s některými technologiemi mohou obsahovat i dynamicky generovaný obsah a interaktivně se měnit dle zadání uživatele. Pro zobrazení těchto stránek je potřeba speciální program, tzv. prohlížeč. World Wide Web Consortium (W3C) Mezinárodní konsorcium sdružující odborníky, firmy i veřejnost k vývoji standardů pro službu WWW. Cílem tohoto sdružení je snaha o definici protokolů a standardů spojených s WWW tak, aby byl zajištěn trvalý rozvoj a přínos pro uživatele. Přčstože návrhy vydávané konsocire (na rozdíl od Mezinárodní organizace pro normalizaci – ISO) nemají žádnou právní autoritu, jsou natoli dobré, že jsou vydávaná doporučení příjmána za de facto standardy v dané oblasti. Toto sdružení vyvinulo většinu standardů spojených s formátem XML, o kterých se tato práce zmiňuje. Parser Parsování textu v oboru informačních technologii vyjadřuje proces analyzování vstupních dat např. ze souboru nebo klávesnice. Účelem této analýzy je rozeznat strukturu těchto dat a určit zda splňují předem dané požadavky, zapsané formální 9
gramatikou. Tomuto procesu se také říká syntaktická analýza. Parser je počítačový program, který tuto analýzu provádí. Well-formed dokument Dokumenty, které jsou označeny jako well–formed, jsou textové dokumenty, které splňují všechny požadavky definované standardem XML. Jsou to nutné podmínky k tomu, aby dokument mohl být automaticky rozpoznán a zpracován nějakým parserem. Mezi základní požadavky patří správně definované kódování znaků, uzavřené elementy, atributy elementů v uvozovkách atd. Doporučené je logické a a přehledné pojmenovaní elementů tak, aby při čtení nějakým člověkem byl význam elementů pochopitelný i bez další dokumentace. Human-readable Tento výraz označuje informace, které umí člověk snadno přečíst, narozdíl od dat, která jsou určeny pro zpracování počítačem. Obvykle jde o obyčejný text, který není nijak zakódován a jeho význam je hned pochopitelný. Ukládání do human–readable formátu má nesporné výhody – předávaná data nepotřebují žádný popis jejich významu, ani žádný speciální program k jejich čtení. Nejsou závislá na žádné technické platformě ani konkrétním programu. Nevýhodou je nepoužitelnost pro některé typy dat (např. obrázky), většinou špatná strojová zpracovatelnost a také jejich velikost, neboť je nelze zmenšit nějakým kompresním algoritmem. XML formát je příkladem kompromisu, který umožňuje o jak parsování počítačem, tak čtení člověkem. Unicode Znaková sada Unicode byla definovaná sdružením Unicode Consortium v roce 1988. Tato univerzální sada znaků byla vyvíjena na základě problémů při zpracování národních znaků v počítačovém oboru. Díky nekompatibilitě jednotlivých kódování vznikaly značné komplikace při komunikaci mezi aplikaceni a při přenosech dat mezi programy a různými platformami. Problém odstranil Unicode rozšířením rozsahu jednoho znaku (z původně používaných 7 nebo 8bitů až na 31), čímž byl pokryt rozsah na všechny známé znakové sady jazyků na zemi (včetně složitého japonského nebo čínského písma i speciálních znaků pro vědecké a matematické symboly). V tomto kódování lze všechny znaky zobrazit zároveň; v jednom textu lze tedy kombinovat např. češtinu i řečtinu. Stále více se prosazuje v aplikacích i operačních systémech a bylo přijato již v roce 1993 jako ISO norma 10646. Sada Unicode je výchozím kódováním pro všechny XML dokumenty. Jmenné prostory (namespaces) Jmenné prostory jsou abstraktní, pomyslnou množinou jmen (názvů objektů), které k sobě nějak významově patří. Každý jmenný prostor je pojmenován tak, aby jej bylo možné jednoznačně identifikovat a zároveň platí pravidlo, že v daném jmenném prostoru nejsou žádné dva objekty se stejným názvem. Díky těmto jmenným prostorům lze pak pracovat s více množinami stejných jmen, neboť jejich rozlišení je zřejmé dle kontextu, podle toho do jakého jmenného prostoru patří. Příkladem je použití jmenných prostorů v XML dokumentech, které obsahují vícejazyčné části. 10
3
Softwarová dokumentace
Dokumentaci je možné definovat jako všechny materiály (např. text, video, zvuk nebo jejich kombinace), které jsou použity k vysvětlení různých aspektů nějakého objektu, systému nebo procedury. Nejčastěji se setkáváme s dokumentací technickou, projektovou nebo softwarovou, popisující strukturu a komponenty či návod k použití daného systému nebo produktu. Nosičem takové dokumentace je většinou tištěná kniha nebo elektronický dokument. V souladu s cílem této práce se dále budu zabývat pouze dokumentací sofwareovou, tedy dokumentací jednotlivých počítačových programů nebo větších systémů z oboru informačních technologií. Pokud se tedy zmiňuji o dokumentaci, je míněna dokumentace softwarová. Daný program nebo informační systém shrnuji pod kratší výraz produkt, neboť v případě dokumentace není nutné tyto dva druhy odlišovat. Autorem dokumentace je nečastěji specializovaná osoba tzv. dokumentátor. Ten musí mít kromě dokonalé jazykové znalosti přehled v oboru, a to minimálně na úrovni pochopení odborných výrazů a jejich souvislostí. Daný systém nebo produkt pak musí pochopit a popsat ho tak, aby ten, komu je dokumentace určena, i bez nějakých předchozích znalostí pochopil, co potřebuje. Náročnost obsáhnutí oboru je častým důvodem proč v některých případech je autorem dokumentace řešitel daného problému (inženýr, programátor), který sám zdokumentuje tu část, za kterou je odpovědný. Výhodou je samozřejmě odborná znalost autora, který zná velmi dobře svoji práci a jen těžko může udělat při popisu nějakou faktickou chybu. Na druhou stranu je rozšířeným jevem, že dokumentace vlastního díla je těmito lidmi považována za nutné zlo, které je při vývoji daného produktu zdržuje od jejich „opravdovéÿ práce. Také nutná trpělivost při popisu triviálních znalostí pro laickou veřejnost (v případě psaní uživatelské dokumentace), která jejich produkt používá a jejich oboru nerozumí, je u těchto lidí spíše výjimkou. Stejně tak málo častá je dobrá jazyková vybavenost a schopnost napsat jednoduchý, slohově kvalitní a srozumitelný text. Základní hledisko, které musíme mít při psaní dokumentace na zřeteli, je komu bude dokumentace určena. Výše popsané dělení podle autora není tím důležitým hlediskem jak na danou dokumentaci nazírat. Dokumentace je kvalitní pouze tehdy, pokud splní svůj účel a ten je spojen s jejím uživatelem. Je tedy nepodstatné, kdo danou dokumentaci napsal a jen z pohledu čtenáře lze posoudit, zda účel dokumentace byl či nebyl splněn. Další dvě podkapitoly popisují dokumentaci ze dvou základních pohledů, a to z pohledu uživatele daného produktu a z pohledu programátora, který při své práce se systémem pracuje s jeho náplní práce.
3.1
Uživatelská dokumentace
Důvodem pro psaní každé uživatelské dokumentace je popsat, co program umožňuje uživateli a jak toho má dosáhnout. Což není vždy snadné a nese s sebou jistá úskalí.
11
Vzhledem k tomu, že není vždy jasné, kdo bude čtenářem našeho textu, musíme při psaní přizpůsobit sloh a náročnost i laickému čtenáři, který se s daným produktem seznamuje poprvé. Pokud je okruh potencionálních uživatelů rozsáhlý a předem není konkrétně specifikovatelný, nemůžeme předpokládat, že daný uživatel má nějaké předpoklady či znalosti o daném programu, respektive o oboru, kterého se program týká. Typickým příkladem je program volně dostupný široké veřejnosti a tedy čtenářem může být opravdu kdokoliv. Co se týče slohu, je dokumentace literární žánr svého druhu . Jako v každém kulturním textu je vhodné, aby každá věta měla nějaký význam a byla zasazena do správného kontextu. Není vhodné používat nic neříkající výčty technických parametrů (ty patří do příloh), nebo prokládat text dlouhými obecnými pasážemi, které uživateli nic nepřinesou. Nejlepší je souvislý a čtivý text, doprovázený vysvětlujícími obrázky. Někdy lze použít ikony pro upozornění na typ informace, kterou daný odstavec nese. Dalším úskalím je jak má být daná dokumentace strukturovaná. Následující popis členění dokumentace nevychází z žádné konkrétní metodiky, ale je spíše subjektivním názorem. Ten jsem si vytvořil na základě praktických zkušeností při seznamování se různými informačními systémy a nespočetnými programy, se kterými jsem pracoval. Druhým zdrojem při hledání informací byly konzultace s dokumentátorkou UISu, která má praxi jak se psaním dokumentace, tak s mnoha podněty od jejich uživatelů. Tato struktura je definována pro úplnou uživatelskou dokumentaci, jak uvidíme v další kapitole, jsou možné i jiné varianty, které však jsou jen doplňující nebo neúplnou formou uživatelské dokumentace. Dokumentace většinou začíná obecným přehledem, k čemu je daný produkt určen a kdo by ho měl používat. Dále je předem vhodné uživatele seznámit s filosofií programu, kdo by ho měl používat a jaké uživatelovy znalosti jsou předem přepokládány. Je však chybou přepokládat nějaké hlubší chápání problému, který daný program řeší. Vhodné je seznámit se základními problémy oboru uživatle dopředu a přidat vysvětlení základních pojmů a užitých zkratek. Pojmy zde uvedené musíme dodržovat a nepopisovat stejnou věc dvěma jinými způsoby nebo naopak dvě různé věci, které jsme definovali samostatně, pak shrnout jedním obecnějším výrazem. Pokud tedy již uživatel pochopil, k čemu je produkt určen, je dobré mu vysvětlit, jak toho dosáhnout, tedy ovládání programu. Jednotlivé funkce je dobré popsat podle jejich důležitosti a složitosti. Ty jednoduché a více používané uvedeme dříve, nejlépe s názornými příklady jejich použití. Není vhodné popisovat ovládání pomocí struktury nabídkového menu, to je umístěno a děleno spíše podle mnohokrát použité a již zažité normy, a o produktu samotném nic nevypovídá. Na závěr je vhodné program dát do kontextu s okolním světem. Pro mnoho produktů v dnešní době existuje podpora na Internetu, kde se lze dozvědět mnohé užitečné informace. Jde o časté dotazy uživatelů, diskusní fóra nebo rozšíření a doplňky, které program umožňuje. Vhodné je tedy na tyto možnosti upozornit a dát do dokumentace odkaz na stránky o programu, stejně tak jako odkázat, kam je dále vhodné se obrátit v případě dotazů (např. telefonní linka nebo školicí středisko) a 12
také kontakt na autora. Úplně na konec je užitečné u větších projektů dát rejstřík, popis chybových hlášení a doporučené reakce na ně, podrobnější technické informace nebo užitečný přehled příkazů a klávesových zkratek. Typy uživatelské dokumentace Struktura dokumentace, uvedená v předcházející části, platí jen pro základní typ dokumentace – uživatelský manuál. Ten patří mezi nejběžnější typ uživatelské dokumentace pro softwarové produkty. Je jediným typem dokumentace, který obsahuje úplné členění, jak bylo popsáno v minulé části, ostatní typy jsou jen stučnějšími verzemi uživatelského manuálu. Můžeme se také setkat s pojmenováním uživatelská příručka nebo podrobná příručka či učebnice. Autorem těchto publikací nemusí být vůbec autor daného produktu, častěji je to nějaký velmi zkušený profesionál v daném oboru, používající tento program. O něco stručnější, praktičtěji orientovaný dokument, je referenční příručka. Ta není většinou psána jako souvislý text a je již určena pro zkušenější uživatele. Neseznamuje čtenáře podrobně s problematikou, nýbrž je přehledem všech funkcí, které daný produkt nabízí a to včetně těch méně používaných. Důraz je kladen na úplnost popisu včetně technických detailů. Jde tedy o jakousi pomůcku, kterou má uživatel po ruce pro případ, že potřebuje rychle vyhledat konkrétní postup či informaci. Nejstručnějším přehledem základních funkcí produktu bývá přehled klávesových zkratek. Ten obsahuje seznam těch zkratek, o kterých se přepokládá, že jsou používány nejčastěji. Uživatel daného produktu mívá tento přehled přímo u počítače. Stejně koncipovaných dokumentem jsou referenční karty, které místo klávesových zkratek obsahují nejčetnější postupy, jak řešit konkrétní úkony. Předchozí typy uživatelské dokumentace měly jednu společnou vlastnost, že téměř vždy existují v papírové podobě. Jejich elektronická verze je jen doplňujícím formátem, narozdíl od následujících typů, které naopak převážně existují jen ve formě elektronické. Nejčastěji používaným typem elektronické dokumentace je on–line nápověda. Ta je dodávána vydavateli daného produktu k rozsáhlejším programům jako alternativa k uživatelským manuálům. Většinou obsahuje o něco méně informací než manuál, hlavně je zaměřená na ovládání programu, popis nastavení a stručné návody jak řešit konkrétní problémy. Nápověda je většinou rozčleněna do kapitol dle jednotlivých funkcí programu a jednotlivá témata jsou mezi sebou propojena hypertextovými odkazy. Pro snadné nalezení tématu má svůj obsah a rejstřík a je možné ji prohledávat podle zadaných klíčových slov. Uživatelsky oblíbené jsou také tzv. FAQ – Frequently Asked Questions, v překladu „často kladené otázkyÿ1 . Tento typ dokumentace obsahuje seznam typických 1 Název „FAQÿ se objevil až na Internetu, konkrétně v USENEtových diskusních skupinách. Koncept je ovšem mnohem starší, např. již v roce 1647 vydal Matthew Hopkins knihu The Discovery of Witches („Odhalování čarodějnicÿ), která se držela formátu otázek a odpovědí.
13
otázek a odpovědí, které se ohledně nějaké problematiky vyskytují a uživatelé se nimi často setkávají. Motivací pro vznik tohoto typu dokumentace byla snaha o zamezení pokládání stále stejných dotazů uživatelů buď autorům produktu nebo ostatním uživatelům ve fórech. Je dobrým zvykem a doporučením si před položením nové otázky někomu dalšímu tyto FAQ přečíst. Jedna z mála netextových dokumentací je tutoriál, který je ve formě videa. Toto video je buď ve formě programu nebo animace na internetových stránkách. Rozlišujeme dva základní typy tutoriálů, interaktivní a neinteraktivní. V případě neinteraktivního uživatel jen sleduje daný film. V interaktivním tutoriálu program s uživatelem spolupracuje. Ukazuje mu co má udělat a pak vede jeho další kroky podle reakcí uživatele. Mezi interaktivní nápovědu také patří kontextová nápověda. Ta je součástí daného produktu a umožňuje uživateli využít nápovědu k právě prováděnému příkazu nebo funkci. Odpadá tedy čtení celé nápovědy a hledání toho, co uživatel požaduje. Forma této nápovědy bývá například ve formě popisu, který se sám zobrazí nad nějakým funkčním prvkem při jeho použití nebo se zobrazí na uživatelovu žádost jako ta část dokumentace, která je v danou chvíli relevantní. Někdy bývá součástí dokumentace také pár stručných návodů pro vybrané konkrétní postupy, tzv. „HowToÿ (z anglického „How to . . . ÿ, v překladu „Jak na . . . ÿ). Tyto návody popisují řešení různý dílčích, avšak nejpoužívanějších problémů a jsou určeny i pro úplné začátečníky. Psány jsou jako odpovědi na dané otázky, které daný produkt umožňuje řešit, např. „Jak vložit obrázekÿ, bez nějakých vysvětlujících podrobností . Někdy je dokumentace tvořena jen seznamem těchto jednotlivých „HowToÿ dokumentů. V případě jednoduchých a jednoúčelových programů jde o efektivní způsob jak předat potřebné informace uživateli a nepopsat stohy papíru. Někdy jsou „HowToÿ psány také s negativními otázkami („Co dělat když nefunguje . . . ÿ), jako rady co dělat při vzniklých problémech. Na závěr zmíním ještě referenční dokumentaci. Ta obsahuje základní informace převážně technického charakteru. Popisuje jednotlivé služby a základní informace potřebné pro pochopení účelu daného produktu. Je napsána tak, aby se jím dalo řídit například při výběru mezi několika jinými produkty. Není tedy dokumentací v tom smyslu, že by čtenáře seznamovala s používáním daného produktu, pouze informuje o tom, co daný produkt umí.
3.2
Programátorská dokumentace
Každý softwarový produkt má kromě uživatelů také jejich autory, programátory. U malých produktů je autorem jeden programátor, u větších projektů jsou to desítky až stovky lidí. Programátorem zde myslíme autora vlastního kódu produktu, ne tedy celý tým lidí, kteří se na vývoji produktu podílejí (analytiky, databázové specialisty). Těm je tento typ dokumentace určen jen okrajově. Programátorskou dokumentací zde myslím popis k danému produktu nebo (u větších produktů) jejich logické části,
14
která je vyvíjena samostatně. Pojmenování těchto částí je různé, nejčastěji modul. Programem tedy je v dalším textu myšlen celý produkt nebo modul. V obou případech má programátorská dokumentace zásadní význam pro další vývoj produktu. Pokud je autorem jen jedna osoba, má dokumentace sice význam menší, ale i tak důležitý. Slouží hlavně k tomu, aby i po delším časovém odstupu bylo možné se v kódu programu vyznat a případně je nějak měnit. Neexistuje žádný program, který by v sobě nějaké chyby neobsahoval. Dobře napsaný popis toho, jak byl program napsán pak rapidně zmenšuje dobu vyhledávání a opravování těchto chyb. V případě větších projektů, na kterých pracuje více lidí, se význam dokumentace značně zvyšuje. Kromě popisu samotného programu pro pozdější pochopení zde hraje významnou roli při spolupráci těchto osob. Stejně tak je zásadní v případě, když někdo z týmu programátorů odejde a je nahrazen někým novým. Což v případě větších týmů není nijak neobvyklé, a je nutné aby nový programátor mohl co nejdříve zastoupit svého předchůdce. Dokumentace tak snižuje závislost vývoje produktu na konkrétních osobách. Dalším využitím je nutnost zdokumentovat technické vlastnosti a omezení programu. Program obvykle má nějaké základní určení a omezení, jejichž existenci autor považuje za zřejmé, ale pro někoho, kdo s programem nepracuje každý den, nemusí být jasné. Často se jedná o různá nastavení aplikací nebo specializovaného hardware od jiných firem, se kterými program spolupracuje. To se třeba nemění po celou dobu vývoje aplikace, což se snadno zapomene a považuje za samozřejmé. Krátce k tomu, co by měla programátorská dokumentace obsahovat. Nejdříve je vhodné formulovat zadání problému a popsat způsob řešení a jeho výsledek, tedy vlastní program. Každý program má nějakou systematiku a filosofii své tvorby, účel a způsob použití. Důležité použité algoritmy a zvolené metody, nejlépe nezávisle na použitém programovacím jazyku, tedy abstraktní popis toho co program dělá. Toto všechno je nutné správně definovat a popsat tak, aby jasně vyplývalo, jak se může daný program udržovat a vyvíjet. Všechny vstupy i výstupy, interakce s okolím, musí být popsané včetně očekávaných formátů a ošetření chybových stavů. Pokud je výstup určen pro další počítačové zpracování, součástí popisu je přesný popis datových struktur a syntaxe. Cílem je tedy základní pochopení vlastností zvoleného řešení a jeho parametry. Výše zmíněné obsahové doporučení platí nejen pro celý program jako celek, ale i pro každou jeho část. Tedy pro každý program existuje souhrnná dokumentace, kterou používají všichni její autoři. Tato hlavní dokumentace celého systému obsahuje popis dělení na menší celky či vrstvy a charakteristiku jednotlivých rozhraní (interface), pomocí kterých pak části mezi sebou komunikují. Dále existuje pro každou část (modul) vlastní úsek, který popisuje jen tuto část a její vztahy s celým programem. Zde se klade větší důraz na konkrétní řešení, spíše než jeho filosofii. Hlavní je správná interpretace výsledků části programu a jeho zapojení do celku. Ještě si stručně popíšeme, jaké formy programátorská dokumentace může mít. Kromě již zmiňovaných textů s určeným obsahem, jako je přehled struktury pro15
gramu, algoritmické řešení, podprogramů a datových struktur, které mají stejné vlastnosti jako jiné texty, jde také o speciální typy, vyskytující se jen v oboru informačních technologií. Typy programátorské dokumentace Klasickým a nejčastěji používaným způsobem je psát dokumentaci přímo do kódu pomocí komentářů. Komentáře ve všech programovacích jazycích mají definované nějaký způsob pro odlišení od vlastního kódu a používají se spíše pro základní popis jednotlivých funkcí daného programu, než celého programu. Kromě popisných textových komentářů je možné tyto komentáře i strukturovat podle předem definovaných konvencí. V poslední se objevily nástroje, které při zachování určitých konvencí těchto kometářů mohou dokumentaci generovat automaticky. Syntaxi, jak různé části komentářů zapsat má každý dále popsaný generátor svoji, ale obsahově se téměř neliší. Většinou jde o speciální značky (tagy), určující, kdo danou část kódu napsal, seznam parametrů, verzi a datum poslední změny, odkazy na příbuzné části a návratové hodnoty. Více o kombinaci psaní kódu programu dohromady s jeho dokumentací je v části o literárním programování. Kromě komentářů, které píše sám programátor, má většina nástrojů pro generování dokumentace také možnost pracovat se samotným zdrojovým kódem programu. Jeho parsováním lze vytvářet přehledy balíků, strom tříd nebo seznamy všech souborů, ze kterých se program skládá. Co se týče funkcí, lze vygenerovat také Application Programming Interface (API, v překladu „rozhraní pro programování aplikacíÿ), což je seznam funkcí a jejich atributů v programu použitých a které jsou nějakým způsobem nabízeny k využití jiným částem programu. Jejich popis určuje jaký mají význam, jak je použít a jak je volat. Výhodou je, že se na jednom místě spojí dílčí dokumentace jednotlivých částí, čímž je možné prohledávat použití funkcí a modulů v kontextu celého programu. Výsledkem je obsah a rejstřík používaných elementů ne nepodobný jejich protějškům v dokumentaci uživatelské. Literární programování Jak již bylo zmíněno, hlavním účelem programátorské dokumentace je snaha o zdokumentování funkcí kódu pro další použití. Programy jako takové obsahují vždy nějaké chyby a je potřeba je odstranit, což je možné jen v případě, že dobře pochopíme jeho funkci. Porozumět kódu programu je však složité, obzvláště pokud kód psal někdo jiný a je součástí nějaké komplexnější struktury. Je tedy zřejmé, že každá metoda vedoucí k zpřehlednění kódu a k zlepšení jeho srozumitelnosti je vítaným přínosem. Metoda literárního programování2 od Donalda E. Knutha je jednou z nich. Tento autor sázecího systému TEX jako první použil v roce 1981 systém WEB, který kombinoval ve zdrojovém kódu části jazyka Pascal a obsah dokumentace 2
Více o literárním programování viz (Šorm, 2006).
16
formátovaný značkami TEXu. Tento přístup umožnil z jednoho zdroje vygenerovat kompletní dokumentaci, nebo zkompilovat samotný program. Navíc díky míchání dokumentace se zdrojovým kódem je snadné porozumět tomu, k čemu daná část slouží, neboť se vždy v daném místě se nachází i její popis. Původní systém WEB byl časem přepsán do novějšího CWEB za pomocí jazyka C a implementován i do dalších jazyků, např. Plain Old Documentation pro programovací jazyk Perl (PerlPOD) nebo JavaDoc pro dokumentaci v jazyku Java. CWEB se stal de facto standardem i pro další generátory dokumentace pro jiné jazyky například PHP, C++, VB.NET nebo Delphi, a je podporován v mnoha prostředích pro vývoj software. Nástroje pro generování programátorské dokumentace Generátor dokumentace je nástroj, umožňující vytvářet technickou dokumentaci daného programu. Jak bylo již uvedeno, autorem je přímo programátor kódu, který mezi funkční části kódu vkládá speciálně označené komentáře, které pak generátor zpracuje spolu se zdrojovým kódem daného programu nebo celého projektu obsahující více programů. Většinou jde o samostatný program, který pracuje s daným programovacím jazykem. Někdy jde o nástavbu programovacích prostředí (IDE) nebo o programy distribuované již se samotným programovacím jazykem. Občas lze tyto generátory použít i on–line přes webové rozhraní. Výsledná dokumentace může být v mnoha různých formátech a také lze její vizuální stránku měnit nějakým stylem. Uvádím stručný přehled nejpoužívanějších generátorů a jejich vlastnosti. JavaDoc Tento nástroj je určen pro parsování komentářů ve zdrojových souborech napsaných v jazyce Java. Kromě programátorem napsaných komentářů parsuje i samotný kód programu a umožňuje tak automaticky generovat API. Výsledný dokument navíc obsahuje seznamy tříd i jejich popisy, seznam balíků, souborů daného balíku, všech elementů souboru seřazený dle typu, úkolů k dopracování atd. To celé je přehledně uspořádané, s navigačním panelem a vzájemně provázané hypertextovými odkazy. Vizuální podobu lze měnit pomocí předdefinovaných, měnitelných šablon, a to pro libovolný výsledný formát. Export je podporován do formátů HTML, CHM3 , PDF, XML nebo DocBook. Stejně jako Java samotná je i tento program platformově nezávislý a díky velké podpoře a rozšíření Javy se použitá syntaxe stala velkou inspirací pro ostatní nástroje. Oxygen Relativně nový nástroj pro dokumentaci programů v jazycích C++, C, Java, Objective-C, Python, IDL. Přidáním dalších rozšíření je možné ho použít také na 3
Microsoft Compressed HTML Help. Speciální formát pro nápovědu ve formě HTML stránek, propojených a zabalených do jednoho souboru. Používá se na platformě Windows jako standardní formát nápovědy aplikací.
17
PHP, C# a D. Pro každý program zvládne vizualizovat vztahy mezi různými elementy a jejich závislosti, grafy dědičnosti a spolupráce. Kromě toho si poradí s normální psanou dokumentací obsahující popis programu i jeho části. Umí exportovat do formátů HTML, LATEX, RTF, PostScript, PDF, CHM a unixových manuálových stránek (man pages). Program je dostupný pro platformy Unix i Windows. phpDocumentator Nástroj pracující s programy v jazyku PHP, který má velmi podobnou syntaxi jako zmíněný JavaDo a dokáže generovat podobné seznamy a obsahy. Podporuje odkazy mezi dokumentací, vkládání externích souborů s uživatelskou dokumentací a také tvorbu tutoriálů se zvýrazňováním PHP kódu přímými odkazy do dokumentace. Dokumenty na výstupu mohou být ve formátech HTML, PDF, CHM, DocBook. V základní instalaci je již 15 hotových stylů a je také možné šablony stylů měnit. PerlPOD PerlPOD se z uvedených nástrojů nejvíce blíží ke konceptu literárního programování. Značky které používá jsou spíše stylistického a typografického charakteru než programovacího. Syntaxe obsahuje dvě úrovně nadpisů, značky pro delší texty nebo odsazení odrážek. Dále lze definovat části textu určené jen pro konkrétní výstup nebo určit přesné formátování textu. Také vkládání jiných souborů nebo odkazování na další části není ničím složitým. Výstup lze mít ve formátech LATEX, TEX, prostý text a HTML. O použitelnosti tohoto nástroje vypovídá, že samotná dokumentace programovacího jazyka Perl je napsaná v PerlPOD syntaxi.
3.3
Nástroje pro psaní dokumentace
V této podkapitole stručně představím běžné nástroje pro psaní dokumentace a výhody a nevýhody jejich používání. Hlavní důraz kladu na popis nástroje TEX , který je používán pro psaní uživatelské dokumentace UIS. Textové editory Textové editory patří k těm nejzákladnějším aplikacím, které se na počítačích používají již od prvopočátku jejich vzniku. Slouží k psaní a ukládání jednoduchých „čistýchÿ textů (anglicky „plain textÿ), ve kterých není nijak určeno výstupní formátování textu, ale jen jejich obsah. Textový editor tedy žádným způsobem neurčuje jak bude dokument vypadat na výstupu, pouze pomáhá uživateli při jeho psaní, font je většinou neproporcionální. Mezi základní funkce, které textové editory nabízí, patří kopírování, hledání či nahrazování částí textu. Ty propracovanější nabízí psaní opakujících se operací pomocí maker, různé převody či barevné odlišování syntaxe textu při editaci souboru. Výhodou je jejich nenáročnost, rychlost používání a velký výběr editorů na všech platformách, z nichž značná část je zdarma. Odpadá také nutnost pracovat 18
v nějakém grafickém prostředí, výstupní soubory jsou zobrazitelné na jakémkoliv zařízení a přenositelné mezi platformami. Omezením je pak nemožnost text naformátovat a většinou i menší uživatelská přívětivost. Používány jsou tedy hlavně programátory (někdy se tomuto typu říká také programové editory) a správci systémů. Mezi nejrozšířenější patří editory vim, Emacs, joe (na Unixovýxch systémech) či Notepad a PSPad na platformě MS Windows. Textové procesory Pro definici textových procesorů je asi nejdůležitější zkratka WYSIWYG. Tato vychází z anglického „What You See Is What You Getÿ (česky přibližně „co vidíš, to dostanešÿ) a je označením pro grafické textové editory, ve kterých uživatel již při psaní textu vidí konečnou podobu rozepsaného dokumentu, tak, jak bude vytištěna. Uživatel má nepřeberné množství možností jak text naformátovat, může změnit velikost, barvu, font písma a výsledek hned vidí na svém monitoru. Tyto textové procesory umožňují kromě obyčejného textu také vkládat různé objekty jako jsou obrázky, tabulky nebo grafy, křížové odkazy, automaticky generovaný obsah či rejstřík. Dále mají často vestavěné funkce pro kontrolu pravopisu, propojení s databází nebo sledování změn dokumentu v čase, interaktivní formuláře atd. Často jsou tyto procesory dodávané dohromady s jinými programy, jako jsou tabulkový procesor, tvůrce prezentací či program na správu databází. Tyto jsou prodávány hlavně pro kancelářské a domácí použití. Mezi nejrozšířenější patří v současné době kancelářský balík Microsoft Office s textovým procesorem Word nebo zdarma dodávaný OpenOffice s textovým procesorem Writer. Mezi výhody používání textových procesorů patří jednoduché ovládání i pro nezkušené uživatele, kteří mohou vytvářet složitě naformátované dokumenty. Což je zároveň i nevýhodou, neboť při této velké složitosti WYSIWYG není rozhodně dokonalý a výstup není vždy stejný, jak vypadá na obrazovce. Pro přísná pravidla typografické sazby nebo rozsáhlejší texty je tento typ editoru nevhodný. Mezi další nevýhody patří závislost uživatele na konktétním programu při práci s daným dokumentem a větší velikost zpracovávaných dat. DTP programy Programy pro desktop publishing (DTP) se používají pro výrobu kvalitních a vícenákladových publikací, které jsou určeny široké veřejnosti – časopisů, novin nebo knih. Stejně tak jako textové procesory umožňují interaktivní zpracování dokumentu, ovšem jsou na ně kladeny mnohem větším nároky na design, typografickou sazbu a tiskovou úpravu. Tyto programy nejsou určeny pro běžné uživatele, používají je školení profesionálové. Mezi známé patří QuarkXPress nebo Adobe InDesign. Pomocí těchto programů je sice možné vytvářet dokonalé dokumenty, používány jsou díky své celkové složitosti jen na úzkou skupinu lidí. Také je zpracování textu časově náročnější než 19
u přechozích typů programů. Další nevýhodou je vysoká pořizovací cena, která je většinou několikanásobně větší než pro běžný textový procesor. TeX TEX je program, který vytvořil profesor Stanfordovy univerzity Donald E. Knuth v roce 1978 pro kvalitní a typograficky správnou sazbu textu. Název TEXje odvozen od počátečních písmen slova „technologieÿ, což v řečtině prý znamená technologii i umění. Proto se název čte řecky „techÿ. Při tvorbě tohoto programu byl motivován hlavně nespokojeností sazby své vlastní knihy „The Art of Computer Programmingÿ a tak se rozhodl vytvořit zcela nový nástroj 4 . Výsledkem práce byl velice univerzální nástroj, který sice nebyl uživatelsky moc přívětivý, ale byl otevřený pro další rozšiřování. Uživatel TEXu je od počátku veden k běžným typografickým zásadám díky tomu, že Knuth pečlivě nastudoval zákonitostí typografie a spolupracoval s předními americkými typografy (např. Hermanem Zapfem). Psaní dokumentace v TEXu je zcela odlišné od ostatních editorů a má dvě fáze – napsání vlastního zdrojového textu dokumentu a následný převod do konečné podoby. Při psaní textu se formátovaní jednotlivých částí dokumentu určuje pomocí speciálních značek („mark–upÿ), které pak s vlastním obsahem tvoří zdrojový text dokumentu5 . TEX sám dokáže pracovat se značkami pro zarovnání či obtékání textu, umístění tabulek na stránku sazbu do sloupců, horní a dolní záhlaví, poznámky pod čarou a spoustu dalších, včetně složitých matematických výrazů. Také dokáže sám správně dělit slova pokud se již nevejdou na řádek, odstraňovat zbytečné mezery, posunuje jednopísmená slova na konci řádku na další a umí uplatnit další typografické zásady, se kterými si tak uživatel nemusí dělat starosti. Kromě zdrojového textu se TeXu předloží k načtení sada maker, které převádějí logické značky v dokumentu na příkazy určující konečný vzhled. Je jimi určeno, jak mají vypadat logické značky v textu a definují typografii dokumentu. Tato makra jsou definovatelná nezávisle na zdrojovém textu a dají se jednoduše upravovat. Tím je umožněna další dobrá vlastnost TEXu a tou je možnost oddělení práce na obsahu od vizuální stránky dokumentu. Typograf tak může pomocí maker navrhnout jak bude finální výstup vypadat bez zásahu do zdrojového textu. Autora textu je pak zcela zajímá jej jen obsah dokumentu a starost o formu svěří typografovi6 . Ustálené množině maker se pak říká styl. Jako zásadní pro tuto práci, uvádím vlastnost TEX u, že tyto styly se mohou definovat pomocí nových značek. Při převádění z dokumentace, která má vlastní styl, tedy potřebujeme i vlastní konfigurační soubor, který tyto nové značky zná. Při 4
Při psaní TEXu Knuth jako první navrhl koncept literárního programování, viz kapitola 3.2 Ukázka formátování viz příloha A 6 Tato vlastnost byla využita při psaní této práce, styl je definován zcela odděleně od obsahu. 5
20
používání stylů se pak samotný obsah dokumentu píše s pomocí nějaké nástavby, jako např. LATEX(viz. níže)7 . Mezi velmi sofistikované vlastnosti TEXu patří kerning a ligatury. Kerning je metoda seskládání jednotlivých znaků k sobě v rozestupech, které jsou určené danou kresbou písma, což značně zlepšuje estetickou stránku textu. Ligatury jsou kompozice dvou a více znaků, které spolu tvoří skupinu, která bude vysázena jako celek za účelem lepšího vzhledu (např. skupina dvou písmen „fiÿ). TEX se také snaží objekty ze zdrojového textu poskládat do nejlepších možných stránek a co nejhezčích stránek8 . TEX svoje výstupy prezentuje v jednotném, na výstupním zařízení nezávislém formátu Device Independent (DVI). Jde o popis vizuálního rozvržení stránky, který není závislý na tom, zde bude zobrazen jako stránka na tiskárně, obrázek nebo zobrazen na monitoru. Fonty použité v dokumentu nejsou jeho součástí, jsou zde pouze odkazy. O realizaci kreseb jednotlivých znaků se postarají až tzv. dvi–ovladače. Fomát DVI slouží jako zdroj pro další konvertory, převážně do dvou základních pre–pressových standardů, PostScript a PDF. Ty jsou již určeny pro konečné zpracování, tedy k tisku nebo zobrazení na různých zařízeních. Interpret je uložen buď přímo v hardwaru vybaveným RIP9 nebo pro aplikační zpracování např. programy GhostScript či Acrobat Distiller. Dohromady s programem pro definici fontů pro TEX nazvaný METAFONT, vzniklo řešení dvou problémů, které byly do té doby jen těžko řešitelné – každý si mohl napsat velmi kvalitní knihu s přiměřeným množstvím stráveného času a za druhé vzniklý dokument vypadal stejně na všech výstupních zařízeních. K samotnému programu TEX se pak během vývoje přidaly nástavby, které značně zjedodušovaly práci s mírně „syrovýmÿ TEXem. Tyto nástavby jsou vlastně jen balíky maker, s předdefinovanými vzhledy dokumentu a někrými nástroji. Tyto nástavby pak TEX používají jen jako sázecí program. Mezi nejrozšířenější patří LATEX, kde najdeme nástroje pro sazbu nadpisů, vzorců, tabulek, obrázků, poznámek pod čarou, obsahu rejstříku atd. Další nástavby jsou například balíky plainTeX, AMS–TeX, AMS–LaTeX a LAMS–TeX. Vznikly také editory pro práci s TEXem, které práci s ním přibližují více k WYSIWYG editorům, například GNU TeXmacs který je distribuován zdarma pro platformy Windows i Unix. Donald Knuth dal své programy všem zdarma k užívání, takže TEX je dnes velmi rozšířený, nejvíce v akademické sféře, kde jsou využity schopnost psát složité matematické či fyzikální výrazy a jiné povinné atributy odborných prací. 7
Výrazově zcela přesně bych měl v této práci psát o převodu z formátu LATEX, neboť samotný TEX využívá málokdo. Řešení tohoto problému je tedy logicky založeno na práci s formátem LATEX. Tam kde to nebude nutné odlišit nebo přesně určit zda je vstupní soubor ve formátu TEX nebo LATEX (tedy s nějakými makry či styly), přepokládám, že vstupní soubor je formátu LATEX. Může tedy obsahovat i jiné značky než definované v „holémÿ TEXu. 8 „Škaredostÿ dokumentu se vyjadřuje podle paradigmatu „boxi–glue–penaltyÿ 9 Raster Image Processor - program zajišťující vykreslení specifikovaných objektů na stránce
21
TEX je zcela programově i platformově nezávislý, a jeho poslední verze z roku 1989 je autorem fixována a nebude do budoucna dále vyvíjena. Dokument, který byl od tohoto data připraven nebo teprve vznikne, bude TEXem zpracovatelný se zcela stejným výsledkem třeba i za mnoho let. Nevýhodou a důvodem k přehlížení ze strany běžných uživatelů je fakt, že naučit se a používat TEX chvíli trvá. Psaní v TEXu připomíná programování, se také píše „zdrojový textÿ, ten se přeloží a z chybového hlášení se poznají místa, kde je potřeba ještě něco upravit. Většina uživatelů na tento přístup není ochotna přistoupit a raději píší své krátké a jednoduché dokumenty v nějakém WYSIWIG programu.
3.4
Shrnutí kapitoly
Chtěl bych zde upozornit, že v této kapitole je při hodnocení kvality i doporučovaném obsahu dokumentace použit často můj subjektivní názor. Jde o důsledek toho, že jsem k dané problematice nedokázal sehnat žádnou odpovídající literaturu, která by se tématem do hloubky zabývala. Stejně tak jsem nenašel v knihovnách ani na Internetu nějaká komplexní doporučení nebo zákonné normy. Zde zmíněná doporučení jsem čerpal jak z obsahů dokumentací mnoha programů i větších systémů (např. uživatelské dokumentace UISu), tak z mnoha případů, kdy jsem dokumentaci potřeboval a nebyla k dispozici, nebo byla zcela nepoužitelná. Porovnávání kvality jiných dokumentací programů a častých otázek uživatelů jsem pak odvodil co by mohlo být přínosem pro uživatele. Dále pak jako autor několika větších programových celků, na kterých se podílelo více lidí, jsem definoval další pravidla a postupy, které se osvědčily nebo zpětně se ukázaly jako chybějící. Jako vhodné vidím zavedení nějaké přednášku či cvičení, jak psát dokumentaci, nápovědy a manuály k programům na vysokých školách, které se programováním zabývají. Existují sice mnohá technická řešení pomáhající při psaní dokumentace, ale nikde není žádný návod, co má být obsahem této dokumentace. Celkově musím shrnout, že úroveň dokumentace určuje nemalým dílem kvalitu celého programu a kromě samotné funkčnosti se podílí na uživatelově spokojenosti. Dokonalá dokumentace musí být úplná, přesná a aktuální dále pak čtivá, vždy a snadno dostupná a má být čtenářovým pomocníkem a rádcem. Dokumentace je často opomíjena nebo odsouvána na vedlejší kolej, neboť z krátkodobého hlediska není pro program žádným přínosem. Navíc splnění předchozích požadavků si žádá nemalý čas a investice v podobě lidských zdrojů. Toto opomíjení je však strategickou chybou, která časem přináší mnohé problémy jak programátorům při ladění, tak uživatelům při používání programů.
22
4
Značkovací jazyk XML
XML je zkratkou pro anglický název eXtended Markup Language, což v překladu znamená „rozšířený značkovací jazykÿ. V následující kapitole pojednávám o tom, jaké jsou jeho vlastnosti a proč je tento jazyk často užívaným řešením při přenosu informací. Dále je potřebné se zmínit o formátech s XML spojených a jejich praktickém využití s ohledem na téma této práce.
4.1
Předchůdci XML
Předchůdcem jazyka XML byl formát Standard Generalized Markup Language (SGML), který byl v osmdesátých letech minulého století vyvinut v rámci projektu Open Document Architecture. Jako standard ISO byl schválen v roce 1986. Vyvíjen byl již od konce šedesátých let jako nástroj pro zpracování různorodých dokumentů v elektronické podobě se dvěma základními vlastnostmi – zachováním čitelnosti formátu i pro člověka (a to i po značné době od jeho zavedení) a zároveň jeho snadné strojové zpracování. Z těchto podmínek pak vyplývala nutná nezávislost na platformě, aplikaci nebo výrobci, značná obecnost a flexibilita. Stěžejním bodem nalezeného řešení bylo použití značkovacího jazyka – markup language. Slovo »markup« se původně vztahuje ke značkám vepisovaným redaktorem do rukopisu označujících, jak má být výsledný dokument formátován. Podobně tento formát pomocí speciálních značek, které obklopují zobrazovaný text, určuje strukturu dokumentu. Celý dokument je tak pomocí značek (tagů) rozdělen do částí – elementů, které mohou mít svoje pojmenování, vlastnosti a vzájemné vztahy. Tyto názvy elementů i vztahy jsou definovány pro každý dokument zvlášť v samostatném souboru – definici typu dokumentu (DTD). Dokument, na rozdíl od prezentačních jazyků však nijak neřeší formu zobrazování daných elementů, tu si můžeme určit až v závislosti na požadovaném výstupu. Výsledný formát SGML byl velmi komplexní, zahrnoval v sobě mnoho různých standardů pro formáty dat, architekturu předávání, zabezpečení informací, spoustu volitelných parametrů – počínaje maximální délkou názvů elementů a konče určením znaků použitelných jako oddělovače značek od textu. Už v jeho návrhu se s jeho nasazením počítalo spíš do rozsáhlých vládních projektů nebo v průmyslu, kde tato vysoká univerzálnost, komplexnost a složitá implementace nevadila. Díky těmto vlastnotem tento formát nebyl příliš rozšířen, neboť využití pro menší projekty nebylo praktické. V současné době je asi nejznámější aplikací SGML velmi jednoduchý jazyk HTML (Hypertext Markup Language), který je používán od pro tvorbu webových stránek v rámci internetové služby World Wide Web.
4.2
Vznik XML
První verze jazyka XML vnikla začátkem roku 1998 jako výsledek práce skupiny „XML Working Groupÿ pod patronátem konsorcia W3C. Jazyk vycházel z návrhu
23
SGML, ale přinášel oproti původnímu návrhu mnohá zjednodušení (např. některé byly parametry již striktně určeny, přísnější syntaxe), která byla přijata na základě praktických zkušeností s používáním SGML. Také se zohlednily vlastnosti v té době již velmi rozšířeného a dobře přijatého jazyka HTML, který však nevyhovoval obecnějšímu využití. Další požadavky na nový jazyk byly kromě širokého použití na Internetu také čitelnost, stručnost a metodická jasnost při vytváření a kontrole správnosti dokumentu (tzv. „well–formedÿ dokumenty). Daná zjednodušení umožnila mnohem snazší a levnější vývoj aplikací, které umožňují s XML pracovat, čímž se odbourala poslední překážka většího rozšíření tohoto jazyka mezi velké i malé aplikace. Během následujících let byl tento jazyk mírně upravován a doděláván – poslední aktualizací jazyka je verze 1.1. z února 2004 – avšak hlavní vlastnosti a výhody použití zůstaly stejné.
4.3
Vlastnosti XML
Z předchozího textu již známe vlastnosti, které XML zdědilo od SGML – je to formát počítačově zpracovatelného, ale lidmi čitelného textového dokument, ve kterém je struktura dána speciálním značkami – tagy. Další základní vlastnost jazyka XML, která je daná již od počátku, je jeho jazyková univerzálnost. V XML můžeme vytvářet dokumenty nejenom v angličtině, ale bez problému ve všech ostatních jazycích a dokonce lze vytvářet dokumenty, které obsahují texty ve více jazycích najednou. Kódování znaků je v každém dokumentu přesně určeno, jako výchozí znaková sada se používá Unicode10 , která umožňuje psát znaky všech světových jazyků bez hrozby kolizí nebo složitých převodů. XML umožňuje definovat vlastní sadu značek, které budou v dokumentu obsaženy, a jejich definici zapsat pomocí DTD. Tento zápis správné struktury dokumentu umožňuje automatickou kontrolu, zda nějaký dokument má danou strukturu, kterou dané DTD popisuje. Parser – program, který kontrolu provádí – může velmi rychle a jednoduše najít chyby ve struktuře dokumentu, což je při přenosech informací zásadní vlastnost. Díky tomu, že v XML dokumentu je definována pouze struktura textu a žádné informace, které mají význam při zobrazení dokumentu, je možné v tomto dokumentu jednoduše vyhledávat a to i podle významu a umístění hledané fráze. Tato absence formátovacích značek také dovoluje si zobrazit XML dokument na libovolném výstupu, přesně dle potřeb uživatele. Pro potřebu formátovaných výstupů byly navrženy stylové jazyky, které umožňují definovat, jak se mají jednotlivé části zobrazit. Souboru těchto pravidel pro daný dokument se říká styl a mezi nejrozšířenější jazyky pro vytváření stylů patří kaskádové styly Cascading Style Sheets (CSS) a o něco složitější jazyk eXtensible Stylesheet Language (XSL, více o nich v následující podkapitole). Výhodou používání stylů je, že jeden styl můžeme aplikovat na 10
Byl přijat i za mezinárodní standard jako norma ISO 10646.
24
mnoho dokumentů stejného typu a dosáhnout tak jednotného formátování těchto dokumentů při jejich zobrazení. Stejně tak na jeden XML dokument můžeme aplikovat různé styly pro různé typy výstupů (obrazovka, tiskárna).
4.4
Formáty spojené s XML
Jak vyplývá z předchozího textu, XML je velice univerzálním formátem. K jeho praktickému využití je potřeba jej aplikovat a specializovat na konkrétní typ využití. Uvádím stručný přehled existujících jazyků odvozených z XML jako ukázky toho, jak je tento formát v praxi využíván. XHTML - Extensible HyperText Markup Language Tento jazyk je novou verzí jazyka HTML, jehož vývoj byl ukončen a nahrazen právě XHTML11 . Průběh transformace znázorňuje obrázek G. . Menšími úpravami půodního HTML a zpřísněním jeho syntaxe tento jazyk zůstal stejně popisným i s většnou původních zanček, ale je možné ho automaticky zpracovat, tak jako ostatní XML dokumenty. To umožňuje autorům stránek jejich jednoduchou validaci oproti vydanému DTD, zobrazování těchto stránek i na jiných zařízeních než jsou klasické počítače (např. v mobilních telefonech nebo PDA) jenom pomocí stylů. XSL - Extensible Stylesheet Language Jazyk XSL byl původně určen pro formátování elementů dokumentu, podobně jako tehdy již existující jazyk CSS. Během vývoje však z tohoto jazyka byly odděleny některé části do samostatných jazyků a v dnešní době tak XSL obsahuje „rodinuÿ tří jazyků. První částí je XSL Transformations (XSLT), který umožňuje psát styly na transformování XML dokumentů např. do HTML, jiných XML či PDF dokumentů. Jazyk umožňuje napsat jakýkoliv převaděč XML dokumentů do jiného libovolného formátu12 . Průběh transformace znázorňuje obrázek G. Další částí XSL je jazyk XSL Formatting Object (XSL FO, někdy jen XSL), který umožňuje popsat vzhled dokumentu na výstupu. K dispozici jsou zde např. definice okrajů stránky, barvy a velikosti písma, zarovnání a rozložení textu. Tedy vše co je potřeba k definování formátovacích atributů výstupu s vysokou typografickou kvalitou. Třetí částí je XML Path Language (XPath), který je používán jazykem XSLT k popisu toho, jak přistupovat k částem XML dokumentu. Umožňuje adresovat jednotlivé části dokumentu jak podle názvu elementu, tak podle jeho pozice v dokumentu nebo podle jeho atributů. 11 12
Ukázka XHTML viz příloha F. Ukázka XSLT stylu viz příloha E.
25
Obr. 1: Znázornění průběhu transfromace pomocí XSLT
XML Schema Pro zápis typu dokumentu se od počátku existence XML používal jazyk DTD. Tento byl ale časem shledán nedostačujícím a navíc jeho lepšímu zpracování bránilo to, že nebyl v XML formátu. Byl tedy vyvinut nový formát – XML Schema, v němž každý DTD dokument byl zapsán v XML. Tento nový jazyk byl sice o hodně složitější, ale přinesl tři zásadní vlastnosti – sjednotil syntaxi definic do standardní XML formy, přidal možnost definovat jmenné prostory a umožnění určit atributům datové typy. XLink - XML Linking Language Jazyk je určen pro vytváření odkazů v XML dokumentech na jiné dokumenty, a to jak interní – uložené na stejném médiu – nebo externí – přístupné na Internetu. Odkazy definované tímto jazykem mohou odkazovat i na více dokumentů zároveň, nebo mohou být obousměrné. Dalším důležitým rysem XLinku je možnost přiřazení typu jednotlivým odkazům. Samotné odkazy tak mohou přímo nést nějakou informaci. I když možnosti odkazování jsou mnohem lepší než v původním HTML, tento jazyk, narozdíl od ostatních zde zmiňovaných, nebyl příliš dobře přijat a jeho praktické využití je v současné době minimální.
26
XPointer Jazyk umožňuje jednoznačnou identifikaci libovolné části XML dokumentu a je velmi podobný jazykům XPath a XLink, jejichž vlastnosti spojuje. Umí vytvářet odkazy na sekce pomocí jednoznačného identifikátoru – atributu »id«. Stejně tak je možné pomocí tohoto jazyka definovat výsek dokumentu na základě struktury nebo jména elementu, popřípadě jejich obsahu. RDF - Resource Description Framework Jazyk RDF je určen pro popis metadat13 , který klade důraz na univerzálnost a umožňuje jednoduché strojové zpracování a výměnu informací mezi aplikacemi. Metadata jsou zapisována ve formě výrazů subjekt–predikát–objekt (tzv. „tripleÿ). Predikátem je nějaká vlastnost vyjadřující vztah mezi subjektem a objektem. RDF je možné využít zejména v oblastech vyhledávaní a katalogizování informací, hodnocení obsahu, sdružování více různých stránek do logického celku, pro popis intelektuálních vlastnických práv webových stránek a v mnoha dalších případech. Příkladem použitím jazyka RDF je velmi rozšířený formát RDF Site Summary (RSS), který se používá k popisu obsahu webových stránek, tzv. RSS kanál. Umožňuje publikování seznamu odkazů na články s dalšími informacemi, které je blíže popisují – např. stručný obsah – bez nutnosti stahovat celý obsah ze serveru. SVG - Scalable Vector Graphics Škálovatelná vektorová grafika – tak zní překlad názvu tohoto jazyka – je jazyk, který se používá pro popis vektorové grafiky v XML. Popis je dán pomocí grafických objektů – vektorových, rastrových nebo textových – které mohou být formátovány pomocí CSS stylů a polohovány pomocí obecných transformací. Grafika kromě statických obrázků může být i animovaná a interaktivní. Využití má především na webových stránkách, kde je zatím jediným formátem pro přenos a zobrazení vektorové grafiky, i když její implementace zatím není častá. Teprve novější verze prohlížečů Firefox a Opera umí tento formát zobrazovat již bez dodatečných modulů. DocBook DocBook je jedním z velmi rozšířených otevřených řešení založených na XML, který slouží k zápisu textových dokumentů. Samotná definice je pouze jeden soubor s DTD, který definuje použití elementů a jejich atributů. Formát DocBook je primárně určen pro psaní technické dokumentace, např. pro software, ale lze v něm psát jakékoliv články, knihy apod. Co činí DocBook zajímavým, je jeho značná rozšířenost a široká podpora. Díky tomu, že formát používají milióny uživatelů a zároveň je podporován velkými společnostmi a komunitami v oboru IT (např. Novell, Digital, Hewlett–Packard, O’Reilly, 13
Informace o informacích; metadata popisují nějakou možinu zdrojových dat.
27
PHP, FreeBSD), je snadné si pro DocBook zdarma stáhnout různé styly, převaděče do mnoha jiných formátů nebo textové editory přímo určené pro něj (např. oXygen, XMLmind). Existují též nástroje určené pro převod dokumentace ze zdrojových kódů různých programovacích jazyků do DocBooku. OpenDocument Dalším rozšířeným otevřeným formátem pro dokumenty je Open Document Format (ODF), který je určen pro kancelářský software. Tento souborový formát je určen pro ukládání a výměnu dokumentů vytvořených kancelářskými aplikacemi, tedy kromě textových dokumentů zahrnuje i prezentace, tabulky, grafy a databáze. Účelem tohoto formátu je nabídnout alternativu uzavřeným (a velmi rozšířeným) formátům kancelářského balíku Microsoft Office14 . Výhodou používání tohoto formátu je pro uživatele nezávislost na konkrétním dodavateli software, což bylo u většiny kancelářských aplikací obvyklé a velmi často také těmito dodavateli zneužíváno. Typickým nešvarem těchto dodavatelů kancelářských aplikací bylo utajování formátů a následná nemožnost převodu do jiných formátů, z čehož vyplývala závislost na dodané aplikaci. Dále pak zvyšování ceny těchto aplikací nebo změna licencování nových verzí. Od všech těchto neblahých vlastností se snaží odprostit právě formát ODF, který není závislý na konkrétní aplikaci nebo výrobci. Navíc od května tohoto roku je formát ODF standardizován Mezinárodní organizací pro normalizaci jako standard ISO/IEC 26300, což by mělo pomoci rozšíření tohoto formátu i do větších organizací a státní správy.
4.5
Nástroje pro práci s XML
Žádný formát dokumentů se nemůže stát široce oblíbený a používaný bez existence kvalitních nástrojů pro něj určených. Formát XML v tomto ohledu není žádnou výjimkou, i když svým zaměřením jako formát pro výměnu informací určuje i trochu jiné nástroje, než v případě formátů uživatelských. Spíše než pro každodenní práci mnoha laických uživatelů je XML formát svým zaměřením určen pro programátory, techniky, databázové specialisty, webové designéry, správce systému a jiná zaměstnání spojená se světem informačních technologií. Tomuto zaměření se také přizpůsobují nástroje určené pro práci s XML. Hlavním úkolem následující podkapitoly je ukázat současné možnosti práce s XML tak, jak je mohou využívat výše jmenovaní. 14 Produkty firmy Microsoft sice umí ukládat svoje dokumenty do formátu Microsoft Office Open XML, ovšem jeho implementace je licencovaná.
28
XML a XSLT parsery Parsery XML dokumentů jsou tím nejzákladnějším nástrojem pro prácí s XML. Jejich kvalita určuje snadnost a dostupnost celé řady dalších technologií spojených s XML formátem. Parser XML se používá pro syntaktickou analýzu dokumentu a následné zpracování. Parser tedy dokument načte, popřípadě zkontroluje jeho validitu oproti nějakému DTD. Zpřístupnění obsahu dokumentu má obecně dva zcela odlišné přístupy, definující dvě zcela odlišná rozhraní (API) – SAX a DOM. SAX - Simple API for XML SAX je rozhraní řízené událostmi („event drivenÿ), které jsou generovány hned při zpracování vstupního dokumentu. Události mají různé typy a jsou vyvolávány na základě prvků vstupního dokumentu, např. existuje událost pro začátek značky, obsah elementu, instrukci, atd. Aplikace využívající toto rozhraní musí pouze u SAX parseru zaregistrovat funkce, které se mají volat pro jednotlivé typy událostí. Výhodou je jednoduchost, rychlost, malá prostorová náročnost a možnost serializace aplikací (aplikace mohou fungovat jako řetěz kde výstupy jedné aplikace jsou vstupem další). Nevýhodou je vyšší složitost pro tvůrce aplikací než u rozhraní DOM, protože celý dokument je parsován pouze jednou a není nijak ukládána struktura dokumentu, takže při zpracování na ni nemůže být brán zřetel. Rozhraní vzniklo společným úsilím vývojářů z diskusní skupiny xml–dev a je de facto standardem. DOM - Document Object Model Toto rozhraní si na rozdíl od SAX načte celý dokument nejdříve do paměti a pak ho zpřístupní uživatelům pomocí stromu dokumentu, který obsahuje jako uzly elementy. Struktura dokumentu je tedy obsažena ve stromu. Pak je možné dokument jednoduše procházet i měnit a to i opakovaně a odkazovat se na elementy v závislosti na struktuře, což umožňuje efektivní přístup k obsahům elementů. Nevýhodou tohoto rozhraní je značná náročnost na paměť, takže tento přístup je pomalejší než SAX, ale má lepší funkcionalitu pro tvůrce aplikací. Používá se například pro HTML prohlížeče nebo editory dokumentů, tedy tam kde se dokument nějak mění nebo se znovu přistupuje k jeho částem. Rozhraní DOM je standardem z dílny konsorcia W3C. Původně byl DOM vytvořen zejména proto, aby nové verze prohlížečů podporující XML používaly stejný objektový model pro přístup k dokumentu ze skriptovacích jazyků jako JavaScript. Rozhraní DOM podporují oba majoritní prohližeče Internet Explorer i Mozilla. Implementace XML a XSLT parserů Dobrý parser značně ulehčuje práci s XML dokumenty a programátor tak nemusí psát žádný kód, související s XML. Parser mu totiž pouze dodá v nějaké podobě data získaná z dokumentu. Implementace těchto parserů není nijak jednoduchá a trvá dlouhou dobu, proto je většinou zastřešena nějakou větší organizací či firmou nebo alespoň velkou komunitou.
29
Zde uvedu základní vlastnosti nejrozšířenějších parserů, podle jejich původu, včetně krátkého přiblížení, co daný parser nabízí. Microsoft - MSXML parser Spolu s internetovým prohlížečem Internet Explorer 5 firma Microsoft implementovala první verzi vlastního XML parseru – MSXML parser. Vývoj tohoto parseru stálé probíhá, aktuální verze 6.0 je součástí systému MS Windows a obsahuje všechny důležité vlastnosti s několika rozšířeními. Není tedy pouhým parserem, ale slouží jako hlavní komponenta pro přístup k XML formátům. Parser implementuje DOM i SAX rozhraní, podporu jmenných prostorů a podporu pro jazyky JavaScript, VBScript, Perl, VB, Java, C++ a další (díky tomu, že parser je realizován jako COM objekt). Mezi funkční rozšíření nad klasický rámec parseru patří zabudovaná podpora XSLT, XPath a vlastního výměnného formátu XDR. Omezením je jeho použití jen pro operační systém Windows. Apache group Další tři open–sourcové programy jsou z dílny nadace Apache, která je velmi uspěšným sdružením v oblasti internetových technologií. Toto sdružení vydává své produkty zdarma pod licencí Apache Software Licence. První z nich je XML parser Xerces. Je napsán v jazyce Java a podporuje obě rozhraní DOM i SAX. Umožňuje validaci dokumentu a má dobré možnosti nastavení a také podporuje jmenné prostory. Další velmi používaný program od skupiny Apache je XSLT procesor Xalan. Kromě XSLT umí pracovat i z XPath výrazy a je implementován v jazycích Java a C++. Ve své výchozí instalaci spolupracuje právě s parserem Xerces, ale je možné ho použít i s jiným parserem. Třetím je Formatting Objects Processor (FOP), který je prvním procesorem pracující s formátem XSL–FO. Implementován byl takéž v Javě a dokáže generovat grafické výstupy do formátů PDF, PCL, PS, SVG a dalších. Expat, XP a XT Jeden z nejvýraznějších propagátorů XML byl a stále je James Clark. Kromě členství v různých komisích W3C napsal mnoho programů pro práci s XML. Zde zmíním pouze tři nejdůležitější. Nejdůležitějším z nich je Expat, XML parser distribuovaný jako knihovna napsaná v jazyku C. Je to jeden z prvních open–sourcových parserů (první verze byla zveřejněna již v roce 1998), díky čemuž byl zabudován do mnoha dalších otevřených projektů jako HTTP Apache server a programovacích jazyků Perl, Python či PHP. Ve své původní variantě podporoval pouze SAX rozhraní, ale díky později přidaným nástavbám k němu je možné v některých jazycích používat i DOM. Je velmi rychlý, podporovaný na většině platforem a zcela zdarma. Clark C implementoval i parser pro jazyk Java, nazvaný stručně XP. Neumí sice validaci dokumentů, má omezenou podporu pro různé znakové sady (např. nepodporuje české normy), ale je velmi rychlý a stále se používá.
30
Clark je také autorem jednoho z prvních procesorů jazyka XSLT pojmenovaný XT, který je stále ve vývoji. Procesor je napsaný v Javě a podporuje jak SAX tak DOM rozhraní. Oblíbený je hlavně díky své rychlosti.
31
5
Regulární výrazy
Regulární výraz (regular expression), označovaný též zkráceně jako regexp či regex je speciální řetězec znaků, který představuje určitý vzor (masku) pro textové řetězce. Tento vzor se pak použije pro hledání daného řetězce v textu. Regulární výrazy pomocí daných operátorů umožňují manipulaci s částmi textu, např. nahrazení některých nalezených částí jinými. Důvodem jejich rozšíření a jejich základní vlastností je obecnost a značná rychlost. Vzhledem k tomu, že regulární výrazy jsou kostrou navrženého řešení, podrobněji je popíšu.
5.1
Vznik regulárních výrazů
Původ regulárních výrazů leží překvapivě v biologii. V roce 1940 Warren McCulloch a Walter Pitts popsali neurony jako malé jednoduché automaty a pomocí tohoto popisu modelovali nervový systém. Jejich práci pak přepsal matematik Stephen Kleene do notace nazvané regulární množiny. Odtud už byl jen krok k současným regulárním výrazům, které navrhl Ken Thompson při psaní vyhledávacího nástroje grep. Díky implementaci do standardního nástroje grep jsou regulární výrazy rozšířené hlavně na platformě Unix, kde jsou základem pro další programy jako ed, vi či Emacs.
5.2
Formální definice
Definici regulárních výrazů najdeme v teorii formálních jazyků a automatů, viz (Habiballa, 2003; Češka, 2003). V této teorii se zkoumají a klasifikují formální jazyky a pracuje s abstraktními matematickými stroji – automaty. Definice takového konečného deterministického automatu je tato: Deterministickým konečným automatem (DKA) nazýváme každou pětici A = P (Q, , δ, q0 , F ), kde • Q je konečná neprázdná množina (množina stavů, stavový prostor) P • konečná neprázdná množina (množina vstupních symbolů, vstupní abeceda) P • δ je zobrazení Q × → Q (přechodová funkce) • q0 ∈ Q (počáteční stav, iniciální stav) • F ⊆ Q (množina koncových stavů, cílová množina). P P Přechodovou funkci δ : Q × → Q konečného automatu A = (Q, , δ, q0 , F ) P rozšíříme na zobecněnou přechodovou funkci δ ∗ : Q × ∗ → Q následovně: 1. δ ∗ (q, e) = q, ∀q ∈ Q P P 2. δ ∗ (q, wa) = δ(δ ∗ (q, w), a), ∀q ∈ Q, w ∈ ∗ , a ∈ . Každý takový stroj pak popisuje nějakou třídu (vybranou podmnožinu) jazyků, které rozpoznává. Jazyk rozpoznávaný konečným automatem je definován následovně: P Vstupní slovo w = x1 x2 . . . xm ∈ + je rozpoznáváno deterministickým konečným automatem A, jestliže existuje posloupnost stavů qi0 , qi1 , qi2 , . . . , qim taková, že: 32
qik = δ(qik − 1, xik ) a qim ∈ F (stav, ve kterém automat skončil činnost, je koncový stav). Množina všech slov w ∈ ∗ , jež jsou rozpoznávána (přijata) automatem A, tvoří jazyk rozpoznávaný automatem A. Označujeme ho L(A), jazyk rozpoznatelný konečným automatem. P Dále definujeme, že jazyk L (nad abecedou ) je rozpoznatelný konečným automatem, jestliže existuje konečný automat A takový, že L(A)=L. Je možná definice těchto regulárních jazyků pomocí gramatiky, podobně jako čeština definuje gramatikou, které věta je správně česky. Třetím způsobem – kromě automatů a gramatik – je právě zápis pomocí regulárních výrazů. Ještě k výrazu „regulárníÿ. Jazyky, které jsou vytvořeny ze základních symbolů abecedy pouze s pomocí operací sjednocení, zřetězení a iterace a to jejich postupnou aplikací v libovolném počtu a pořadí, nazýváme regulární. Stejně tak automaty, které tyto jazyky rozpoznávají, nazýváme regulární automaty. Regulární výrazy slouží k přehlednějšímu zápisu regulárních jazyk a používají také jen operace sjednocení, zřetězení a iterace a konečné abecedy. Přesná definice je následující: Každý regulární výraz označuje (reprezentuje) konkrétní regulární jazyk. ∅ označuje jazyk ∅, ε označuje jazyk {ε} a označuje jazyk { a } pro libovolné P a∈ Jestliže regulární výraz α označuje L1, a regulární výraz β označuje L2, pak (α + β) označuje jazyk L1∩L2 (α · β) označuje jazyk L1·L2 α∗ označuje jazyk (L1)∗ P
P
kde je neprázdná konečná množina znaků, operace + značí sjednocení jazyků, operace · zřetězení a operace * iteraci jazyka. Proto regulární výrazy generují právě regulární jazyky, laicky řečeno regulární výraz je jen jiným způsobem, jak popisovat P stejnou třídu jazyků. Příkladem regulárního výrazu pro abecedu = {0, 1} je výraz (0 + 1) + (11 + 00 ) + 1, který popisuje jazyk L = { 0001,0111, 1001, 1111 }.
5.3
Implementace a rozšíření
Regulární výrazy můžeme v současné době najít téměř ve všech moderních programovacích jazycích (C#, Java, Visual Basic .NET, Perl, PHP, Javascript aj.) a mnoha programech zvláště pro platformu Unix (vi, sed, awk). Pro regulární výrazy existují různé implementace, lišící se v různých přidaných vlastnostech. Nejznámější tři odnože, které si přiblížíme jsou původní Unixová, POSIX a Perl–compatible. Každá z těchto rozšířených syntaxí nijak nerozšiřuje možnosti regulárních jazyků, jenom zjednodušuje zápis složitějších výrazů.
33
Unixové implementace regulárních výrazů Praktická implementace regulárních výrazů již od počátku v sobě kromě sjednocení, zřetězení a iterace obsahuje několik dalších operátorů a speciálních výrazů a umožňuje jednodušeji zapsat tyto výrazy: • konečný seznam znaků (tzv. třídy) • začátek a konec řádky • libovolný jeden znak kromě nové řádky Typickou vlastností, kterou je ještě vhodné popsat, je hladovost kvantifikátorů. Jde o to, že v případě, kdy je možné při porovnání vybrat různě velkou část řetězce, si regulární výraz vybere tu nejdelší možnost. Příklad pokud máme text obsahující „011101110111ÿ a hledáme pomocí výrazu „0*111ÿ dostaneme zpět celý řetězec byť by vyhovovala i jeho úvodní část „0111ÿ. POSIX rozšířené regulární výrazy (POSIX extended) Tento standard přinesl mnohá další rozšíření regulárních výrazů, mezi přidané vlastnosti patří nové definice předdefinovaných tříd a kategorií znaků. Tyto speciální definice se zapisují do hranatých závorek s dvojtečkami. Přehled a význam je v následující tabulce: Tab. 1: Třídy znaků definované v POSIX standardu
Popis velká písmena malá písmena malá a velká písmena čísla, malá a velká písmena čísla čísla v šestnáctkové soustavě interpunkce mezera a tabulátor bílé znaky kontrolní znaky tisknutelné znaky tisknutelné znaky a mezera
Také byly přidány tři nové operátory: • + – pro opakování jednoho a více znaků • ? – pro nepovinný výskyt jednoho nebo více znaků • | – pro výběr mezi množinami před a za operátorem A protože znaky (,),[,],.,*,?,+,^ a $ se používají jako speciální symboly, musí být před nimi v místě, kde je chceme použít jako obyčejné znaky, vždy zpětné lomítko. 34
Příkladem POSIX výrazu je zápis pro kontrolu správnosti emailové adresy: ^[_a-zA-Z0-9\.\-]+@[_a-zA-Z0-9\.\-]+\.[a-zA-Z]{2,4}$
Perl-compatible regulární výrazy (PCRE) V programovacím jazyku Perl je pevně zabudován další interpret regulárních výrazů, pro který se časem vžilo označení PCRE. Přineslo další významná rozšíření oproti POSIX, například vyřešilo problém hladovosti. Pro každý operátor ve výrazu se může určit, zda má být hladový nebo ne. Tento interpret také umožnil psaní komentářů do opravdu složitých výrazů, podporu Unicode, vlastní backtrackingový algoritmus pro nahrazování částí textů, modifikátory (např. pro evaluaci Perlovské syntaxe uvnitř výrazů apod.) S těchto vlastnosti vyplývá, že program označující se jako PCRE by měl v sobě správně zahrnovat i interpretr jazyka Perl. V praxi tomu samozřejmě tak není, pokud je program označován jako PCRE, má se za to že umí „ jenÿ jeho rozšířenou syntaxi (viz tabulka 2). Kromě těchto nových vlastností se jinak zapisují třídy znaků než v POSIX normě, třídy byly nahrazeny metasymboly. Metasymboly jsou sekvence o více než jednom znaku, které mají speciální význam. Pokud znak obráceného lomítka uvedeme před znakem, který není metaznakem, nebo před skupinou znaků, stává se z celé této sekvence metasymbol. Dalším typem metasymbolu mohou být kvantifikátory či rozšířené vzory. Přehled metasymbolů definovaných v PCRE je v tabulce 2. Také bylo odstraněno používání zpětného lomítka před závorkami a zpětné lomítko bylo vyhrazeno jen pro definici nealfanumerických znaků. Mezi největší výhody patří dosud nepřekonaná rychlost při vyhodnocování výrazů.
Popis znak ASCII NUL znak s ordinálním číslem nnn (zadáno osmičkově, max. do \ 377 odpovídá předchozímu n–tému nalezenému podřetězci pípnutí (bell) začátek řetězce znak backspace hranice slova jinde než na hranici slova znak Ctrl+X jeden byte v jakékoliv znakové sadě číslice jiný znak než číslice znak Escape ukončovací symbol k L, U nebo Q znak nové stránky pravdivé za hranicí posledního nalezení vzoru při použití m//g následující znak malými písmeny znak nového řádku pojmenovaný znak (např. \ N{greek:Sigma} pro znak σ) libovolný znak se zadanou vlastností libovolný znak bez zadané vlastnosti následující znaky malými písmeny (do \E) potlačuje metavýznam následujících znaků (do \E) znak návratu vozíku (CR) prázdný znak (mezera, tabulátor apod.) jiný než prázdný znak tabulátor následující znak velkým písmenem následující znaky velkým písmenem (do \E) alfanumerický znak [a-zA-Z 0-9] jiný než alfanumerický znak znak zadaný hexadecimálně znak v znakové sadě Unicode konec řetězce konec řetězce nebo pozice před koncem řádku na konci řetězce
36
6 6.1
Analýza převodu dokumentace UIS Univerzitní informační systém MZLU
Univerzitní informační systém (UIS) je komplexní portálový informační systém sloužící pro většinu aktivit celé univerzity, která má v současné době přes osm tisíc studentů a více než pět set učitelů. Zahrnuje správu majetku a hardwaru, stravování, administraci vzdělávací i výzkumné činnosti a mnoho dalších agend, které jsou pro chod univerzity potřeba. Univerzitní informační systém je přístupný pomocí webového prohlížeče komukoliv, kdo je připojen na síť Internet. UIS obsahuje dvě části – veřejnou a neveřejnou. Ve veřejné části si každý návštěvník může prohlédnout základní informace o MZLU v Brně (např. studijní programy, obory a vyučované předměty, základní informace o zaměstnancích, seznam pracovišť, projekty vedené na univerzitě). Z veřejné části je přístupný i návod pro první přihlášení do UIS a seznam systémových integrátorů jednotlivých pracovišť. Do neveřejné části UIS se dostanou jen registrovaní uživatelé (studenti, zaměstnanci, akademičtí pracovníci) a mají možnost používat značné množství aplikací. Některé jsou přístupné všem uživatelům (např. poštovní schránka, dokumentový server, změna preferencí uživatele, kontrola osobních údajů), některé jen zaměstnancům s určitou rolí , která jim v daném systému byla přidělena.
6.2
Dokumentace UIS v současné době
Oficiální dokumentaci pro UIS píše v současné době jediná osoba, dokumentátorka, která má na starosti kompletní uživatelskou dokumentaci celého systému. Tato osoba není vývojářem systému a jeho dokumentaci tak tvoří a upravuje na základě vlastní praxe s používáním systému, poznámek od uživatelů a seznamu přidané či změněné funkčnosti od vývojového týmu. Také se účastní školení uživatelů na všech úrovních, která jsou pořádány vývojovým týmem. Informace jsou rozděleny do devíti samostatných souborů z nichž každý obsahuje část určenou nějaké roli, kterou může uživatel v informačním systému mít, a jsou to: • Všichni uživatelé • Student • Učitel • Věda a výzkum • Studijní referentka • Přijímací řízení • Koleje a menzy • Portál vedoucího • Systémový integrátor
37
Z přehledu vyplývá značně široký záběr informací, které dokumentátorka musí nabýt a obsáhnout tak, aby byla schopna napsat užitečnou dokumentaci. Je celkem obdivuhodné, že tuto práci zvládá jedna osoba, která se tak stává jednou z mála osob, jenž má přehled o celém informačním systému. Vlastní práce dokumentátory pak spočívá v přípravě TEXovských dokumentů, opravě chyb, aktualizaci dokumentace dle konference pro vývojáře a úprav stávající podoby dokumentace na základě připomínek od uživatelů. Dokumentace je přístupná všem ke stažení uživatelům informačního systému v podobě souborů ve formátu PDF on–line. Výhodou je častá aktualizace a přístupnost kdekoliv z Internetu. Kromě těchto dokumentů mají uživatelé k dispozici – každá role svou – tzv. referenční kartu uživatele, která na jednom oboustranně popsaném listu stručně a přehledně seznamuje začínající uživatele s možnostmi, které jim informační systém nabízí a ukazuje jim postup při řešení obvyklých situací. Kromě této uživatelské dokumentace existují také jiné různé dokumenty jako „Dokumentace k technologiím řízeným z UISÿ či informační materiály pro nové zaměstnance nebo potencionální zákazníky, také dostupná on–line. Programátorská dokumentace je zatím jen plánovaná a měla by ji zpracovávat také tato dokumentátorka.
6.3
Požadované vlastnosti řešení
Z uvedeného tedy vyvodíme jaké by měly být požadavky na dané řešení. Obecně lze říci, že program nebude spouštěn nijak často, jen při změně dokumentace. Používán bude nejspíše dokumentátorkou nebo vývojáři systému. Z těchto předpokladů vyplývá, že nejsou kladeny žádné velké požadavky ani na výkon, ani na uživatelskou přívětivost. Na vstupu daného převodu budou očekávány TEXové zdrojové soubory s uvedenou dokumentací. Ty většinou obsahují kromě textu také obrázky, tabulky, seznamy a rejstříky. Uvedené řešení tyto prvky musí umět zpracovat. Složitější elementy jako například matematické rovnice v dokumentaci spíše neočekáváme a jejich zpracování není nutné. Pokud by tento ojedinělý případ nastal, lze to vyřešit převodem těchto výrazů na obrázky a ty pak v dokumentaci použít. Nebo lze převést TEXovský zápis do formátu MathML15 , který je široce podporován a jeho vizualizaci jde programově zajistit. Rozhodně však práce s matematickými výrazy není rozhodujícím kritériem. Základním požadavkem daného řešení musí být také jeho pozdější modifikovatelnost. Jak jsem již uvedl, TEXovský styl pro psaní uživatelské dokumentace se může měnit a je to více než pravděpodobné, že se tak bude dít relativně často. Stejně tak je téměř jisté, že pro plánovou programátorskou dokumentaci bude styl zcela nový. Z toho vyplývá nutnost oddělit definici, jak se má převod provést, od samotného programu do konfiguračního souboru. Jeho úpravou se pak bude při změně stylu dát měnit i převod do XML. 15
MathML je XML formát na popis matematických výrazů na webových stránkách. Od roku 2001 je doporučením konsorcia W3C a je podporován např. programy Maple nebo Mathematica.
38
UIS je napsán v programovacím jazyku Perl, je tedy vhodné preferovat program napsaný také v tomto jazyku. Není to podmínka nutná, ale řešení ve stejném jazyce by přineslo do budoucna při jeho používání několik výhod. Za prvé jde o samotné úpravy programu. Pro někoho z vývojového týmu budou snáze proveditelné, když budou napsány ve stejném jazyce, s jakým denně pracuje. Další výhoda je spojená s budoucím využitím programu. V případě použití Perlu by bylo možné ho přímo v případě potřeby zakomponovat přímo do systému. Posledním omezením je požadavek na výstupní kódování znaků. Jelikož v UIS je používáno kódování ISO–8859–2, musí být výstup ve stejném kódování nebo alespoň ve takovém, ze kterého se dá bez ztráty informací do uvedeného převést. Což bohužel vylučuje například použití sady Unicode, která by byla vhodná.
6.4
Možné varianty a výběr řešení
Při hledání řešení jsem se zaměřil na dvě varianty. Buď najít již hotové řešení od jiného autora a s tím, že ho v ořípadě potřeby upravím. Druhou variantou je dané řešení naprogramovat vlastními silami. Obě varianty musí splňovat výše uvedené požadavky a v první variantě je ještě vhodné, aby bylo distribuováno jako open source. Nástrojů pro převod z TeX nebo LaTeX formátu do HTML existuje celkem nepřeberné množství a jsou teoreticky použitelné pro dané řešení. Převod by pak probíhal dvoufázově, nejdříve z TEXu do HTML a následně do XML. Jsou ovšem zaměřené spíše na převody správné vizuální stránky dokumentů a pro další zpracování (a zachování strukury dokumentu) jsou nevhodné. Dvojí převod by také byl o něco složitější, podařilo se však nalézt dva nástroje, které umožňují přímo převod do XML. Hermes Hermes16 je převaděč z (AMS) LATEXu do sémantického XML s využitím MathML a sady Unicode. Slouží k převodu LATEX dokumentů do podoby zobrazitelné na webu a k archivaci těchto dokumentů. Především je určen pro pro vědecké práce a je dispozici zcela zdarma i se zdrojovými kódy v jazyce C++. Je platformově nezávislý a pro svoji činnost vyžaduje mít nainstalovaný LATEX, XSLT parser a parser Bison. Převod dokumentu probíhá ve čtyřech fázích: • zkopírování zdrojového TEX souboru s vyznačením sémantiky • převod pomocí TeXu do DVI formátu • parsování DVI formátu • vygenerování referenčního XML souboru s přihlédnutím na přidanou sémantiku Tento referenční XML soubor obsahuje kromě vlastního textu také XML slovník. V textu dokáže rozeznávat většinu TEX syntaxe (sekce, tabulky, metadata, 16
Domovská stránka projektu na Internetu http://hermes.roua.org/
39
seznamy) a speciální grafické znaky převádí do jejich ekvivalentu ve znakové sadě Unicode. Seznam podporovaných elementů lze dále rozšiřovat. XML slovník obsahuje definice pro různé oddíly textu s jiným než základním prostředím (např. prostředím pro matematické výrazy). Tyto definice tedy obsahují popis těchto speciálních částí odděleně od hlavního textu a mohou být samostatně zpracování. Zatím je podporovaný jen převod z matematického prostředí do syntaxe MathML. Bohužel díky použití Unicode, programovacímu jazyku C a hlavně netypickému refernčnímu formátu XML na výstupu není vhodný pro hledané řešení. GELLMU Generalized Extensible LATEX-Like Markup (GELLMU)17 je univerzální nástroj pro převod z do značkovacího jazyka SGML a jeho podmnožiny XML. Autorem je William F. Hammond, který jej napsal v programovacím jazyce ELisp. Pro použití GELLMU je třeba mít ještě program Emacs, s nainstalovanou podporou jazyka GNU Emacs Lisp (Elisp) 18 . Dále je pro práci se SGML využit program OpenJade19 . Projekt také rozlišuje tři různé koncepty (režimy) zpracování: základní, rozšířený a regulární. V základním režimu se používá k převodu spíše jednoduchých dokumentů, napsaných s ohledem na omezené vlastnosti tohoto režimu (jenom jednoduché převody, maximálně jeden atribut v elementu atd.) Přesto je možné pomocí příkazu \\newcommand definovat vlastní elementy použité v dokumentu. V rozšířeném režimu se pak plně využívají možnosti vlastního nastavení převodu, v dokumentu mohou být i složitější TEXové výrazy a více atributů . Nejsložitější a také nejvíce obecný je pak režim pojmenpovaný jako regulární. Převod zde zajišťuje více částí, z nich každá je zcela samostaná a jejichž rozdělení je následující: • Syntaktický analyzátor, který dle konfigurace převádí LATEX soubory do SGML formátu. • Popis typu SGML – DTD pro validaci SGML vygenerované analyzátorem • Popis typu XML – DTD pro výstupní XML soubor • Samostatné transformační nástroje, které je jsou ve formě Perlových skriptů od jiných autorů: – převod z SGML do XML, kde SGML je výstupem syntaktickho analyzátoru GELLMU – převod z XML do HTML. – převod z XML do LATEXu. ˜ Domovská stránka projektu na Internetu http://www.albany.edu/hammond/gellmu/ Program je založený na původním převaděči napsaným v Elispu, který transformoval dokumenty z LATEXu do formátu Texinfo (formát pro GNU dokumentaci). Autor pak tento program upravil, ale jeho závislost na Elispu zůstala. 19 Domovská stránka projektu na Internetu http://openjade.sourceforge.net/ 17
18
40
Program nejdříve převede zdroj do SGML, které používá pro vnitřní reprezentaci struktury dokumentu. Pro export do XML se následně použije jeden z převzatých Perlovských skriptů. V tomto režimu program dává možnost kontrolovat (validovat) každou část převodu, takže spolu se vstupem zpracován i DTD pro XML a SGML. Program také umožňuje zpracování matematických výrazů pomocí do formátu MathML nebo jsou tyto výrazy převedeny do podoby co nejbližší původnímu významu v ASCII kódování. Výstupní formátem může být kromě XML také XHTML, DVI a PDF. Program zcela postrádá podporu pro převod TEXovské grafiky a omezené je také zpracování tabulek. Současná verze 0.8 zatím nedostahuje takové kvality, aby mohla být použita na libovolné TEX soubory, bez jeho dalších úprav či omezeních pro daný dokument. I přes tyto nedostatky je tento program nejpropracovějším a nejobecnějším řešním, které je v současné době k dispizici. Jeho závislost na programech Emacs a OpenJade ho vyřazuje z možného použití pro převod dokumentace UISu, ale stal se zdrojem mnoha podnětů pro realizované řešení. Vlastní řešení Pokud bych navrhl vlastní řešení problému, mělo by několik výhod. Určitě bych použil programovací jazyk Perl, což mělo být výhodou pro další vývoj programu. Dále bych složitost programu upravil předpokládaným potřebám uživatelské dokumentace. Upravování takového programu by pak nemělo být více složitější než je nezbytně nutné. Také při návrhu programu bych mohl přihlédnout k požadovaným podmínkám (kódování, modifikovatelnost) už při jeho návrhu, aby jim co nejlépe vyhovoval. V Perlu existuje podpora pro převod v podobě různých pomocných nástrojů. Co bude jistě potřeba je nástroj pro hledání, porovnávání a nahrazování textu. Skvělým pomocníkem pro tento typ úloh jsou regulární výrazy20 , které jsou přímo zakomponované do syntaxe Perlu. Jejich implementace PCRE umožňuje značně zjednodušit parametrizaci výrazů a také oplývají značnou rychlostí. Kromě toho je také v Perlu dobrá podpora pro práci s XML a to hlavně díky kvalitní knihovně lib2xml21 . Pomocí této knihovny lze snadno manipulovat s XML soubory a dalšími formáty na XML založených (XPath, XSLT, XPointer atd.) Po porovnání možností existujících programů a možných vlastností při programování nového programu jsem se rozhodl realizovat řešení vlastními silami. Vlastnostu regulárních výrazů a jejich dobrá podpora v Perlu jsou také silným důvodem proč vybrat vlastní řešení. Rozhodně ale oba programy si při řešení beru jako inspiraci, jak řešit některé problémy spojené s převodem.
20
Více o regulárních výrazech viz kapitola 5 Domovská stránka tohoto samostatného projektu je http://xmlsoft.org/. Knihovna je napsaná v jazyce C a do Perlu je vložená přes modul XML::LibXML. 21
41
7
Popis a hodnocení zvoleného řešení
7.1
Popis řešení
Jak vyplývá z podmínek a výběru řešení, bude program napsaný v Perlu jako samostatný program (skript). Na vstupu program načte jméno vstupního souboru a souboru s konfigurací převodu a výstup tiskne na standardní výstup nebo do výstupního souboru. Kromě těchto paramatrů lze ovlivňovat chování programu i pomocí přepínačů, jejich přehled je v příloze A. Celý proces převodu lze rozdělit do tří fází – příprava vstupu, hlavní převod a závěrečné úpravy. Fáze jsou od sebe odděleny hlavně z důvodu zachování správného pořadí při procesu nahrazování; některé úpravy by se totiž mohly navzájem nesprávně prolínat a ovlivňovat navzájem. Pokud se zde zmiňuji o elementu v TEXovském souboru, je tím myšlena nějaká značka ze zdrojového souboru spolu s jejím obsahem, pokud nějaký má. Příprava vstupu Fáze přípravy vstupu je úpravou vstupního textu před vlastním převodem. Narozdíl od následujících částí, není zcela řízena konfiguračním souborem. V konfiguračním souboru lze pouze zapínat či vypínat některé části této přípravy. Zaprvé se odstraní všechny TEXové komentáře, která nemají pro výstup žádný význam a jejich pozdější odstranění by mohlo být problematické. Komentáře jsou definovány jako text od znaku procenta až do konce řádku. Právě konce řádku by se mohly časem měnit či ztratit. Toto odstranění se provádí jen v případě že je proměnná NOCOMMENT v konfiguraci nastavena na nenulovou hodnotu. Dále se provede změna v zápisu TEXovských značek, které jsou zapsány uvnitř složených závorek, na ekvivalentní zápis před těmito závorkami. Příkladem je převod zápisu elementu Tento text { \it bude kurzívou } na sémanticky ekvivalentní zápis téhož Tento text \it{ bude kurzívou } . Cílem je zjednodušení pro pozdější nahrazování těchto značek. Tímto sjednocením zápisu zamezíme dvojímu hledání téže značky. Seznam všech značek, které se takto budou takto převádět je uložen v konfuguraci v proměnné BLOCKINNER. Dále se převedou všechny nepovinné atributy, které jsou zapisovány do hranatých závorek, na ekvivaletní zápis do složených závorek. V XML souboru ani v konfiguraci nijak nerozlišíme povinnost výskytu atributu, takže tato úprava jen zjednoduššuje další převod sjednocením těchto dvou různých zápisů do jednoho tvaru.
42
Dalším zjednodušení je převedení podobných elementů různých jmen na stejná jména. Sjednocení je definováno v proměnné SAMENAME a sloučí zadané elementy do jednoho, pravidlo na převod se tak může psát jen pro jeden z nich. V TEXu jde např. o elementy em a emph, které se významově nijak neliší. Pro vlastní styly si pomocí této proměnné můžeme sjednotit nějaké elementy, které v XML nepotřebujeme od sebe rozeznávat. Poslední úpravou je převedení znaků „<ÿ a „>ÿ na jejich XML entitní formu. Tyto znaky totiž mají v XML formátu speciální význam (oddělují elementy od textu) a je nutné je před dalším zpracováním označit jako text. Hlavní převod Pravidla hlavního převodu jsou definována v konfiguračním souboru, jehož jméno je jedním z povinných parametrů programu. Stručně popíšu formát souboru a ukázky jeho použití. Jde o jednoduchý textový soubor, kde je každá definice části převodu na jednom řádku. V konfiguračním souboru se mohou vyskytovat čtyři základní druhy výrazů – nastavení proměnné, definice převodu mezi TEX a XML elementem, regulární výraz nebo komentář. Program je od sebe rozeznává pomocí prvního znaku na řádku, komentáře nebo prázdné řádky program nezpracovává. Nastavení proměnné se uvozuje znakem dolaru a následuje jméno proměnné a její požadovaná hodnota. Proměnné, které lze nastavit pro převod, jsou například jaké bude jméno hlavního elementu v XML souboru, definice hlavičky tohoto souboru apod. Úplný seznam i s krátkým vysvětlením je obsažen v příloze B. Řádky uvozené apostrofem jsou rozpoznány jako definice převodu z TEX elementu na nový XML element. Kromě jména elementu ze zdrojového souboru se za jeho název píší další informace, které zpřehledňují převod. Každému elementu pak lze definovat typ, počet a názvy atributů a u některých typů ještě další parametry. Celkem program rozeznává sedm typů elementů, typy a ukázky převodu jsou v tabulce 3: Tab. 3: Tabulka typů nahrazovaných elementů
Typ IN INATR INALONE BLOCK INDIRECT REMOVETAG REMOVEALL
Zdroj \jmeno{obsah} \jmeno{obsah} \jmeno \jmeno{obsah} např. \TeX \jmeno{obsah} \jmeno{obsah}
Výstup <jmeno>obsah <jmeno atr=„obsahÿ> <jmeno/> <jmeno>obsah ... TeX obsah
Typ „INÿ a „BLOCKÿ se od sebe liší jen v tom ohledu, že konec typu „BLOCKÿ není určen koncovou složenou závorkou, ale je nalezen buď na konci souboru nebo 43
na začátku jiného elementu. Seznam těchto elementů je předán v konfiguračním souboru jako další parametr. Typickým použitím tohoto typu jsou elementy pro definci začátku kapitoly. Např. definice ’castc’
=> ’castcxml’
, BLOCK , 1 , sekce|podsekce
omezuje platnost blokového elementu castc až do začátku jiné části nebo začátku elemenů sekce či podsekce. Tímto výčtem ukončovacích elemetů způsobem se řeší problém s nepárovým zápisem bloku, který je v TEXu narozdíl od XML možný. Typ „INDIRECTÿ je používán hlavně pro převod jednotlivých speciálních znaků TEX. Jeho použitím se jen zpřehledňuje zápis, který se mohl složitěji zapsat i regulárním výrazem. Typy „REMOVETAGÿ a „REMOVEALLÿ umožňují se zadanéhu vstupu odstranit daný element, a to i s jeho obsahem. Tato část je nejdůležitější a nejsložitější z celého převodu a její správné nastavení je klíčové. Složitost převodu je dána tím, že některé typy elementů mohou obsahovat i další elementy, takže je potřeba toto vnořování ošetřit. Navržené řešení tak obsahuje funkci, která v uvedeném případě volá rekurzivně sebe sama nad daným textem, který je obsahem elementu. V průběhu psaní převodu se vyskytla nutnost definovat ještě čtvrtý typ a to přímou definici regulárního výrazu (řádky jsou uvozené zpětným lomítkem). Program daný regulární výraz nijak neupravuje a provede opakované nahrazování, dokud jsou v textu nějaké vzory nelezeny. Tento typ převodu je určen pro převody, které nahrazují jenom jméno TEXovského elementu na jiný v XML tvaru. Příkladem takového převodu je problém psaní českých uvozovek, které se zapisuje v TEXovském formátu tak jako ostatní blokové elementy, ale na výstupu nejsou XML elementem, ale jen znaky uvnitř jiných elementů. Obdobně je použit tento typ převodu u obrázků a tabulek, jejichž parametrizace pomocí typů by byla příliš složitá. Součástí řešení této práce bylo i napsání tohoto konfiguračního souboru pro aktuální TEXovský styl a jeho jako ukázka je obsažen v příloze B. Závěrečné úpravy V poslední fázi se zpracovává konfigurační soubor docconv.conf tex22 . Zde jsou definice převodu různých TEXových speciálních výrazů, které je potřeba převést na jejich významový ekvivalent v XML, pokud je to možné. Jde tedy o převody těch elementů, na které nemají vliv na definovaný styl a jsou společné pro všechny TEXovské dokumenty. Proto také nepřepokládám jeho častou změnu. Kromě zde definovaných lze přidávat stejné typy převodů jako v případě hlavního konfiguračního souboru. Jde o hlavně odstranění zpětného lomítka, které je nutné v TEX formátu psát před významné znaky jako jsou složené závorky, dolar, paragraf nebo procento. Dále jde o značky pro konec řádku, značka pro tři tečky, různé mezery a trochu složitější 22
Součaný soubor viz příloha ??
44
převod značky pro datum (\today). Ta se převede na aktuální datum v době převodu s tím že formát lze měnit. Dále jde o jednoduché grafické symboly jako jsou šipky, loga TEX a LATEXapod., které se převedou na jejich textovou reprezentaci. Kromě těchto jsou zde definice pro převod těch nejjednodušších matematických výrazů, které lze ještě snadno převést do prostého textu (např. znak pro stupeň Celsia). Bohužel složitější vzorce stejně tak jako ostatní grafické symboly (např. písmena řecké abecedy) nelze do daného kódování převést. Jako poslední se upravují odkazy v dokumentu. V TEXovských dokumentech se pro odkaz na nějaké místo v textu používá element ref, který odkazuje na místo definované elementem label. Element label se vyskytuje buď uvnitř nějakého jiného elementu např. obrázku, nebo za elementem. V obou případech se program hledá takovýto nadřazený nebo blízký element, a pokud takový existuje, přidá mu atribut »id« a do něj uloží obsah a původní element label je odstraněn. Kromě uvedených tranformací ještě program před vlastním výstupem provádí drobné úpravy, např. přejmenování hlavního elementu ve kterém je celý dokument, odstranění přebztečných mezer nebo odstranění již nepotřebného formátování.
7.2
Omezení zvoleného řešení
Uvedení řešení samozřejmě není dokonalé a má své nedostatky. Některé z nich je možné časem překonat, některé ovšem nikoli. Největším problémem je samotné zpracování TEXformátu, které není a nemůže být zcela dokonalé. Omezením, které se nedá překonat vůbec, jsou složitější matematické výrazy. Tyto výrazy nelze nijakým způsobem převést do XML podoby. Výsledný matematický vzorec se nedá reprezentovat pouhými znaky, spíše ho lze přirovnat k obrázku, který je v u výsledkem celkem složitého sázecího algoritmu. V převodu lze pouze definovat předem známé a jednoduché výrazy, jako např. výraz pro stupeň Celsia, který má svůj ekvivalent v ASCII tabulce znaků. Jde však o řešení závislé na výstupním kódování (v našem případě ISO-8859-2). V jiném kódování tento znak má jiné místo v ASCII tabulce nebo v ní vůbec není. Dalším omezením je zpracování TEX znaků, které sice nejsou definovány pomocí matematickém prostředí, ale nemají svůj ekvivalent v ASCII tabulce. Jde například o znaky pro různé šipky, symboly řecké abecedy a další grafické symboly. Možným řešením by bylo použití jako výstupního kódování sadu Unicode. Pro některé z těchto znaků by se nějaký ekvivalent našel, ovšem výstupní soubor by nešlo zobrazit v jiném kódování než je Unicode. To je bohužel v protikladu s požadavky tak jak jsou definovány v části 6.3. Přechod celého informačního systému na nové kódování kvůli dokumentaci je samozřejmě nesmyslný a tak nezbývá, než se tímto omezením smířit. Výše zmíněné nedostatky jsou dány širokými možnostmi TEXu a obecně se jich nelze nijak zbavit. Jdou však obejít tím, že daná omezení jsou dopředu známé autorům dokumentace. Tito pak při psaní dokumentace musí mít na zřeteli, že nemohou používat všechny grafické značky TEXu. Problém je tedy možné vyřešit 45
dodržením jisté disciplíny při psaní dokumentace, čímž sice řešení ztrácí na své univerzálnosti, ale vzhledem k daným podmínkám je to nevyhnutelné. Navicí tento problém zatím patří jen hypotetické roviny, protože v současné době leč uživatelská dokumentace žádné takové speciální znaky neobsahuje.
7.3
Možná zlepšení řešení do budoucna
Pokud by se později ukázalo nezbytné používání speciálních TEXových symbolů v textu dokumentace, dala by se přidat volba, která by umožnila výstup kódovat do sady Unicode. Tím by se rozšířila množina TEX dokumentů, které by program zvládal převést správně. Možná by byla také volba, že jenom v případě, pokud by dokument nějaké speciální symboly obsahoval, výstup by se kódoval do Unicode. V opačném případě by zůstal v původním kódování. Kromě toho by se dalo zlepšit ošetření chyb při parsování textu. Progra předpokládá, že vstupní soubor bude správně napsán podle TEXovských pravidel. V případě, že tomu tak není, nelze se na výsledky programy zcela spolehnout. Přidáním nové úrovně hlášení chyb, například při nenalezení odpovídajícíhi vzoru v konfiguračních souborech, by odhalilo chyby ve vstupních datech nebo by upozornilo na nedostatky v převodní konfiguraci. Největším nedostatkem programu je celkem omezená množina TEX elementů, které se podařilo převádět na jejich významově stejné ekvivalenty v XML. V této oblasti je jistě co zlepšovat, například parsování grafiky, sloupcové zarovnání, čítač nebo lepší zpracování matematických výrazů by programu prospělo. Zatím se tyto věci neukázaly jako nutné, ale do budoucna by se nimi mělo počítat. Hodně záleží na praktickém používání, kde se jistě odhalí nějaké nedostatky. Samotná analýza by šla rozšířit o možnost rozeznávání znamých elementů zadaných v konfiguračním souboru od těch, co jsou definovaní v samotném LATEXu. Přepínačem by se ovlivňovali chování programu pokud by takový element našel, zda by ho zachoval, smazal nebo přejmenoval. Možné je také do budoucna naprogramování automatické kontroly odkazů v rámci dokumentu a případné vypsání buď chybějících nebo přebývajícíh odkazů či návští. Pokud se to ukáže jako vhodné, bylo by možné zlepšit práci s konfiguračními soubory. V aktuální verzi program umí pracovat pouze se dvěma konfiguračními soubory – jedním nepovinným zadaný uživatelem a druhým pro převod jednodušších TEXových značek. Je možné, že se dokumentace časem rozdělí na několik samostatných typů, z nichž některé budou sdílet stejné TEXovské styly . V tomto případě by se zápis převodu těchto společných stylů psal do jednoho konfiguračního souboru a do druhého pak jen ty pro daný styl. Možnost pracovat s několika konfiguračními soubory by byla vhodná. Za úvahu také stojí myšlenka přidání podpory pro práci s XSLT styly. Ty jsou v programovacím jazyce Perl podporované různými rozšiřujícími moduly a jejich implementace by neměla být tak složitá. Program by pak mohl převádět výstupní XML formát pomocí těchto XSLT stylů do dalších formátů zcela automaticky. 46
Kromě XSLT je možné pomocí těchto modulů také pracovat s XML samotným. Pomocí těchto modulů by pak šlo kontrolovat XML syntaxi na výstupu nebo samotný výstup lépe naformátovat, aby šel lépe číst. Dále je zde k možnost napsat nějaký DTD pro danou dokumentaci a výstup v XML formátu pak kontrolovat oproti tomuto DTD. To by vedlo k lepší kontrole výstupních dat. I když je možné, že toto DTD se bude měnit tak často, že jeho úpravy budou příliš časově náročné, aby jeho používání pro validaci bylo praktické.
7.4
Doporučení pro práci s dokumentací
Během práce s uživatelskou dokumentací UISu jsem dospěl k několika doporučením, které vidím jako přínosné jak pro dokumentaci samotnou, tak pro možnosti její zpracováním programem. Největším nedostatek vidím v neexistenci jasných pravidel, jak se má dokumentace psát a jaké značky a styly se mají v TEXovském souboru použít. To není v současné době žádným markantním problémem, neboť dokumentaci tvoří jen jedna osoba. Na ní závisí dodržování zvoleného stylu, použitých značek i ustálených výrazů. Pokud ovšem dokumentaci nebo její část bude psát někdo jiný, bude nucen prostudovat všechny existující svazky a na tyto zákonitosti přijít. Což jistě zabere nemalé množství času s nejistým výsledkem. Samozřejmě tato pravidla by značně ulehčila i konfigurování převodního programu. Při změně těchto pravidel by byl adekvátně změněn i konfigurační soubor. Ovšem bez daných pravidel není jak zajistit stav, kdy bude nastavení převodu korespondovat s aktuální verzí stylu dokumentace. Jestliže se v budoucí době navíc očekává rozšíření dokumentace i na část programovou, myslím že tím spíše je na místě se těmito pravidly zaobírat. Dále je třeba do budoucna navrhnout nějaký systém pro jednoznačnou identifikaci částí textu. Jak jsem již uvedl, kromě převodu celých svazků do nové formy je plánován nový typ dokumentace a to kontextová nápověda. Ta se má zobrazovat uživatelům přímo v UISu jako nápověda pro nějakou konkrétní akci nebo jako krátký popisek ovládacích prvků. Vzhledem k tomu, že se tato nápověda bude generovat ze stejných souborů obsahující celé téma, bude nutné jednotlivé části v těchto souborem nějak identifikovat. Identifikátor této části se pak přiřadí daným akcím nebo ovládacím prvkům tak, aby systém mohl rozhodnout, kterou kontextovou nápovědu má zobrazit. Identifikace musí být jednoznačná a přiměřeně dlouhá, tak aby ji bylo možné nějak uchovávat v UISu a zároveň ji zapisovat do TEXových souborů dokumentace. Navíc při větší změně v dokumentaci, například přidání nové kapitoly nebo změny názvu kapitoly, se nesmí identifikace nijak změnit. Nelze tedy části dokumentace určovat pomocí názvu nebo očíslování kapitoly. Dalším omezením je nutná jedinečnost tohoto identifikátoru ve všech svazích, nelze tedy ani doporučit použít zkratek názvu kapitoly (např. z názvu „Nastavení aplikaceÿ vytvořit identifikátor »nastapl«, ne47
boť kapitolu se stejným názvem jistě obsahují i další svazky). Z pohledu zpracování identifikátoru v UISu by byl samozřejmě nejlepší nějaký číselný identifikátor. To je ale trochu nepraktické řešení pro práci dokumentátorky, která by musela mít někde napsanou „překladovou tabulkuÿ, sdílenou s UISem, kam by se zapisovalo číslo a místo, kde se nápověda zobrazit. Stejně jako v předchozím případě by programátor by určil identifikátor pro danou akci či ovládací prvek a zanesl by jej do překladové tabulky. Dokumentátorka by pak v textu dokumentace označila odpovídající část tímto číslem. Nepraktičnost toho přístupu je nesystematičnost identifikátorů, protože jejich rozmístění v dokumentu bude zcela náhodné. Bez překladové tabulky by také nebylo možné určit, pro kterou kontextovou nápovědu se daná část vztahuje. Takovýto model se těžko udržuje v konzistentním stavu a lehce se v něm udělá chyba. Další otázkou je, jak bude kontextová nápověda uložena, zda ve zvláštních souborech nebo přímo v UISu. Také nebude snadné určit, kdo rozhodne, ke kterým akcím a ovládacím prvkům se kontextová nápověda bude zobrazovat. Má to být programátor nebo dokumentátorka? Odpovědi na tyto otázky bohužel nemohu vyřešit v této práci, ty bude muset zodpovědět vývojový tým. Rozhodnutí závisí na technických vlastnostech informačního systému a také principech zde použitých.
48
8
Závěr
Cílem této práce bylo najít a realizovat řešení při převodu uživatelské dokumentace Univerzitního informačního systému MZLU z TEXu do formátu XML. Ke zdárnému řešení problému bylo nutné najít a analyzovat využití již existujících nástrojů pro práci s XML formátem. Dalším cílem bylo ukázat jak je možné XML formát použít v praxi v současné době a jaké jsou možné varianty do budoucna. Během práce jsem se tak musel seznámit se třemi hlavními směry – problematikou psaní dokumentace, problematiku daných formátů a nalezení praktického řešení problému. Před psaním této práce jsem měl s dokumentací zkušenost pouze u nástrojů pro psaní dokumentů. Můj předpoklad byl, že najdu i nějaké doporučení a praktické rady jak psát dokumentaci, které pak porovnám a vyberu ty nejlepší. Musím však konstatovat, že se mi nepodařilo najít žádný metodický pokyn, normu či jen popis nějakého konkrétního řešení při psaní uživatelské dokumentace v oblasti informačních technologií. Existuje sice několik nástrojů pro psaní dokumentace programátorské, se kterými se často pojí určitá doporučení jak od samotných autorů, tak uživatelů. To je markantní rozdíl oproti dokumentaci uživatelské, kde žádná taková interakce není a uživatelé dokumentaci přijímají pasivně např. jako knihu. Dokumentátoři tak tyto „knihyÿ píší jen na základně vlastních zkušeností a citu. Každá uživatelská dokumentace je výsledkem subjektivních názorů a postupů jejich autorů, bez silné vazby na uživatele. Její obsah nelze nijak předvídat ani objektivně hodnotit či porovnávat. Dospěl jsem k závěru, že v tomto směru je hodně „bílých místÿ a bylo by vhodné se na ní v budoucnu zaměřit. Na rozdíl od uživatelské dokumentace, bylo při hledání informací o TEXu a XML zdrojů nepřeberně mnoho a také nástrojů pro práci s nimi bylo dostatek. Oba formátu jsou široce rozšířené a využívané, práce s nimi je díky existenci těchto nástrojů snadná. Analýzou již existujících řešení daného problému jsem však musel většinu vyřadit díky různým nevyhovujícím vlastnostem. V praktické části jsem tedy realizoval vlastní řešení ve formě skriptu v programovacím jazyce Perl. Díky konzultacím přímo s dokumentátorkou UISu a testování na reálných dokumentech jsem jej dopracoval do vydoby, připravené pro reálný provoz. Během hledání řešení se objevilo mnoho problémů jak převod realizovat. Syntaxe z TEXovského formátu se ukázala jako značně komplikovaná a rozsáhlá. Její úplný a přesný převod do XML není dle mého názoru v podstatě možný a je třeba hledat nějaké kompromisní řešení. Zároveň je zde nutná podmínka mít možnost co nejlépe vyhovět danému stylu dokumentu, což je možné zajistit vhodným typem konfigurace. Jako možné zlepšení do budoucna vidím převod dokumentace do znakové sady Unicode, která by markantně rozšířila a zobecnila možnosti převodu. Je však otázkou, zda takové rozšíření bude někdy nutné v souvislosti s uživatelskou dokumentací 49
UISu implementovat. Jako vhodné dále vidím vyřešit jednoznačnou identifikaci částí dokumentu. Jde o vlastnost, kterou shledávám pro další použití velmi důležitou ne-li nutnou. Závěrem lze říci, že se mi realizaci daného problém podařilo vyřešit tak, jak byla požadována. Omezené vlastnosti řešení jsou dané jednak vstupními požadavky a také vlastnostmi TEX formátu. Předpokládám, že při její praktickém používání se dodatečně zjistí nějaké další požadavky a úpravy, které bude potřeba přidat. Jsem toho názoru, že uvedené řešení je na tuto situaci připravené a jeho rozšíření o další prvky nebude problémem. Doufám, že tento nový nástroj bude užitečný nejen pro vývojovým tým, ale hlavně pro všechny uživatele tohoto informačního systému.
50
9
Literatura
Bradley, N. XML – kompletní průvodce. Praha: Grada Publishing, 2000. ISBN 80-7169-949-7. Bříza, P. Kompletní průvodce XSLT - jmenné prostory. Článek z periodika Interval ISSN 1212-8651. Dostupné na Internetu [cit. 5.7.2006]. Češka, M., Rábová, Z.Gramatiky a jazyky. Brno: VUT, 1992. Dokument dostupný na Internetu [cit. březen 2006]. Habiballa, H.Regulární a bezkontextové jazyky I. Ostrava: Ostravská univerzita, 2003. ISBN 80-7042-852-X. Kočer M. – Sýkora P.Ne příliš stručný úvod do systému LATEX 2ε Elektronická publikace. Dostupné na Internetu [cit. 5.7. 2006]. Kosek, J.XML pro každého. Praha: Grada Publishing, 2000. ISBN 80-7169-860-1. Kosek. J.K čemu můžeme XML použít již dnes. Plzeň: 2001 . Dostupné na Internetu: [cit 20.5. 2006]. Kosek J.Seriál o XML. Plzeň: 2001. Seriál článků pro Softwarové noviny. Dostupné na Internetu [cit. 30.6. 2006]. Kryl, R. Jak psát dokumentaci zápočtového programu Článek dostupný na Internetu http://ksvi.mff.cuni.cz/ kryl/dokumentace.htm [cit. 6.7. 2006] . Lemay, L. Naučte se Perl za 21dní. Praha: Computer Press, 2002. ISBN 80-7226616-0. Olšák, P. TeXbook naruby Brno: Konvoj, 1997. ISBN 80-85615-64-9. Rybička, J.LaTeX pro začátečníky. Brno: Konvoj, 2003. ISBN 80-7302-049-1. Rybička, J.Úvod do teorie formálních jazyků. Brno: Konvoj, 1999. ISBN 80-8561525-8. Šorm, M.Využití principu skládání komponent při návrhu webového informačního systému. Brno: 2006. Disertační práce. . Young, M. J. Redmont U.S: Microsoft Press, 2001 XML Step by Step Redmond, Washington: 2001. ISBN 0-7356-1465-2. Wall, L. – Christiansen, T. – Schwartz, R.Programování v jazyce Perl. Praha: Computer Press, 1997. ISBN 80-85896-95-8.
51
Přílohy
A
Přepínače programu
Program očekává na vstupu minimálně název vstupního souboru s dokumentací . Dále je možné volitelně použít tyto přepínače: Jméno kofiguračního souboru – -c Textový parametr se jménem hlavního konfiguračního převodu. Kromě tohoto se automaticky načtě i souor docconv.config tex, který obsahuje definice převodu pro samotný TEX. Nastavení úrovně výpisu o průběhu převodu – -l Tento přepínač má pět různých úrovní od čísla jedna až po číslo pět, význam je následující 1 – Žádné zprávy nejsou vypisovány, vhodné pro již ověřené vstupy a tam kde potřebujeme výsledný soubor programu mít na standartní výstupu. 2 – Jen hlavní informace o načtených konfiguračních souborech a výsledku převodu. Toto nastavení je výchozí. 3 – Vypisuje navíc i seznam načtencýh řádků z konfiguračních souborů s počtem nalezených výskytů pro každý z nich. 4 – Kromě řádků vypisuje i některé ladicí informace. 5 – Všechny zprávy. Vhodné jen pro detailní ladění převodu. Tento parametr se může definovat i do konfiguračního souboru jako proěnna LOGLEVEL. Pokud je v definovaná v konfiguračním souboru, pak je přepínač na příkazové řádce ignorován. Formátovat XML výstup – -x Pokud je tento přepínač nastaven, tak výstupní XML soubor bude před uložením ješte naformátován tak, aby šel co nejlépe číst. Jde tedy o významově úpravu s lepším odsazením XML elementů podle struktury dokumentu. Zároveň se provádí i kontrola správnosti formátu, tedy validace zda je výstup well-formed.
53
B
Výchozí konfigurace programu
####################################################################### # Ruzne promenne (zacinaji dolarem) ####################################################################### # Uroven vypisu logovani $LOGLEVEL => ’2’ # Vstupni parametry # Znak kterym zacina tag $INSTARTTAG => ’\’ # Znak kterym konci tag $INENDTAG => ’’ # Znak kterym zacina atribut (obsah) $INSTARTCONTENT => ’{’ # Znak kterym konci atribut (obsah) $INENDCONTENT => ’}’ # Znak kterym defaultne zacina element typu BEGIN-END $INBEBEGIN => ’begin’ # Znak kterym defaultne konci element typu BEGIN-END $INBEEND => ’end’ # Vystupni parametry # Znak kterym zacina tag $OUTTARTTAG => ’<’ # Znak ktery je potom $OUTENDMARK => ’/’ # Znak kterym konci tag $OUTENDTAG => ’>’ # Hlavicka vystupnih souboru. Kodovani se zmeni dle $OUTENCODING $HEADER => ’’
54
# Jmeno elementu do ktereho bude ’zabalen’ $MAINELEMENT => ’document’
obsah
# Defaultni nazev prvniho atributu pro vsechny elementy $ATRNAME => ’nazev’ # Vystupni kodovani $OUTENCODING => ’iso-8859-2’ # Jmena elemetu co jsou obsahem $OBSAH => ’obsah|tableofcontents’ # Bloky, ktere mohou definovane uvnitr zavorek { a } $BLOCKINNER => ’tiny|scriptsize|footnotesize|small| normalsize|large|Large|LARGE|huge|Huge’ # Ktere elementy jsou povazovane za stejne $SAMENAME => ’em,emph’ # Odstranit komentare? $NOCOMMENT => ’1’ # Formatovani ’tiny’=> ’male’, IN , 1 ’scriptsize’ => ’male’, IN , 1 ’footnotesize’ => ’male’, IN , 1 ’small’ => ’male’, IN , 1 ’normalsize’ => ’normalni’, IN , 1 ’large’ => ’vetsi’, IN , 1 ’Large’ => ’velke’, IN , 1 ’LARGE’ => ’velke’, IN , 1 ’huge’ => ’velke’, IN , 1 ’Huge’ => ’velke’, IN , 1 ’textbf’ => ’tucne’, IN , 1
\documentclass{doc} \makeindex \begin{document} \titlepage{1}{Všichni uživatelé}{2.0}{11. leden 2006} \obsah \preambule{} \noindent Vážený uživateli Univerzitního informačního systému,\\ \noindent dostává se Vám do rukou příručka, která Vám pomůže s~prvními a základními kroky v~Univerzitním informačním systému (UIS) zavedeným na všech fakultách Mendelovy zemědělské a lesnické univerzity v~Brně. Naleznete zde rady k~prvnímu přihlášení, přehled základní terminologie, vysvětlení základních principů a postupů použitých v~jednotlivých aplikacích a také návod k~základním aplikacím v~částech: \begin{odrazky} \item Informace o~MZLU v~Brně (informace o~studiích, kontakty na veškerá pracoviště a osoby), \item Celouniverzitní agendy, \item Správa centrálních aplikací (poštovní schránka, dokumentový server, přístupový systém, evidence věcí k~výpůjčkám a evidence výpůjček, sledování plánu absencí pracovníků, správa úkolů TODO), \item Dokumentace~a \item Nastavení informačního systému. \end{odrazky} Jsou to aplikace, které jsou zpřístupněny všem přihlášeným uživatelům našeho informačního systému. Některé z~uvedených aplikací jsou dostupné také na veřejném portálu Univerzitního informačního systému na adrese \url{http:\dvelom is.mendelu.cz/}.\\ \dots \podpis{Ing. Jitka Šedá a kolektiv autorů} 58
\newpage \noindent \textbf{\large Jak číst dokumentaci}\\ \dots \sekce{Vývojový tým UIS}{Vyvojovy tym UIS} \index{tým!vývojový} Členové vývojového týmu jsou zaměstnanci Ústavu informačních a komunikačních technologií (\emph{ÚIKT})\index{ÚIKT}, převážně Oddělení koncepce a vývoje (OKV). Jako součást vývojového týmu lze považovat i některé zaměstnance (správce dat, univerzitního integrátora) Oddělení provozu a správy aplikací (OPSA).
\podsekce{Oddělení koncepce a vývoje (OKV)} Členové \emph{OKV}\index{OKV} tvoří převážnou část vývojového týmu, který navrhuje a vyvíjí pilotní aplikace integrovaného UIS, pro uživatele tvoří další potřebné aplikace podle sjednocených požadavků rektorátu, pedagogické komise, vedení fakult a vedoucích ústavů jednotlivých fakult. \newpage \dots \tip{Uživatelé, kteří řeší nějaké problémy s~informačním systémem, se v~první řadě obracejí na OSSA (str. \pageref{ossa}) a SIF příslušné fakulty nebo pracoviště.} \obrazek \includegraphics{obrazky1/2-prihlasovaci_formular} \endobr{prihlaseni}{Příklad přihlašovacího formuláře} \sekce{Odhlášení z~informačního systému}{Odhlasni z~informacniho systemu} \label{odhlášení z~UIS} \obrazek \scalebox{.95} {\includegraphics{obrazky1/nzmena_hesla1}} \endobr{heslo}{Změna hesla}
59
%\newpage %\printindex \rejstrik \end{document}
60
D
Ukázka vygenerované dokumentace v XML formátu
<document> Vážený uživateli Univerzitního informačního systému, dostává se Vám do rukou příručka, která Vám pomůže s~prvními a základními kroky v~Univerzitním informačním systému (UIS) zavedeným na všech fakultách Mendelovy zemědělské a lesnické univerzity v~Brně. Naleznete zde rady k~prvnímu přihlášení, přehled základní terminologie, vysvětlení základních principů a postupů použitých v~jednotlivých aplikacích a také návod k~základním aplikacím v~částech: <polozka> Informace o~MZLU v~Brně (informace o~studiích, kontakty na veškerá pracoviště a osoby), <polozka> Celouniverzitní agendy, <polozka> Správa centrálních aplikací (poštovní schránka, dokumentový server, přístupový systém, evidence věcí k~výpůjčkám a evidence výpůjček, sledování plánu absencí pracovníků, správa úkolů TODO), <polozka> Dokumentace a <polozka> Nastavení informačního systému.
Jsou to aplikace, které jsou zpřístupněny všem přihlášeným uživatelům našeho informačního systému. Některé z~uvedených aplikací jsou dostupné také na veřejném portálu Univerzitního informačního systému na adrese . ... <podpis>Ing. Jitka Šedá a kolektiv autorů Jak číst dokumentaci ...
61
<sekcexml nazev="Vývojový tým UIS"> Členové vývojového týmu jsou zaměstnanci Ústavu informačních a komunikačních technologií (ÚIKT), převážně Oddělení koncepce a vývoje (OKV). Jako součást vývojového týmu lze považovat i některé zaměstnance (správce dat, univerzitního integrátora) Oddělení provozu a správy aplikací (OPSA). <podsekcexml nazev="Oddělení koncepce a vývoje (OKV)"> Členové OKV tvoří převážnou část vývojového týmu, který navrhuje a vyvíjí pilotní aplikace integrovaného UIS, pro uživatele tvoří další potřebné aplikace podle sjednocených požadavků rektorátu, pedagogické komise, vedení fakult a vedoucích ústavů jednotlivých fakult. ... <sekcexml nazev="Odhlášení z~informačního systému">
Všichni uživatelé Vážený uživateli Univerzitního informačního systému, dostává se Vám do rukou příručka, která Vám pomůže s~prvními a základními kroky v~Univerzitním informačním systému (UIS) zavedeným na všech fakultách Mendelovy zemědělské a lesnické univerzity v~Brně. Naleznete zde rady k~prvnímu přihlášení, přehled základní terminologie, vysvětlení základních principů a postupů použitých v~jednotlivých aplikacích a také návod k~základním aplikacím v~částech:
Informace o~MZLU v~Brně (informace o~studiích, kontakty na veškerá pracoviště a osoby),
Celouniverzitní agendy,
Správa centrálních aplikací (poštovní schránka, dokumentový server, přístupový systém, evidence věcí k~výpůjčkám a evidence výpůjček, sledování plánu absencí pracovníků, správa úkolů TODO),
Dokumentace a
Nastavení informačního systému.
Jsou to aplikace, které jsou zpřístupněny všem přihlášeným uživatelům našeho informačního systému. Některé z~uvedených aplikací jsou dostupné také na veřejném portálu Univerzitního informačního systému na adrese http:\dvelom is.mendelu.cz/. ...
Ing. Jitka Šedá a kolektiv autorů
<strong> 65
Jak číst
dokumentaci
...
Vývojový tým UIS
Členové vývojového týmu jsou zaměstnanci Ústavu informačních a komunikačních technologií (ÚIKT), převážně Oddělení koncepce a vývoje (OKV). součást vývojového týmu lze považovat i některé zaměstnance (správce dat, univerzitního integrátora) Oddělení provozu a správy aplikací (OPSA). Členové OKV tvoří převážnou část vývojového týmu, který navrhuje a vyvíjí pilotní aplikace integrovaného UIS, pro uživatele tvoří další potřebné aplikace podle sjednocených požadavků rektorátu, pedagogické komise, vedení fakult a vedoucích ústavů jednotlivých fakult. ...
Odhlášení z~informačního systému
66
G
Ukázka převodu do formátu XHTML - na obrazovce
Obr. 2: Ukázka převodu do formátu HTML pomocí XSLT
