DocBook útmutató Jeszenszky Péter Debreceni Egyetem, Informatikai Kar jeszenszky.peter@inf.unideb.hu
Mi a DocBook? (1) XML formátum műszaki dokumentációhoz Eredetileg hardver és szoftver dokumentáció készítéséhez fejlesztették ki, de tetszőleges célra használható Nyílt szabvány, amely az iparban széles körben elterjedt és használt, de-facto szabvány Stíluslapok és egyéb eszközök szolgálnak a DocBook XML dokumentumok különböző formátumokba alakítására (például HTML, PDF, TeX, RTF, ) 2
Mi a DocBook? (2) Nem alternatívája például a LaTeX használata! Kiforrott szabványokon és technológiákon alapuló egyszerű, szöveges elektronikus dokumentumformátum, amely gyártó- és platformfüggetlen módon teszi lehetővé strukturált dokumentumok szövegének időtálló megőrzését Független bármiféle feldolgozó és megjelenítő szoftvertől Nem ördögtől való dolog, a jövőnek szól 3
Mire szolgál? Segítségével a dokumentumok logikai szerkezetét lehet leírni, szó sincs megjelenítésről Nem lehet például szöveget középre igazítani vagy betűtípusokat használni, betűméretet beállítani A felhasználó a szövegben a különböző szerkezeti elemeket jelölheti meg (jelölőnyelv) Például fejezeteket, bekezdéseket, betűszavakat, idegen szavakat és kifejezéseket, idézeteket, változók, kivételek, osztályok és interfészek nevét Nagyon gazdag szövegannotációs lehetőségekben 4
Jelölőnyelv Példa: <para>az <acronym>xml</acronym> az iparban <foreignphrase lang="la">de facto</foreignphrase> szabvány.</para> A szöveg különböző részeinek ilyenforma megjelölése hozzáadott értéket jelent Nincs hozzáadott érték például LaTeX dokumentumok automatikus konverziója esetén! A feldolgozó alkalmazások tetszőlegesen hasznosíthatják a szöveget és az annotációkat Így például megfelelően jeleníthetik meg a különböző módon megjelölt szövegrészeket 5
Megjelenítés? Különböző eszközök szolgálnak a DocBook XML dokumentumok megjelenítésre alkalmas formába alakításához Akár ma még nem létező eszközökön is lehetséges lesz a megjelenítés, mivel a DocBook dokumentumok egyszerűen feldolgozható szövegállományok (XML dokumentumok) 6
Szabvány A szabvány felelőse az OASIS DocBook Technical Committee http://www.oasis-open.org/committees/docbook/ A szabvány jelenleg aktuális verziója az 5.0 The DocBook Schema Version 5.0 (2008. augusztus 12.) RELAX NG séma formájában adott a formátum Van W3C XML Schema és DTD változat, de a RELAX NG séma a normatív 7
Néhány felhasználás Szoftver dokumentálás: Fedora Project http://fedoraproject.org/ FreeBSD http://www.freebsd.org/ GNOME http://developer.gnome.org/doc/ KDE http://www.kde.org/ PHP http://php.net/ PostgreSQL http://www.postgresql.org/ The Linux Documentation Project http://www.tldp.org/ Könyvkiadás: O'Reilly Media http://oreilly.com/ 8
Hasznos címek DocBook Technical Committee Document Repository http://www.oasis-open.org/docbook/ DocBook.org http://www.docbook.org/ DocBook Wiki http://wiki.docbook.org/ DocBook-specific publishing tools http://wiki.docbook.org/topic/docbookpublishingtools The DocBook Project http://docbook.sourceforge.net/ 9
DocBook 4.x és DocBook 5.0 A DocBook 5.0 szabványt megelőző DocBook 4.x verziók közül a legutóbbi a DocBook 4.5 Az alapvető különbség az, hogy az 5.0 verzió XML séma (RELAX NG) alapú, a korábbi verziók pedig DTD alapúak Ebből kifolyólag az 5.0 verzió például környezetfüggő módon definiálja az elemek tartalommodelljét XML névterek használata az 5.0 verzióban, amely rugalmas integrálást tesz lehetővé más XML formátumokkal (például MathML, SVG) Nem kompatibilis egymással a 4.x és 5.0 verzió Adottak eszközök (XSLT stíluslapok) DocBook 4.x dokumentumok DocBook 5.0 dokumentumokká konvertálásához 10
DocBook 4.4 és DocBook 4.5 A TÁMOP pályázatban a DocBook 4.x verziók közül a 4.4 használatát várják Elhanyagolható különbség van a 4.4 és a 4.5 verzió között Lásd: http://www.oasis-open.org/docbook/specs/docbook-4.5-spec.html Minden DocBook 4.4 dokumentum érvényes DocBook 4.5 dokumentum (visszafelé kompatibilitás) 11
DocBook: The Definitive Guide DocBook: The Definitive Guide V2.0.17 (2006. október 11.) http://www.docbook.org/tdg/ Szerzők: Norman Walsh, Leonard Muellner Licenc: GNU Free Documentation License (GNU FDL) A DocBook V4.5 szabványt tárgyalja XML források (DocBook V4.4): http://docbook.svn.sourceforge.net/viewvc/docbook/trunk/de 12
DocBook 5.0: The Definitive Guide DocBook 5.0: The Definitive Guide V0.0.25 (2008. március 3.) http://docbook.org/tdg5/ Szerző: Norman Walsh Licenc: GNU Free Documentation License (GNU FDL) XML források (DocBook 5.0): http://docbook.svn.sourceforge.net/viewvc/docbook/trunk/de 13
Minták A TÁMOP pályázat kiírói által biztosított minta: http://www.hik.hu/tankonyvpalyazat/minta_xml/minta_20 Version Control with Subversion http://svnbook.red-bean.com/ XML források (DocBook V4.4): http://code.google.com/p/svnbook/ Letöltés a projekt Subversion tárolójából lehetséges az alábbi paranccsal: svn checkout http://svnbook.googlecode.com/svn/trunk/ svnbook-read-only 14
Szoftverek DocBook szerkesztéshez Nyílt forrású szoftverek: Conglomerate http://www.conglomerate.org/ (GNU GPL) (Linux, Mac OS X) Serna Free http://www.syntext.com/products/serna-free/ (GNU GPL) (Linux, Mac OS X, Solaris, Windows) Egyéb ingyenes, de nem nyílt forrású szoftverek: XMLmind XML Editor Personal Edition (Pixware) http://www.xmlmind.com/xmleditor/persoedition.html (Linux, Mac OS X, Windows) Kereskedelmi szoftverek: Altova XMLSpy (Altova) http://www.altova.com/ (Windows) Oxygen XML Editor (SyncRO Soft) http://www.oxygenxml.com/ (Linux, Mac OS X, Windows) 15
Oxygen XML Editor Professzionális XML szerkesztő, amely minden létező és elterjedten használt XML-alapú technológiát támogat Fejlett DocBook XML támogatást ad (például WYSIWYG szerkesztő), ehhez semmilyen egyéb szoftver telepítését nem igényli Elérhetőség: http://www.oxygenxml.com/ Kereskedelmi szoftver A honlapról letölthető program teljesen funkcionális, de csak 30 napig használható A Java programozási nyelven készült alkalmazás Linux, Mac OS X és Windows környezetben is telepíthető Elérhető Eclipse bővítményként is 16
Az Oxygen XML Editor telepítése A 30 napos ingyenes használathoz is próbalicenc szükséges, amelyet a következő címen lehet igényelni: http://www.oxygenxml.com/register.html Próbalicenc a program felhasználói felületéről is kérhető A licencet a regisztráció során megadott email címre küldik el, az üzenetből az alábbi sorok határolta szöveget kell az első programfuttatás során megadni: ------START-LICENSE-KEY------ licenc kulcsot tartalmazó szöveg -------END-LICENSE-KEY------- 17
DocBook XML dokumentumok megnyitása Állományrendszerből: File Open Webről: File Open URL Támogatott protokollok: HTTP(S), (S)FTP, HTTP/WebDAV Az utóbbi használata lehetővé teszi weben elérhető dokumentumok módosítását is 18
Új DocBook XML dokumentum létrehozása (1) File New... From template DocBook 4 Book 19
Új DocBook XML dokumentum létrehozása (2) A dokumentum létrehozásánál alapértelmezésben a DocBook XML 4.4 DTD-t használja a program A TÁMOP pályázatban nem DTD, hanem XML séma használatát várják el! A dokumentum forrását ennek megfelelően kell módosítani (lásd például a minta dokumentumokat) Ez a dokumentumtípus-deklaráció törlését jelenti (<! DOCTYPE >), valamint az alábbi attribútum-specifikációk megadását a book gyökérelem nyitócímkéjében: xmlns:xsi="http://www.w3.org/2001/xmlschemainstance" xsi:nonamespaceschemalocation="http://docbook.org/x sd/4.4/docbook.xsd" 20
Dokumentum szerkesztés 3 különböző módon lehet a DocBook XML dokumentumokat szerkeszteni: Szöveges mód (Text): XML forrás szerkesztése Rács mód (Grid): XML dokumentum szerkesztése táblázatos formában Ez DocBook XML dokumentumok esetén nem valami hasznos és kényelmes Szerző mód (Author): WYSIWYG szerkesztés (a dokumentum egy lehetséges vizuális megjelenítése) Szerkesztőmód váltás a Document Edit menüben vagy a szerkesztőablak bal alsó sarkában lehetséges: 21
Szöveges mód (1) Automatikus kiegészítés: a szerkesztő a gépelés során választásra kínálja fel a lehetőségeket, például hogy a dokumentum aktuális pontján milyen elemeket, attribútumokat vagy szöveget lehet beszúrni 22
Szöveges mód (2) A kijelölt szövegen a jobb egérgombbal előhívható menüben végezhetünk műveleteket (például a Refactoring Surround with/surround withs Tags menüben lehet a kijelölt szöveget a kiválasztott elembe zárni) 23
WYSIWYG szerkesztő (1) 24
WYSIWYG szerkesztő (2) A menüsorban az ilyen szerkesztőkben megszokott ikonok (a funkciókat el lehet érni a szintén a menüsorban lévő DocBook menüből is) 25
Dokumentum érvényesítés (1) Document Validate Validate Document (Ctrl+Shift V), de a funkció elérhető a nagy piros pipás ikonra kattintva is A program egyébként a gépelés közben automatikusan is jelzi a hibákat 26
Dokumentum érvényesítés (2) A hibák a szerkesztőablak alatt jelennek meg 27
Dokumentum megjelenítése Meg kell adni azokat a transzformációs beállításokat, amelyek alapján létrehozásra kerül egy eredmény állomány Adottak gyári beállításokat tartalmazó kész transzformációs forgatókönyvek, amelyeket módosítani is lehet (testreszabhatóság) A beállítást csak egyszer kell elvégezni, a transzformálás az aktuálisan kiválasztott forgatókönyv alapján történik A következő példában a dokumentumot egy XHTML weboldallá alakítjuk 28
Transzformáció beállítása (1) Válasszuk az alábbit: Document Transform Configure Transformation Scenario (Ctrl+Shift C), vagy kattintsunk a csavarkulcsot és egy kis piros háromszöget ábrázoló ikonra! 29
Transzformáció beállítása (2) A megjelenő ablakban válasszuk ki a Docbook XHTML sort és kattintsunk a Duplicate gombra! 30
Transzformáció beállítása (3) A megjelenő ablak XSLT fülén tetszőleges beszédes nevet adhatunk a transzformációnak a Name mezőben 31
Transzformáció beállítása (4) Az Output fülre váltva a Save As mezőben adható meg az eredmény állomány (az alapértelmezés elfogadása esetén ha például book.xml az XML állomány neve, akkor automatikusan book.xhtml lesz az eredmény állományé) 32
Transzformáció beállítása (5) Ugyancsak az Output fülön kapcsolható be az Open in Browser jelölő (bekapcsolás esetén a transzformáció eredményeként előálló weboldalt automatikusan betölti egy böngészőablakba a program) 33
Transzformáció beállítás (6) Mielőtt az OK gombbal bezárnánk a Configure Trasformation Scenario ablakot, az új transzformáció legyen kiválasztva a listában! 34
Dokumentum transzformálása Válasszuk az alábbit: Document Transform Apply Transformation Scenario (Ctrl+Shift T), vagy kattintsunk a megfelelő ikonra ( nagy piros háromszög )! A Configure Transformation Scenario ablakban kiválasztott transzformációt használja a program 35
Matematikai formulák kezelése A TÁMOP pályázat keretében készülő tanagyagok valamennyi matematikai formuláját különálló állományokban (is) kell tárolni, MathML formátumban és képként is 36
MathML Mathematical Markup Language (MathML) Version 2.0 (Second Edition) (W3C ajánlás, 2003. október 21.) http://www.w3.org/tr/mathml/ XML formátum matematika formulák leírására A formulák megjelenítését, szerkezetét lehet leírni Többféle felhasználás, például matematikai tartalom megjelenítése a weben, komputer algebra rendszerek export formátuma Beágyazhatóság más dokumentumokba (például DocBook V4.x és V5.0 dokumentumokba is) 37
MathML támogatás (1) Néhány szabad és nyílt forrású szoftver: Amaya http://www.w3.org/amaya/ (megjelenítés, szerkesztés) Licenc: W3C Software Notice and License Platform: Mac OS X, Linux, Windows Firefox http://www.mozilla.com/firefox/ (megjelenítés) Licenc: Mozilla Public License Firemath http://www.firemath.info/ (szerkesztés) Licenc: GNU GPL Platform: Firefox (böngésző bővítmény) 38
MathML támogatás (2) Néhány kereskedelmi szoftver: MathMagic (InfoLogic) http://www.mathmagic.com/ (Mac OS X Windows) MathType (Design Science) http://www.dessci.com/en/products/mathtype/ (Windows) Publicon (Wolfram Research) http://www.wolfram.com/products/publicon/ (Linux, Mac OS X, Windows) Scientific WorkPlace/Scientific Word (MacKichan Software) http://www.mackichan.com/ (Windows) 39
Az Oxygen XML Editor MathML támogatása (1) MathML dokumentum létrehozása: File New From template MathML Equation 40
Az Oxygen XML Editor MathML támogatása (2) Szöveges módban a megszokott kényelmi funkciókkal szerkeszthető az XML forrás Szerző (Author) módban a matematikai formulák megjelenítése 41
Az Oxygen XML Editor MathML támogatása (3) Szerző (Author) módban a jobb egérgombbal a formulán duplán kattintva egy olyan szerkesztőablak jelenik meg, amelyben egyszerre látható a formula és az XML forrás 42
Az Oxygen XML Editor MathML támogatása (4) Az alapértelmezésben rendelkezésre álló eszköztár nehézkesen használható formulák szerkesztéséhez, hiszen a képleteket XML-ben kell leírni és módosítani Matematikai formulák kényelmes WYSIWYG szerkesztéséhez a MathFlow SDK telepítése szükséges 43
MathFlow (1) Kereskedelmi szoftver, amelynek gyártója a Design Science http://www.dessci.com/ Ez a cég a gyártója a minden Microsoft Office verzióban megtalálható Equation Editor képletszerkesztőnek Utóbbi csupán egy nagyon leegyszerűsített verziója a cég MathType alkalmazásának, amely LaTeX és MathML támogatást is ad Míg a MathType csupán Windows és Mac OS X környezetben működik, a MathFlow Linux rendszerekben is használható Sajnos még kipróbálásra sem tölthető le ingyen 44
MathFlow (2) MathFlow beállítások az Options Preferences menüben 45
MathType (1) Míg az Oxygen XML Editor-ba integrálható MathFlow még kipróbálásra sem tölthető le ingyen, addig a MathType képletszerkesztőből elérhető egy 30 napig használható próbaverzió Sajnos csak Mac OS X és Windows platformra Ez egy nagyon kényelmes WYSIWYG formulaszerkesztő, amely MathML-be is tudja konvertálni a formulákat Segítségével meglevő LaTeX formulákat is MathML-be lehet alakítani 46
MathType (2) LaTeX formula MathML-be alakításához másoljuk azt a vágólapra! 47
MathType (3) WYSIWYG képletszerkesztő (az ablakban a vágólapon keresztül bemásolt LaTeX formulák) 48
MathType (4) Beállítjuk, hogy a képletszerkesztőből a vágólapon keresztül kimásolt formulákat MathML képletként kívánjuk beilleszteni 49
MathType (4) A vágólapon keresztül a formulát MathML képletként tudjuk beilleszteni (itt egy szövegállományban tároljuk) 50
LaTeX DocBook XML konverzió? Ha valaki tud elfogadható megoldást, jelezze! Az általam ismert egyetlen konverziós szoftver a TeX4ht http://www.cse.ohio-state.edu/~gurari/tex4ht/ Licenc: LaTeX Project Public License (LPPL) Formulákat képes képekké és MathML formátumba is alakítani Negatív tapasztalatok: Nehézkesen használható parancssori eszköz, amelyet bonyolult megfelelően paraméterezni Működik egyáltalán? 51
Befejezés Új tanagyagok DocBook formátumban elkészítésére nagyszerűen alkalmas például az Oxygen XML Editor Sok matematikai formula esetén célszerű a MathFlow vagy MathType programok beszerzése, amelyekkel a képleteket kényelmesen lehet a kívánalmaknak megfelelően elkészíteni Létező, sok matematikai formulát tartalmazó LaTeX dokumentumok DocBook formátumba alakítása valószínűleg nem lesz fájdalommentes 52