Pravidla dokumentace

Transkript

1 Pravidla dokumentace Příklad na převod XML do HTML pomocí šablon XSLT Na příkladě si ukážeme základy práce s šablonami XSLT. 1. Vhodně otagujeme textový soubor, aby z něj vznikl soubor XML <?xml version="1.0" encoding="utf-8"?> <clanek cislo_clanku="2" verze="1" misto_zverejneni="samozka"> <titulek>struktura dokumentu</titulek> <datum>leden 2007</datum> <autor>josefína Bakerová</autor> <nadpis1>dokumentace k projektu</nadpis1> <poznamka>dokumentace k projektu se skládá (nejméně) z osmi částí:</poznamka> <nadpis2>titulní stránka</nadpis2> <odstavec>vzhledově stejná pro všechny dokumenty (doporučuji vytvořit si pro ni šablonu), obsahuje identifikační údaje. Název fakulty (je možné použít logo FIT), do kterého předmětu dokumentace patří (IZP,IUS), název projektu podle zadání, jméno autora dokumentu, login, datum. <nadpis2>obsah</nadpis2> <odstavec>úroveň detailu (zda budou uvedeny sekce N, nebo i N.N, nebo dokonce N.N.N) zvolte vhodně podle délky a složitosti dokumentu. Pokud dokument obsahuje množství obrázků a/nebo tabulek, je vhodné vytvořit a za obsah připojit také seznam těchto elementů. <nadpis2>úvod</nadpis2> <odstavec>stručný a jasný přehled, čeho se dokument týká a jaké má části.. Úvod je nutnou součástí každého dokumentu. Stačí dva, maximálně tři odstavce. Mají být napsány tak, aby čtenář dokumentu nemusel už dál číst a přesto měl přehled o celém dokumentu. Pokud se jedná o dokument hemžící se zkratkami a akronymy, je nutné uvést pododdíl s vysvětlující tabulkou (zkratka, plný text) XSLT - příklad 1/5

2 <nadpis2>analýza problému a princip jeho řešení</nadpis2> <odstavec>obsahuje stručnou charakteristiku řešeného problému. Princip řešení, popis funkcí, vymezení vstupních dat a požadovaných výsledků, možná omezení, možný rozsah hodnot dat. Je možné použít slovní formu doplněnou obrázky, schématy, tabulkami apod. (např. tabulka by mohla obsahovat sloupce: Funkce:..., Popis:..., Vstupy:..., Výstupy:..., Podmínky:...), nebo: Diagramy datových toků - grafická technika, modelující toky dat a jejich transformace (různé názvy: bubble chart, bubble diagram, process model, function model, work flow diagram). Je vhodné zde také uvést odkazy na zdroje, odkud bylo čerpáno obeznámení se s danou problematikou, odkazy na literaturu o používaných metodách apod. <nadpis2>návrh řešení problému</nadpis2> <odstavec>výběr, či vytvoření metody řešení, resp. vytvoření matematického modelu, volba a sestavení algoritmu. Dekompozice problému. Stanovení vhodných datových typů, názvů funkcí, specifikace parametrů funkcí. Formát zobrazení výsledků. Možná forma: slovní popis, vývojové diagramy, Nassi Schneidermanovy diagramy, symbolika vyššího programovacího jazyka, či kombinace těchto forem. <odstavec>!!! Nebude zde okopírovaný celý program v jazyku C!!!! <nadpis2>specifikace testů</nadpis2> <odstavec>obsahuje popis zhruba 10 testovacích případů, kterými se bude ověřovat funkčnost a/nebo výkonové vlastnosti programu nebo jeho podprogramů (funkcí). Je nutno zdůvodnit výběr testovacích případů, testovacích dat a metodiky testování. Návrh testů bude zaměřen např. na možné: chyby zvolené metody, chyby vstupních dat, chyby zobrazení. Může být i ve formě tabulky. <odstavec>můžete použít například tuto šablonu pro specifikaci testů (pro každý test): <seznam> <bod>testovací údaje č.: XX</bod> <bod>testovací kritérium: popis vybraného testovacího kritéria</bod> <bod>testovací vstupy/očekávané výstupy: konkrétní dvojice</bod> <bod>další vstup/výstup; může jich být na základě příslušného kritéria více</bod> <bod>výsledek testování: zda se odhalila nějaká chyba testováním a jaká - její popis</bod> <bod>poznámky: jakékoliv další významné poznámky k tomuto testovacímu kritériu.</bod> </seznam> <nadpis2>popis vlastního řešení</nadpis2> <odstavec>obsahuje popis vlastního řešení (implementace) a problémů, se kterými jste se při řešení setkali. Budou zde rovněž uvedeny případné odchylky od návrhu, XSLT - příklad 2/5

