Mendelova univerzita v Brně Provozně ekonomická fakulta
Šablona závěrečných prací pro DocBook Bakalářská práce
Vedoucí práce: Ing. Dita Dlabolová
Jan Peťovský
Brno 2014
Místo určené pro zadání práce.
Rád bych tímto způsobem poděkoval své vedoucí práce Ing. Ditě Dlabolové za cenné připomínky a odborné rady, kterými kladně přispěla k vyhotovení této práce. Také bych chtěl tímto způsobem poděkovat doc. Ing. Jiřímu Rybičkovi, Dr. za odbornou konzultaci ohledně stávajících šablon fakulty.
Čestné prohlášení Prohlašuji, že jsem tuto práci: Šablona závěrečných prací pro DocBook vypracoval samostatně a veškeré použité prameny a informace jsou uvedeny v seznamu použité literatury. Souhlasím, aby moje práce byla zveřejněna v souladu s § 47b zákona č. 111/1998 Sb., o vysokých školách ve znění pozdějších předpisů, a v souladu s platnou Směrnicí o zveřejňování vysokoškolských závěrečných prací. Jsem si vědom, že se na moji práci vztahuje zákon č. 121/2000 Sb., autorský zákon, a že Mendelova univerzita v Brně má právo na uzavření licenční smlouvy a užití této práce jako školního díla podle § 60 odst. 1 Autorského zákona. Dále se zavazuji, že před sepsáním licenční smlouvy o využití díla jinou osobou (subjektem) si vyžádám písemné stanovisko univerzity o tom, že předmětná licenční smlouva není v rozporu s oprávněnými zájmy univerzity, a zavazuji se uhradit případný příspěvek na úhradu nákladů spojených se vznikem díla, a to až do jejich skutečné výše.
V Brně dne 16. května 2014
..........................................
Abstract Peťovský, J. Thesis template for DocBook. Bachelor theses. Brno, 2014. This thesis is aimed to create template for the theses preparation in DocBook using XSL stylesheet. Template is in accordance with the rules for creating theses of the Faculty of Business and Economics, Mendel University. Thesis also includes selecting an appropriate processor to convert the source files into the PDF output and detailed guide to template.
Keywords DocBook, XSL, style, thesis, template.
Abstrakt Peťovský, J. Šablona závěrečných prací pro DocBook. Bakalářská práce. Brno, 2014. Práce se zabývá vytvořením šablony splňující pravidla pro tvorbu závěrečných prací Provozně ekonomické fakulty Mendelovy univerzity. Tato šablona je vytvořena za pomoci formátovacího jazyka DocBook a XSL stylů. Součástí práce je také zvolení vhodného procesoru na převod zdrojových souborů do výstupu PDF a vytvoření podrobného návodu k práci s šablonou.
Klíčová slova DocBook, XSL, styl, závěrečná práce, šablona.
Obsah 1 Úvod a cíl práce ............................................................................ 13 1.1 Úvod do problematiky .......................................................................... 13 1.2 Cíl práce ............................................................................................... 13 2 Teoretický základ .......................................................................... 2.1 DocBook ................................................................................................ 2.2 XSL ....................................................................................................... 2.3 Procesory .............................................................................................. 2.4 XML editory .........................................................................................
15 15 15 15 16
3 Metodika ........................................................................................ 3.1 Analýza problému ................................................................................. 3.2 Volba struktury .................................................................................... 3.3 Volba procesoru .................................................................................... 3.4 Vytvoření vzhledového souboru ............................................................ 3.5 Vytvoření návodu .................................................................................
17 17 17 17 18 18
4 Realizace ........................................................................................ 4.1 Volba struktury .................................................................................... 4.1.1 Deklarace typu dokumentu ........................................................ 4.1.2 Titulní strana a povinné prvky .................................................. 4.1.3 Vlastní text ................................................................................. 4.2 Volba procesoru .................................................................................... 4.2.1 Dostupné FO-procesory .............................................................. 4.2.2 Vyhodnocení ............................................................................... 4.3 Vytvoření vzhledového souboru ............................................................ 4.3.1 Vzhled strany ............................................................................. 4.3.2 Záhlaví a zápatí .......................................................................... 4.3.3 Titulní strana ............................................................................. 4.3.4 Písmo .......................................................................................... 4.3.5 Generovaný text ......................................................................... 4.3.6 Obsah .......................................................................................... 4.3.7 Odkazy citací .............................................................................. 4.3.8 Instrukce pro procesor ................................................................ 4.4 Vytvoření návodu a archivu .................................................................
6 Diskuse ........................................................................................... 6.1 Testování .............................................................................................. 6.2 Správa šablony ..................................................................................... 6.3 Možnosti rozšíření .................................................................................
39 39 39 39
7 Závěr .............................................................................................. 41 Literatura ............................................................................................ 43 Seznam zkratek ................................................................................... 45 A Obsah archivu ............................................................................... 47
13
1
Úvod a cíl práce
1.1
Úvod do problematiky
Tato práce se zabývá problematikou tvorby závěrečných prací. Pro tvorbu typograficky kvalitních dokumentů má uživatel dvě možnosti. Tou první je zvolit textový procesor z kancelářského balíku, což může být např. Microsoft Word nebo komunitou vytvářené alternativy jako jsou třeba LibreOffice/OpenOffice Writer. Tyto programy jsou vytvářeny a koncipovány pro uživatelovu vysokou pohodlnost a jednoduchost užívání. To je jejich obrovská výhoda, ale zároveň to může být také nevýhoda. Jsou to tzv. WYSIWYG1 editory. To znamená, že dokument je upravován přímo v podobě jeho výstupu. Nepracuje se přímo se zdrojovým kódem a při takové manipulaci s textem můžou vznikat typografické chyby. Nehledě na to, že při větší objemové zátěži může být takový systém značně náročný pro paměť počítače. Druhou možností, jak vytvořit dokument, je psát práci v systémech typu LaTeX nebo DocBook. V tomto případě se pracuje s prostým textem, který je doplněn formátovacími značkami systému. Zdrojový kód dokumentu se poté překládá a vzniká uživatelem požadovaný výstup. Takový systém má mnoho výhod. Velkou výhodou DocBooku nebo LaTeXu je skutečnost, že pracují odděleně s obsahovou a vzhledovou částí. Specialitou DocBooku je vytvoření dokumentu, který je různými styly převeden do odlišných vzhledových alternativ, ať už do tištěné PDF podoby nebo do webové HTML stránky a podobně. Tyto systémy vytváří typograficky kvalitní výstup. Jejich nevýhodou je ale značná uživatelská nepřívětivost. Běžného uživatele bez hlubších IT znalostí může odradit právě absence WYSIWYG editoru popsaného výše. Minimalizací této nevýhody se také bude zabývat tato práce.
1.2
Cíl práce
Cílem práce je vytvořit šablonu pro dokument, který splňuje všechny požadavky závěrečných prací PEF MENDELU. Tato šablona může sloužit studentům jako alternativa k oficiálním šablonám a stylům. V současné době mají studenti k dispozici šablonu pro Microsoft Word a sázecí styl systému LaTeX. Tato práce se bude zabývat vytvořením dalšího stylu a to konkrétně XSL šablonou pro značkovací jazyk DocBook. Ta musí splňovat všechny potřebné náležitosti a normy PEF MENDELU. Mimo vytvoření samotné šablony je důležité také vybrat vhodné programové prostředky pro následnou práci se šablonou a generování dokumentů. U šablony je kladen důraz na jednoduchost a pohodlnost při jejím používání. Součástí práce je také vytvoření podrobného návodu, který popíše práci se šablonou běžnému uživateli. Návod bude zaměřen na instalaci doporučených nástrojů 1
WYSIWYG – „What you see is what you get“, přeloženo do češtiny „Co vidíš, to dostaneš“
14
1
ÚVOD A CÍL PRÁCE
potřebných k tvorbě závěrečných prací. Na příkladech bude ukázáno, co vše studentům šablona společně s DocBookem poskytuje.
15
2
Teoretický základ
2.1
DocBook
Začátky DocBooku se datují k začátku roku 1991. Za jeho zrodem stojí společnosti HaL Computer Systems a O'Reilly & Associates (nyní O'Reilly Media, Inc.). O jeho údržbu se ale starala organizace Davenport Group. V polovině roku 1998 nakonec přešel DocBook pod sdružení OASIS 1. DocBook měl primárně sloužit k tvorbě dokumentace pro UNIX a jeho struktura byla tvořena v jazyce SGML. Od verze 4.1 k ní přibyla také XML verze. V současné době je k dispozici verze 5.0. Tato verze, mimo jiné, přináší XML slovník definovaný schématem RELAX NG na místo, v dřívějších verzích preferovaného, DTD. Tím odpadají některé limitace, které byly s DTD spojené. V RELAX NG se například rozlišují kontexty, v kterých jsou použité jednotlivé elementy. DocBook proto může sloučit některé názvy, které popisují podobná data, do jednoho a ulehčit tím zápis: articleinfo, bookinfo — info (Walsh–Hamilton, 2010). I když byl DocBook převážně určen pro tvorbu počítačové dokumentace, v dnešní době v něm není problém napsat prakticky cokoliv. DocBook v podstatě není nic jiného, než definice všech možných struktur a elementů, které je možné použít při tvorbě publikace. Tyto struktury určují význam jednotlivých částí dokumentu. Mohou se zanořovat do sebe a vytvářet tak různé kontexty.
2.2
XSL
DocBook velice dobře poslouží k uchování obsahu, ale pokud je potřeba data publikovat a nachystat pro výstup, DocBook nestačí. Formát dokumentu XML lze stylovat. V případě DocBooku a tištěného výstupu lze volit styly DSSSL nebo XSL. Stylový jazyk DSSSL byl původně navržen pro dokumenty typu SGML, je zastaralý a jeho vývoj stagnuje. Pro formát XML je speciálně navržený jazyk XSL. Ten obsahuje tři menší části (XSL Languages, c2014): • XSLT — jazyk pro transformaci XML dokumentu; • Xpath — jazyk pro navigaci v XML dokumentu; • XSL-FO — jazyk pro formátování XML dokumentu. Těmito vlastnostmi se liší od svého staršího sourozence CSS a díky těmto vlastnostem se dají vytvářet komplexnější styly.
2.3
Procesory
XML dokument poslouží k vytvoření obsahové části dokumentu, XSL styl k definování vzhledu. XSL procesory jsou určeny k vygenerování konečného výstupu z těch1
OASIS – Organisation for the Advancement of Structured Information Standards.
16
2
TEORETICKÝ ZÁKLAD
to zdrojových souborů. Postup zpracování dokumentu si ukážeme na Obrázku 2.1 (Kosek, 2011).
XML
XSLT procesor XSL
FO procesor
PDF
FO RTF HTML
TEX
Obr. 2.1: Postup zpracování dokumentu • Procesory XSLT — slouží pro transformaci XML dokumentu na jiný druh dokumentu. Dokáží vytvořit HTML dokument, TeX dokument, nebo také vytvořit další, odlišně strukturovaný, XML dokument. • Procesory FO — (formátovací objekty) se zaměřují na formát výstupního dokumentu (velikost nadpisů, pozice obrázků,…). Trendem je, aby program pro vytvoření dokumentu zvládal oba tyto procesy a dokázal pomocí XML souboru s obsahem a XSL souboru se stylem vytvořit formátovaný výstup (např. PDF).
2.4
XML editory
DocBook není nic jiného než XML soubor. Je to textový soubor, který je možné editovat prakticky v libovolném nástroji pro úpravu textu. Je ale vhodné si vybrat takový nástroj, který podporuje práci s XML, nebo ještě lépe s DocBookem. XML je tak rozšířené, že alespoň zvýraznění syntaxe dokáže dnes naprostá většina textových editorů. Typickými zástupci vhodných XML editorů jsou např. Sublime Text nebo PSPad. Druhou kategorií jsou editory, které mají v sobě zabudovanou přímo podporu DocBooku. Od jednodušších, které našeptávají a doplňují syntaxi, až po pokročilé, které pracují nad úrovní zdrojového kódu a částečně se přibližují WYSIWYG editorům, jako je například Microsoft Word. Kombinace takového pokročilého editoru s DocBookem může vytvořit velice silný a uživatelsky příjemný nástroj pro úpravu dokumentů, bohužel většina těchto editorů je komerčních. Za zmínku stojí například editory XML Editor a XMLmind XML Editor.
17
3
Metodika
3.1
Analýza problému
Prvním krokem je nastudování vlastností a možností DocBooku. Je nutné si dopředu uvědomit, co vše tento nástroj povoluje. Podle toho se vytvoří základní struktura textového dokumentu. Po zvolení vhodné struktury a vytvoření základního konceptu je potřeba vybrat vhodný procesor, který vygeneruje výstup. Dále se vytvoří XSL styl, který zvolená data DocBooku naformátuje. V poslední řadě je nutné vytvořit podrobný návod, který studentům popíše práci s hotovou šablonou a také její instalaci.
3.2
Volba struktury
Ze všeho nejdřív je potřeba nastudovat možnosti DocBooku. DocBook je rozsáhlá definice struktur a elementů, které do sebe zapadají a mají nějaký řád. Pro šablonu je nutné zvolit takový koncept, který bude co nejméně narušovat a který se bude co nejméně odchylovat od pravidel a schématu DocBooku. Ne na každou situaci je DocBook připravený a to je potřeba řešit. Jak píše oficiální dokumentace (Walsh–Hamilton, 2010): „If you change DocBook, it’s not DocBook anymore!“1. Licence DocBooku dává komukoliv právo jej měnit a modifikovat, ale tuto modifikaci pak již není možné nazývat DocBookem.
3.3
Volba procesoru
Při volbě procesoru je nutné brát v potaz hlavně potencionální koncové uživatele šablony. Student pro vypracování své závěrečné práce zpravidla nebude investovat do komerčního procesoru. Velice důležitým bodem při výběru je podpora českého jazyka. Procesory ne vždy podporují všechny znaky latinky již v základu. Podpora českých fontů se musí buď doinstalovat, a nebo tato podpora není obsažena vůbec. Posledním, ale stejně důležitým bodem je kvalita výstupu koncového dokumentu. Je žádoucí, aby procesor plně podporoval jazyky DocBook i XSL. V opačném případě by se mohlo stát, že nedocílíme chtěného výsledku. Požadavky na procesor z pohledu studenta: • • • • 1
zdarma, dostupnost mezi platformami, podpora českých znaků a dělení slov, kvalita výstupu. Přeloženo: „Pokud pozměníte DocBook, již to nebude DocBook“.
18
3.4
3
METODIKA
Vytvoření vzhledového souboru
Tato část práce je zaměřená na vytvoření XSL stylu. Výsledný PDF dokument, jehož formát a vzhled určuje tento styl, bude splňovat všechny doporučené normy a vyhlášky. Je žádoucí, aby se vzhled povinných částí dokumentu (titulní strana, prohlášení, poděkování,…) co nejvíce přibližoval stávajícím oficiálním šablonám fakulty. Vzhledový soubor by měl být srozumitelně okomentován. A to zejména pro případ, kdyby si student chtěl šablonu upravit ke své spokojenosti. Může se jednat o změnu fontu dokumentu nebo velikosti nadpisů, ale i o větší zásahy, např. změna struktury titulních stran.
3.5
Vytvoření návodu
Návod poslouží studentům k připomenutí základních typografických pravidel. Popíše struktury DocBooku na názorných ukázkách kódu. Vysvětlí instalaci a spuštění všech potřebných nástrojů k vygenerování dokumentu.
19
4
Realizace
4.1
Volba struktury
4.1.1
Deklarace typu dokumentu
Od verze 5.0 v DocBooku není třeba deklarovat DTD (Document Type Definition). Schéma DocBooku je načteno pomocí modernějšího jazyka RELAX NG v parametru xmlns u elementu book (Walsh–Hamilton, 2010). Do „knihy“ se potom vkládají všechny ostatní prvky. V šabloně je přesto zadefinován i DTD a to z důvodu deklarace entit. Entity nám poslouží jako lokální přepisy složitějších zápisů. ]> Entity lze importovat hromadně zápisem: %allent; Za pomocí entit může student také rozdělit dokument mezi více souborů. Obzvláště pro obsáhlejší práce je tato možnost žádoucí a může značně zpřehlednit celý zdrojový dokument.
4.1.2
Titulní strana a povinné prvky
Povinné prvky, které jsou obsaženy na začátku každé práce se definují v části . Je třeba uložit údaje: – – – – – –
název závěrečné práce, typ práce (bakalářská, diplomová,…), autor, vedoucí práce, údaje o škole a fakultě, rok publikace,
20
– – – –
4
REALIZACE
poděkování, čestné prohlášení, abstrakt v anglickém a českém jazyce, klíčová slova.
• Titulní strana — Pro název a typ práce jsou použity elementy a <subtitle>. Jméno autora je v elementu , v kterém je zanořen . Vedoucí práce je uložen v elementu . Role „advisor“ v elementu upřesňuje, že se jedná o vedoucího. Samotné jméno se nachází v . Údaje o škole jsou k naleznutí v elementu . Název univerzity v a název fakulty v . Poslední údaj, který se vkládá na titulní stranu je , což je rok vydání. • Poděkování — Za titulní stranou následuje poděkování. Zde vzniká první komplikace. Pro poděkování je v DocBooku určený element . Ten se ale nevkládá do části , nýbrž jako samostatná kapitola do „top-level“ elementu . Tahle skutečnost brání přehlednému uspořádání struktury šablony a komplikuje formátování titulních listů (více v sekci 4.3.3: Titulní strana). Tento problém se dá vyřešit nahrazením elementu a místo něj použít <note role="acknowledgements">. Tato situace by šla vyřešit více způsoby. Např. jednou z možností je vytvoření vlastního jmenného prostoru, což by umožnilo tvorbu vlastních elementů (např. ), ale byla zvolena varianta „Co nejméně zasahovat do struktury DocBooku“. • Čestné prohlášení — Čestné prohlášení je v šabloně již předvyplněno v části . Datum je vloženo instrukcí, která při překladu procesorem vygeneruje aktuální datum. • Abstrakty — Pro abstrakt je v DocBooku přichystán element . V závěrečné práci MENDELU je abstrakt uveden ve dvou jazycích společně s klíčovými slovy. Element se tedy použije dvakrát, pouze s jiným jazykovým parametrem lang. Klíčová slova jsou součástí jednotlivých abstraktů.
4.1.3
Vlastní text
Všechny hlavní prvky textu jsou tvořeny přesně podle filozofie DocBooku a bylo by zbytečné je tu rozepisovat znovu. Tyto prvky jsou podrobně popsány v dokumentaci, která je dostupná knižně (Walsh–Hamilton, 2010) i zdarma elektronicky na internetu. Jediným menším odloučením od struktury jsou bibliografické citace. • Bibliografické citace — Je důležité docílit správného zápisu citované literatury podle české normy (ČSN ISO 690, 1996). Zápis citace, která vygeneruje normovaný text vypadá následovně:
Volba procesoru
21
Walsh–Hamilton, 2010WALSH, N., HAMILTON, R.DocBook 5: The Definitive Guide Sebastopol: O'Reilly Media, 2010. ISBN 978-0-596-80502-9. V tomto případě se vygeneruje následující text: WALSH, N., HAMILTON, R. DocBook 5: The Definitive Guide. Sebastopol: O'Reilly Media, 2008. ISBN 978-0-596-52721-1. Ve zkratce je zápis automaticky generovaného odkazu. V je název citace, ten je v textu vysázen řezem kurziva.
4.2
Volba procesoru
Hlavním výstupem šablony je PDF dokument. Postup vytvoření takového dokumentu znázorňuje obrázek 2.1 – Postup zpracování dokumentu. Nejprve se pomocí XSLT procesoru přetransformuje zdrojový dokument do tzv. formátovacích objektů, za pomocí kterých je následně vygenerován výstupní dokument PDF.
4.2.1
Dostupné FO-procesory
Některé komerční procesory nabízejí bezplatné vyzkoušení svých verzí. Zmíním procesor XEP od společnosti RenderX, který ve verzi trial na každou stránku do zápatí vkládá vodoznak. Procesor XEP lze ovládat i skrze grafické uživatelské rozhraní, narozdíl od většiny procesorů (XEP Engine, c2014). Komerční procesor XMLMind XSL-FO Converter nabízí na vyzkoušení verzi „Evaulation“. Ve výstupu se ale náhodně zdvojují některá písmena (XMLmind XSLFO Converter, c1014). Jeden z hlavních parametrů, které student od programu očekává je dostupnost zdarma. Následující výběr procesorů proto obsahuje pouze nekomerční procesory. • Apache™ FOP — Kvalitní open-source projekt od společnosti Apache. Je vytvořen v jazyce Java, což ho staví do pozice multiplatformních aplikací. Podporuje velké množství výstupních formátů jako jsou pdf, ps, png, rtf nebo txt. Je aktivně vyvíjen a plně podporuje psaní v českém jazyce. Pro výstup PDF v současné době ve verzi 1.1 podporuje typy fontů Type 1 a TrueType (ttf). Fonty OpenType (otf) jsou ale autory přislíbeny v příští verzi. • PassiveTex — Jak již název napovídá, PassiveTex je knihovna TeX maker, které mohou být použity k transformaci XML dokumentu. Pomocí TeXu dokáže z formátovacích objektů vytvořit výstup PDF. Přidáním TeXu do procesu přináší kvalitní typografické algoritmy a nové možnosti zápisů matematických vzorců. Neob-
22
4
REALIZACE
sahuje však celý standard formátovacích objektů a je nutné dávat pozor, které stylové vlastnosti jsou použity. • xmlroff — Další open-source varianta procesoru, tentokrát napsaném v jazyce C a založeném na knihovnách GNOME. Podporuje OpenType fonty, ale podpora formátovacích objektů není kompletní.
4.2.2
Vyhodnocení
Zúžením výběru na nekomerční procesory se značně snížili možnosti. Procesor FOP od společnosti Apache poskytne vše, co se od procesoru očekává. Drobné nedostatky ze starších verzí se autorům již podařilo opravit a vývoj stále aktivně pokračuje. V příští verzi autoři přislíbili podporu OpenType fontů, což znovu přispěje ke kvalitnějšímu typografickému zážitku. FOP dostatečně podporuje psaní v českém jazyce a nemá problém ani s českým slovníkem dělení slov. Podpora složitějších matematických vzorců v jazyce MathML je zajištěna knihovnou JEuclid, která se do procesoru dá doinstalovat jako plugin.
4.3 4.3.1
Vytvoření vzhledového souboru Vzhled strany
Velikost listu lze nastavit v parametru paper.type. Pro šablonu je ve výchozím nastavení zvolen formát A4, ale lze jej přenastavit na americký formát USLetter1. Parametry pro nastavení jednotlivých okrajů popisuje obrázek 4.1 (Stayton, 2007). page.m argin.t op Header
region.before.ext ent body.m argin.t op page.m argin.out er
Body page.m argin.inner
body.m argin.bot t om Foot er
region.aft er.ext ent page.m argi.bot t om
Obr. 4.1: Parametry rozložení stránky 1
A4 – 210 x 297 cm, USLetter – 216 x 279 cm
Záhlaví a zápatí
23
Nastavení vnitřního a vnějšího okraje je závislé na použití dvoustránkového či jednostránkového dokumentu (double.sided). V případě dvoustránkového dokumentu se nechává širší vnitřní okraj z důvodu svázání práce do vazby. Naopak při jednostránkovém dokumentu je zrcadlo stránky vycentrováno. <xsl:param name="page.margin.inner"> <xsl:choose> <xsl:when test="$double.sided = 1">35mm <xsl:otherwise>27.5mm Rozměry horního a spodního okraje stránky jsou nastaveny na 30 mm. Vnitřní okraj 35 mm a vnější okraj 20 mm. V případě jednostránkového dokumentu jsou vnitřní a vnější okraj oba po 17,5 mm. Rozměry byly převzaty z (Doporučení pro úpravu závěrečných prací, 2009).
4.3.2
Záhlaví a zápatí
Obsah záhlaví nebo zápatí lze měnit upravením šablony header.content (footer.content). Jsou nám k dispozici čtyři parametry, kterými lze zjistit na jaké stránce se záhlaví (zápatí) právě nachází. Parametr pageclass definuje třídu stránky (titlepage, body, lot,…). Sequence určuje pořadí v již zmíněné třídě. Lze odlišit sudé stránky od lichých, což je důležité hlavně u dvoustránkového dokumentu. Také lze odlišit první stránku v kapitole nebo vakát 2 (first, odd, even, blank). Pozici v záhlaví určuje parametr position (left, center, right). Některé stránky mají automaticky generovaný text podle příslušného jazyka knihy. Tyto generované texty lze rozlišit pomocí parametru gentext-key. <xsl:template name="header.content"> <xsl:param name="pageclass" select="''"/> <xsl:param name="sequence" select="''"/> <xsl:param name="position" select="''"/> <xsl:param name="gentext-key" select="''"/> Pomocí těchto parametrů a podmínek jazyka xsl lze vytvořit různé situace použití záhlaví. <xsl:when test="$sequence='odd' and $position='right'"> V šabloně je zvoleno číslování stran na vnější straně záhlaví. Na vnitřní straně je potom název kapitoly, v případě sudých stránek, a název sekce (podkapitoly) 2
Vakát — záměrně vynechaná stránka publikace.
24
4
REALIZACE
v případě stránek lichých. To neplatí u první strany kapitoly a u vakátů, ty mají vnitřní stranu záhlaví prázdnou. U titulní strany a povinných prvků se záhlaví nevypisuje vůbec. Zápatí je v případě šablony prázdné. Toho docílíme ponecháním footer.content prázdným. Je nutné také vymazat oddělovací linku nastavením parametru footer.rule na hodnotu 0.
4.3.3
Titulní strana
Změna vzhledu titulní stránky se v DocBooku netýká pouze jediné fyzické titulní stránky, ale celé skupiny povinných prvků. Do titulní strany se v tomto případě počítají i strany s poděkováním, čestné prohlášení a abstrakty. V DocBooku pro modifikaci těchto titulních stran existuje XSL styl, který přetransformuje XML dokument rovněž do XSL stylu. Ten je pak možné importovat nebo přímo vložit do koncového stylového souboru. Tato možnost uživateli umožní modifikovat XML soubor s jasně danou strukturou. V případě šablony se postupovalo následovně. Nejprve se vygeneroval XSL soubor, který byl následně vložen do hlavního stylu. Poté už se jen lehce poupravil výsledek. Tento XML dokukument obsahuje několik částí vysázených v následujícím pořadí: • • • • •
Jsou rozděleny na části recto (líc) a verso (rub). Tyto části by se daly rozlišit jako „začínající na liché straně“ a „začínající na sudé straně“. V případě šablony jsou vkládány pouze položky do částí recto. • — Obsahuje položky title, subtitle, note, legalnotice a abstract. Parametrem break-after a jeho nastavením na hodnotu odd-page je zajištěno vynechání sudé stránky a začátek dalšího prvku na stránce liché. Tahle skutečnost se ve výsledném stylu musí přizpůsobit a pomocí podmínky zajistit, aby při volbě jednostránkového dokumentu procesor skočil „pouze“ na další stránku. Mezi abstrakty se stránka nevynechává a je použito pouze odsazení space-after. Důsledkem toho se obsah, který za abstrakty následuje nevytvoří na stránce následující, ale hned za abstrakty. Tento problém lze vyřešit přidáním parametru break-before právě obsahu (toc.margin.propereties). • — Prvky z části before se vypíší ještě před částí content. Obsahuje dodatečné prvky první strany. Jsou to orgname, orgdiv, personname, colabname a pubdate.
Písmo
25
Každý z prvků je vložen do jednotlivých částí jako blok (fo:block), který je možné stylizovat a pozicovat. Někdy je zapotřebí zarovnat prvky na spodní část stránky. Toho lze docílit vložením bloku do kontejneru, který je napozicován absolutně. Příkladem může být například rok publikace: Brno <xsl:value-of select="/book/bookinfo/pubdate"/>
4.3.4
Písmo
Velikost písma je ve výchozím nastavení na 12 bodech (body.font.master). Řádkování line-height je nastaveno na hodnotu normal. Tato hodnota je závislá na stupni písma a pohybuje se okolo 120% jeho hodnoty. Použitý font písma se nastavuje parametry body.font.family pro tělo dokumentu, title.font.family pro nadpisy a momospace.font.family pro neproporciální písmo. Případně jdou nastavit i další rodiny písma například pro symboly – symbol.font.family. Každý student, který využije šablony, má možnost písmo změnit a zvolit si písmo vlastní. Je ale vysoce pravděpodobné, že naprostá většina studentů ponechá písmo výchozí, a také proto je nutné toto výchozí písmo volit kvalitní a univerzální. Jako výchozí font byla vybrána písma Computer Modern Unicode. Fonty jsou pod licencí „X11 License“, tudíž jsou zdarma a je možné je přiložit do archivu se šablonou. Je to takzvaná superrodina, která obsahuje písma serifového typu, bezserifového typu i neproporciální typ písma. Toto písmo je dostatečně univerzální a vhodné pro odborné publikace. Bezserifový typ písma byl nahrazen fontem Latin Modern, který má lépe vyřešená diakritická znaménka. Tyto fonty jsou pod licencí „GFL“ (GUST Font License, c2014).
4.3.5
Generovaný text
Automaticky generovaný text, jako jsou např. popisky u tabulek a obrázků nebo názvy kapitol, lze modifikovat úpravou jazykových stylů v parametru local.l10n.xml. Názvy kapitol jsou upraveny do formátu „číslo a název kapitoly“ oddělené čtverčíkovou mezerou. U obrázků a tabulek je popisek ve tvaru třípísmenné zkratky, za níž následuje číslo a popisek. <xsl:param name="local.l10n.xml" select="document('')"/>
26
4
REALIZACE
4.3.6
Obsah
Obsah se v DocBooku generuje automaticky z názvů kapitol a sekcí, nicméně lze jej upravit do podoby, která je vyhovující. Parametry toc.section.depth a generate.toc jsou hned na začátku stylu pro potřeby uživatele pozměnit tyto hodnoty. Určují jak podrobný obsah bude, a které obsahy se budou generovat. V parametru generate.toc je možnost určit, zda se bude generovat pouze seznam kapitol nebo i seznam obrázků či tabulek. V toc.line.propereties lze modifikovat vlastnosti jednotlivých řádků v obsahu. V případě šablony jsou rozlišeny „top-level“ kapitoly a ty jsou vysázeny silným řezem s větším odsazením. Jsou to prvky chapter, bibliography, appendix a glossary. Jsou vyselektovány podmínkou: <xsl:when test="self::chapter or self::bibliography or » self::appendix or self::glossary">bold <xsl:otherwise>normal V poslední řadě se ještě musí modifikovat obsah jednotlivých řádků, kde je ve výchozím nastavením, jako oddělovač čísla kapitoly a jejího názvu, použita tečka. V šabloně je jako oddělovač použitá mezera o velikosti čtverčíku. <xsl:if test="$label!=''"> <xsl:copy-of select="$label"/> <xsl:text>
4.3.7
Odkazy citací
Pro zápis odkazů na citace podle Harvardského systému je nutné změnit výchozí hranaté závorky kolem odkazu za kulaté. Tento druh citací používá i oficiální šablona pro LaTeX a proto byl upřednostněn. <xsl:template match="biblioentry|bibliomixed" mode="xref-to-prefix">
V šabloně je vytvořeno několik speciálních instrukcí pro procesor, které studentovi mohou pomoci s formátováním textu. Zapisují se ve tvaru {název instrukce} {parametr}?>. • vskip — Tato instrukce vertikálně vynechá určité místo upřesněné v parametru. • hskip — Stejné jako vskip ale v horizontálním směru. • linebreak — Instrukce bez parametru, která v daném místě ukončí řádek. Lze využít i elementu <sbr/>. • dots — Místo o vzdálenosti určené v parametru vyplní tečkami.
4.4
Vytvoření návodu a archivu
Návod je vytvořen jako samostatná následující kapitola práce. Jsou zde popsány všechny základní konstrukce, které jsou důležité při tvorbě publikace. Obsahem archivu jsou vzorové zdrojové soubory. Zdrojový soubor index.xml je základem obsahové části šablony. V tomto souboru se nacházejí pouze meta-informace na titulní stranu a ostatní povinné prvky, seznam literatury a případně slovníček pojmů. Vlastní text práce je vzorově naznačen v souboru chap.uvod.xml, který je do indexu vložen. Šablona samozřejmě nikoho nenutí tímto způsobem rozdělovat kapitoly do souborů, ale je tu naznačena tahle možnost. Dále je obsahem archivu samotný stylový soubor styl.xsl. Ve stylu jsou okomentovány všechny parametry a není problém styl modifikovat pro vlastní potřeby. V konfigurečním souboru fop-cs.xconf je nastavena cesta k fontům. nullfonts
28
4
REALIZACE
Pomocí auto-detect jsou načteny všechny systémové fonty a navíc jsou načteny fonty ze složky fonts, která je také součástí archivu. Jsou v ní obsaženy fonty Computer Modern a Latin Modern. V archivu jsou dále dva soubory PDF, navod.pdf z již zmiňovaným návodem a vystup.pdf jako ukázka výstupu vzorového indexu.
29
5
Návod stylu
5.1
Instalace
K vygenerování požadovaného výstupu si vystačíme s textovým editorem a nainstalovaným XSL-FO procesorem.
5.1.1
Textový editor
Pro tvorbu práce je možné zvolit libovolný textový editor. Pro pohodlné psaní je vhodné volit editory, které zvýrazňují syntaxi XML. Existují i takové nástroje, které „našeptávají“ (automaticky doplňují) strukturu DocBooku. Vhodnými zástupci mohou být např. PSPad nebo SublimeText. TIP: Do textového editoru Sublime Text lze nainstalovat velké množství rozšíření. Je možné jej přizpůsobit tak, aby splňoval všechny požadavky pro pohodlnou práci se šablonou. Zvýrazňení sytaxe XML je samozřejmost. Pomocí rozšíření lze zařídit, aby automaticky doplňoval struktury DocBooku a také vytvořit „build script“, který exportuje dokument.
5.1.2
XSL-FO procesor
Procesorů, které textový DocBook dokument převedou a naformátují do PDF výstupu, je na výběr větší množství. Návod je zaměřen na procesor FOP, který je opensource variantou od společnosti Apache™. Instalace FOP je podrobně popsána na webových stránkách projektu. Také je možné využít instalace na školním serveru akela. Pro načtení systémových fontů je potřeba spouštět procesor s parametrem -c, který odkazuje na konfigurační soubor přiložený k šabloně. Příkaz pro vygenerování výsledného pdf může vypadat takto:1 fop -xml index.xml -xsl styl.xsl -pdf vystup.pdf -c fop-cs.xconf Bude-li nutné v práci používat složitější matematické vzorce, musí být nainstalována podpora MathML pro FOP. To zajišťuje knihovna JEuclid. Na školní síti je tohle rozšíření nainstalováno.
5.2
Základní dokument
Prázdný vzorový dokument je součástí archivu šablony. Hned na začátku dokumentu, v části definice DOCTYPE lze definovat entity. Ty lze použít k ulehčení složitěj1
Jsou použity relativní cesty k souborům, je tedy nutné spustit program ze stejného umístění, kde jsou soubory nebo použít cesty absolutní.
30
5
NÁVOD STYLU
šího zápisu znaku (např. nedělitelná mezera), ale lze také vytvořit odkazy na další zdrojové soubory2. V části jsou informace použité do titulních stránek práce jako jsou jména autora a vedoucího, název práce, ale také čestné prohlášení a abstrakty. Je možné modifikovat také stylový soubor styl.xsl. Tento soubor obsahuje veškeré nastavení formátu výsledného dokumentu. Některá nastavení jsou vypsána v tabulce 5.1. Tab. 5.1: Nastavení stylu parametr
Struktura DocBook dokumentu sama od sebe vynechává přebytečné mezery, to platí i pro nové řádky. Proto je nutné každý odstavec vložit do elementů <para>. V textu odstavce je často potřebné zvýraznit část textu nebo vložit nějaký speciální znak. • Zvýrazněný text — se v DocBooku zapisuje pomocí značek <emphasis> Zvýrazněný text . Ve výchozím nastavení se pro zvýraznění použije řez kurziva, pro zvýraznění textu „tučně“ použijeme strukturu <emphasis role="strong"> Tučný text . • Uvozovky — se v každém jazyce mohou psát odlišně. Tento problém řeší DocBook sám. Stačí uvozený text vložit do elementů „Text v uvozovkách“ quote> a procesor si už sám podle zvoleného jazyka práce vybere ty správné. „Systém si dokáže poradit i s ‚vnitřními‘ uvozovkami.“ • Mezery (Pecina, 2012) — existují hned v několika variantách. Základní mezerou mezi slovy je tzv. mezislovní mezera. Při zarovnání do bloku je její velikost proměnlivá. V dokumentu se zapisuje klasickým mezerníkem. 2
Rozdělením zdrojového souboru do více souborů (např. každá kapitola bude mít svůj vlastní soubor) lze dosáhnout lepší přehlednosti kódu.
Kapitoly a sekce
31
Podle Pravidel českého pravopisu jsou ale případy, kdy je nutné zajistit, aby textový procesor tuhle mezeru nenahrazoval odřádkováním. K tomu slouží tzv. nezlomitelná mezera3. V DocBooku ji zajišťuje entita „&nbps;“ vložená mezi slova. To může vypadat třeba takto „V&nbps;DocBooku“. Jinou variantou nezlomitelné mezery může být tzv. zúžená mezera o velikosti pětiny čtverčíku, Zapíše se entitou „ “, nebo tzv. vlasová mezera, která může sloužit pro řešení různých kolizí v textu. Zapíše se pomocí „ “. • Další znaky — jsou vypsány v tabulce 5.2 (Entity). Tab. 5.2: Entity Znak nedělitelná mezera
Znak mínus se od pomlčky liší svým umístěním. Pokud je položený vedle znaménka plus, musí být tyto dva znaky ve stejné výšce. (+ −).
5.4
Kapitoly a sekce
Pro vložení kapitoly nebo sekce se v DocBooku využívají elementy a <section>. Sekce jsou chápány jako podkapitoly a můžou být dále zanořovány do sebe, čímž vznikají podsekce. Každou kapitolu (sekci) je možné pojmenovat v . Číslování kapitol procesor automaticky při překladu udělá za nás. 3
Použití nezlomitelných mezer: jednoznakové předložky (v Praze), v nadpisech i za víceznakové (do USA), za akademické tituly (Mgr. Filip), mezi čísla a měsíce v datech (12. 1. 1982), za zkratky (čs. voják), u zkrácených jmen (F. X. Šalda) a jmen králů (Karel IV.) atp.
Existují dva druhy seznamů, a to číslovaný a nečíslovaný . Jejich položky se značí jako <listitem>. Seznamy se do sebe mohou vzájemně zanořovat. U seznamů je někdy vhodné použít parametr spacing="compact". Ten minimalizuje odsazení jednotlivých položek. U číslovaného seznamu stojí za zmínku parametr continuation, který naváže na číslování předchozího seznamu, nebo parametr numeration pro volbu stylu číslování. <listitem> <listitem> <para>první, <listitem> <para>druhý, <listitem> <para>třetí. Ukázka znázorňuje příklad zápisu číslovaného seznamu, který jako první položku má další (již nečíslovaný) seznam. Tento zápis vytvoří následující seznam:
Tabulky
33
I. • první, • druhý, II. třetí.
5.6
Tabulky
Každá číslovaná tabulka
nebo nečíslovaná musí obsahovat alespoň jednu skupinu buněk , kde se definují vlastnosti sloupců. Do těchto sloupců se po řádcích vkládají jednotlivá data. Ke spojení buněk v tabulce slouží parametry namest, nameend a pro spojení řádků parametr morerows. Tyto parametry se přiřazují datovému elementu <entry>. Pro horizontální seskupení, tedy pomocí namest a nameend, je nutné pojmenovat sloupce v . Příkladná Ukázka tabulky (5.3):
Strukturu pro vložení obrázku tvoří několik elementů. Používá se <mediaobject>, do kterého se vkládají samotné obrázky . Takových může být více4. Celá tato struktura je obalena elementem