DocBook útmutató. Jeszenszky Péter Debreceni Egyetem, Informatikai Kar

DocBook útmutató

Jeszenszky Péter Debreceni Egyetem, Informatikai Kar [email protected]

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 XML az iparban de facto szabvány.

●

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: ●

●

●

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: ●

●

Conglomerate http://www.conglomerate.org/ (GNU GPL) (Linux, Mac OS X)

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, 15 Mac OS X, Windows)

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 (), 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 20 sd/4.4/docbook.xsd"

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) – –

●

Firefox http://www.mozilla.com/firefox/ (megjelenítés) –

●

Licenc: W3C Software Notice and License Platform: Mac OS X, Linux, Windows 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