3 v případě, že během implementace se ukázalo vhodnější řešení dekompozice problému, které ve fázi návrhu nebylo zřejmé. Při popisu principu řešení nepoužívejte "algoritmické" formy (když A je rovno 5 pak...). Tvořte souvislé české věty. Snažte se o ABSTRAKTNÍ a CO NEJSTRUČNĚJŠÍ popis, který je ale co do obsahu vyčerpávající a věcně správný. Nezabývejte se detaily, pokud to nepovažujete za zajímavé z hlediska řešení. Neopisujte doslova jednotlivé funkce. Vyjádřete se vlastními slovy. Nepopisujte každou funkci zvlášť, účelem není velký objem textu, ale vystižení podstaty. V dokumentačním souboru předpokládejte pouze znalost zadání. Neodkazujte se na komentáře ve zdrojovém textu. <nadpis2>závěr</nadpis2> <odstavec>v závěru dokumentace uveďte seznam zdrojů odkud jste čerpali informace k projektu - eventuálně zdroj vzorových algoritmů, vlastní zajímavé postřehy z celkového řešení problému a metriky vytvořeného produktu: <seznam> <bod>počet funkcí</bod> <bod>počet řádků zdrojového kódu</bod> <bod>velikost kódu programu</bod> <bod>velikost statických dat (proměnné a konstanty)</bod> </seznam> <odstavec>poznámka: Zjišťování metrik není samoúčelné. Slouží k tomu, abyste si uvědomili, v jakém vztahu je vámi zvolené řešení vzhledem k výslednému binárnímu kódu. <nadpis2>další doporučení</nadpis2> <odstavec>dokumentace tvoří samostatný celek. Dokumentace k projektům vás má naučit psát česky (slovensky, anglicky). Proto bude mít podobu slohového cvičení a ne strohého, heslovitého popisu. Nepodceňujte ji. Dosavadní zkušenosti ukazují, že je to pro mnohé velmi těžký úkol. Uvědomte si, že svá díla budete v budoucnu prodávat lidem, kteří neumějí programovat. Zato český (slovenský, anglický) jazyk ovládají mnozí velmi dobře. Dodržujte pravidla českého pravopisu. Stále ještě existují nějaké vzory a vyjmenovaná slova. Vaše skvělé dílo si nikdo nekoupí, pokud ve vašich textech nalezne hrubky typu i/y, s/z, mně/mě a podobné. Nebude prostě důvěřovat tomu, že umíte programovat, když neumíte ani svůj vlastní jazyk. <odstavec>odstavce zpřehledňují text. Při čtení textových souborů v elektronické podobě (neproporcionální písmo, holý ASCII text) je vhodné oddělovat odstavce prázdným řádkem. Nepoužívejte příliš mnoho zvýrazňujících prvků (nadměrné podtrhávání, řádky hvězdiček a podobné grafické prvky). Někdy méně znamená více. Nepoužívejte osobních a citově zabarvených obratů ("Zdá se mi, že by se mohlo..."). Vyjadřujte se decentně, jako kdyby na vašem textu mělo záviset, zda vás přijmou do zaměstnání, či ne. Z popisu může vyplývat, že máte smysl pro humor, ale vyvarujte se laciných "srandiček". Zvlášť nepříznivě to působí v případech, kdy chybí fakta a věcná správnost. Dokumentace se píše pro někoho jiného, než pro vás. Nepoužívejte tvrzení typu: "Vzhledem k tomu, že funkce, které jsem v této části řešil, jsou krátké a velmi průzračné, obsáhlejší komentář nemá smysl". Také hodnocení typu "tato funkce je jednoduchá" (následuje-li popis) si nechejte pro sebe. Co je jednoduché pro vás, nemusí být jednoduché pro někoho jiného. Pokud píšete texty neproporcionálním písmem (ascii text v elektronické podobě), nepoužívejte zarovnávání textu na pravý okraj. Mezi slovy vznikají velké mezery, které zhoršují čitelnost textu. Jediné, co je na uvedeném způsobu hezčí, je XSLT - příklad 3/5

4 vzhled z větší vzdálenosti. Pokud budete někomu posílat úřední dopisy, u kterých předpokládáte, že je nikdo nebude číst, pak je vizuální dojem účinný (vypadá to hezky). </clanek> 2. Na druhý řádek XML souboru vložíme odkaz na XSL soubor <?xml-stylesheet href="pravidla-dokumentace.xsl" type="text/xsl"?> 3. Napíšeme si kostru souboru XSL a zkusíme oba soubory provázat, je dobré si nakreslit strom XML dokumentu <?xml version="1.0" encoding="utf-8"?> <xsl:stylesheet version="1.0" xmlns:xsl=" <xsl:template match="/clanek"> <html> <head> <title><xsl:value-of select="titulek"/></title> </head> <body> <h1><xsl:value-of select="nadpis1"/></h1> <h3><i><xsl:value-of select="autor"/></i></h3> <p><i><xsl:value-of select="datum"/></i></p> <h2><xsl:value-of select="poznamka"/></h2> <xsl:apply-templates select="kapitola"/> </body> </html> </xsl:stylesheet> 4. Zdokonalíme soubor XSL tak, aby se zobrazovaly správně všechny kapitoly, odstavce, seznamy, navíc na začátek dokumentu přidáme pomocí cyklu seznam kapitol <?xml version="1.0" encoding="windows-1250"?> <xsl:stylesheet version="1.0" xmlns:xsl=" <xsl:template match="/clanek"> <html> <head> <title><xsl:value-of select="titulek"/></title> </head> <body> <h1><xsl:value-of select="nadpis1"/></h1> <h3><i><xsl:value-of select="autor"/></i></h3> <p><i><xsl:value-of select="datum"/></i></p> <h2>obsah</h2> <ul> <xsl:for-each select="kapitola"> <li> <xsl:value-of select="nadpis2"/> </li> <br/> </xsl:for-each> </ul> <hr/> XSLT - příklad 4/5

5 <h2><xsl:value-of select="poznamka"/></h2> <xsl:apply-templates select="kapitola"/> </body> </html> <xsl:template match="kapitola"> <h2><xsl:value-of select="nadpis2"/></h2> <xsl:apply-templates select="odstavec"/> <xsl:template match="odstavec"> <p><xsl:apply-templates/></p> <xsl:template match="seznam"> <ul> <xsl:apply-templates/> </ul> <xsl:template match="bod"> <li> <xsl:value-of select="."/> </li> </xsl:stylesheet> 5. Ze statického seznamu kapitol uděláme relativní odkazy na začátky kapitol <h2>obsah</h2> <xsl:for-each select="kapitola"> <a> <xsl:attribute name="href">#o<xsl:value-of select="position()"/></xsl:attribute> <xsl:value-of select="position()"/>. <xsl:value-of select="nadpis2"/> </a> <br/> </xsl:for-each> <hr/>... <xsl:template match="kapitola"> <h2> <xsl:attribute name="id">o<xsl:value-of select="position()"/></xsl:attribute> <xsl:value-of select="position()"/>. <xsl:value-of select="nadpis2"/> </h2> <xsl:apply-templates select="odstavec"/> XSLT - příklad 5/5