Chyavanprash Technikai dokumentáció készítése T E X-hel, egyszer en

Átírás

1 Chyavanprash Technikai dokumentáció készítése T E X-hel, egyszer en Ötletek, Önálló laboratórium Készítette: Pintér Lóránt (MXVK23) Konzulens: Jeney Gábor (BME HIT) április 26.

2 Tartalomjegyzék 1. Bevezetés IT projektek dokumentálása A dokumentációval szembeni elvárások A munka menete A folyamat résztvev i A szerz k és lektorok munkája Problémák a dokumentációval kapcsolatban Részletek Összefoglalás Lehet ségek Támogatandó elvárások Felhasználóbarát felület Formázás különválasztása Kapcsolódó feladatok Metaadatok Ellen rzés Integrálhatóság B víthet ség Nem támogatott funkciók Felépítés Felhasználandó technológiák Munkamenet Megvalósítás Els fázis: Tervezés Második fázis: Prototípus Harmadik fázis: Integráció Negyedik fázis: Befejezés

3 1. fejezet Bevezetés 1.1. IT projektek dokumentálása Egy IT projekt kivitelezése jellemz en nem egyemberes munka. Többen, különböz szakterületekr l érkezve dolgoznak együtt a kész termék megvalósításán, együtt a terméket megrendel ügyféllel. A résztvev k közti kommunikáció egyik fontos eszköze a projekt minden területére kiterjed, az egyes területek életciklisát lefed technikai dokumentáció. A termék megrendel je, leend felhasználói is elvárják a részükre készült, az adott megoldást technikai oldalról bemutató dokumentáció meglétét. Ide tartoznak a felhasználói útmutatók, technikai összefoglalók, referenciák, de a projekt során készül rendszeres jelentések is. Jelen dokumentumban a következ ket tekintjük technikai dokumentációnak:... Több más szempont mellett a dokumentáció min sége is nagyban befolyásolja egy projekt sikerességét. A megrendel felé közvetített anyagok a szállító megítélését ronthatják, vagy javíthatják, a felhasználó bevezetése a termék használatába pedig nagyban egyszer södik a jó dokumentációval. A projekten belüli munka során is nagy jelent sége van a dokumentáció min ségének, hiszen segítségével elkerülhet k az esetleges félreértések, melyek id t és energiát emészthetnek fel, vagy a bel lük fakadó hibák akár bent is maradhatnak a végleges termékben A dokumentációval szembeni elvárások Bár a jó min ség dokumentáció látszólag elengedhetetlen feltétele egy sikeres IT projektnek, mégis ritkán fordul el. Tartalmi helyesség Az els és legfontosabb elvárás. Ez alatt értjük a dokumentáció teljességét, mindenre kiterjed voltát, a benne foglalt adatok, információk pontosságát, valóságnak való megfelelését. Érthet ség Hiába helyes és teljes egy dokumentáció, ha az olvasó számára nem érthet, vagy nemhéz benne megtalálni a keresett információt. 2

4 A dokumentum érthet ségét nagyban befolyásolja, hogy felépítése követi-, megfelel en vezeti-e az olvasó gondolatmenetét. Egyes dokumentumok esetében (ilyenek pl. a felhasználói kézikönyvek referencia-jelleg részei) a megfelel strukturáltság segítheti a felhasználót a keresett információ megtalálásában. Mivel egy dokumentum megértéséhez hozzátartozik a struktúra felismerése is, hasznos, ha az egyes, hasonló dokumentumok azonos struktúrálási elvek alapján készülnek, mivel így a felhasználónak nem kell minden egyes esetben újraértelmezni az adott dokumentum struktúráját. A dokumentáció megértéséhez szükséges a termék, és az ahhoz kapcsolódó (nem feltétlen informatikai) szakterületek ismerete. Ezen területek, valamint a termék maga is rendelkezhetnek speciális terminológiával. Ezek egységessége, a használt kifejezések megfelel helyen történ értelmezése és konzekvens használata nagyban megkönnyíti a leend felhasználók dolgát. Nyelvi helyesség Ide tartozik a fogalmazás tisztasága, és a nyelvtani és a fogalmazásbeli hibák kerülése. Egy-egy ileyn hiba nemcsak kellemetlen, de értelemzavaró, félrevezet is lehet. Az oda nem ill, bonyolult fogalmazás nehezítheti a felhasználó dolgát, különösen, ha nem anyanyelvi szinten beszéli a dokumentum nyelvét. Külalak A technikai dokumentációra még inkább érvényes a kevesebb több elv, mint más dokumentumokra. A formázás feladata a lényeg kiemelése, az értelmezés megkönnyítése. Ha ennek nem tesz eleget, úgy a formázás szükségtelen, és csak rontja a min séget. Az érthet ség szempontjából a stílus területén is fontos az egységesség, mivel azonos formai elemeket könnyen társít az olvasó azonos tartalmi elemekhez, akár dokumentumok közott is. A túlzott sokszín ség, az azonos dolgok különböz formában történ megjelenése nehezíti a megértést. Verziókövetés Nagyon kevés az olyan IT projekt, amely az els verzióval befejez dne. Az egyes dokumentumok elkészülésének folyamatában is érdemes lehet a készül verziókat visszakereshet formában tárolni. Gondoskodni kell ezen kívül az egyes dokumentumok különböz verzióinak a termék verziójával való egyeztetésér l is A munka menete A dokumentáció egy-egy része több lépésen megy keresztül a létrehozástól a befejezésig. Az igény felmerülésekor megkezd dik annak tervezése: milyen dokumentumokból álljon, mi és milyen formában kerüljön beléjük. A terv elkészülte után megkezd dhet a dokumentum megírása. A kész (vagy akár a félkész) dokumentumot egy vagy több alkalmas személy áttekinti, és a talált hibák, hiányosságok listájával, módosítási javaslatokkal megt zdelve visszaküldi a szerz nek, aki elkészíti a dokumentum újabb vezióját, mely ismét lektorálásra kerül. Ez a ciklus optimális esetben mindaddig folytatódik, amíg a lektorok elégedettek nem lesznek a javításokkal. Ekkor a dokumentáció kikerülhet a felhasználóhoz. Egy következ termékverzió megjelenése, vagy egyéb módosítások megkívánhatják a dokumentáció egyes részeinek átdolgozását, akár újratervezését is. 3

5 Ilyen esetben a munka újrakezd dik, majd a lektorálási ciklus végeztével a kész dokumentum egy újabb változatával zárul A folyamat résztvev i A folyamatban a kulcsszerepet a felhasználó játsza, az igényei a legfontosabbak, hiszen számára készül maga a dokumentáció. Felhasználó lehet egy fejleszt, akinek a kés bbiekben a dokumentált modullal kell majd dolgoznia, vagy egy tesztel, akinek a modult tesztelnie kell. De lehet felhasználó a terméket megrendel ügyfél, ill. annak alkalmazottai, partnerei, akik végs soron használni fogják a terméket. A dokumentációban elkészítése a szerz k feladata. Žk lehetnek a modult, terméket fejleszt szakemberek, vagy egy kifejezetten a termék dokumentációjának elkészítésével megbízott, dedikált személy. Žk azok, akik technikai oldalról átlátják a témát. Az egyes dokumentumokat a min ség biztosítására mind tartalmi, mind formai szempontból szükséges lehet ellen rizni, korrigálni azokat. Ezt az ellen rzést a lektor végzi, aki visszaadhatja a dokumentumot megjegyzéseivel a szerz nek, vagy késznek nyilváníthatja azt. A lektor feladata meggy z dni arról, hogy a dokumentum kielégíti a leend felhasználó igényeit. Egy dokumentumot esetenként több szinten is szükséges lektorálni, s t, amennyiben van rá lehet sége, a felhasználó is m ködhet lektorként. A lektorok feladata kimerül a megjegyzéseik hozzáf zésében, k maguk nem szerkesztenek bele a dokumentumokba. Optimális esetben van a projektben egy, a dokumentációs folyamatot koordináló felel s, aki átlátja és ellen rzi a dokumentunok készítését, kiosztja a feladatokat, ajánlásokat tehet a dokumentumok formai és tartalmi paramétereire, a használható szoftverekre, kijelölheti a kívánt terminológiát, valamint ellen riztetheti mindezek betartását A szerz k és lektorok munkája A szerz k számára lehet vé kell tenni, hogy olyan dokumentumokat készítsenek, amelyek a legteljesebb mértékben megfelelnek a leend felhasználók elvárásainak. Személycserék, a termék életciklusában való el rehaladás, vagy a feladatok körének b vülése megkívánhatja más résztvev k akár egyidej bevonását is: az bekapcsolódásuk megkönnyítése, közös munkájuk el segítése érdekében is tehet k lépések. A szerz munkájának megkönnyítésére a legfontosabb, hogy a munkájával (vagyis a készül dokumentummal) szemben támasztott elvárások egyértelm ek legyenek, azok betartása minél egyszer bb legyen, valamint a be nem tartásukból fakadó hibáknak minél nagyobb részét legyen képes saját maga felismerni. A hibák gyors, önálló felfedezhet ségének nagy el nye, hogy kés bb nem köti le a lektor idejét ezek megtalálása, valamint a társszerz ket sem vezeti félre. Ezen kívül annak az esélyét is nagyban csökkenti, hogy a hiba végleg bentmaradjon a dokumentumban. Fontos kritérium még a szerz munkája szempontjából, hogy a társzerz kkel és a lektorokkal való kommunikáció minél egyszer bb, átláthatóbb és pontosabb legyen. Ehhez fontos, hogy mind a lektorok, mind a szerz k a dokumentumok teljes fejl dési folyamatát átláthassák, vagyis hozzáférhessenek azok tetsz leges korábbi verzióihoz, és az azóta történt módosításokat elemezni tudják. 4

6 1.4. Problémák a dokumentációval kapcsolatban Problémák több területen merülnek fel mindezen célok megvalósításában. A személyi és gazdaságossági kérdések elemzése nem része ezen éretkezésnek, itt csak a technikai jelleg gondokat, és az ezekre adható megoldásokat tárgyaljuk. Egy tipikus IT projektben a dokumentációt író szerz k, és a lektorok is informatikai-, vagy az adott termékhez kapcsolódó más területek szakemberei szaktudásuknak a dokumentum-szerkesztés, szedés, tördelés mélyebb ismerete nem képezi részét. S t, általában ezen feladatok sem tartoznak épp a legkedveltebb foglalatosságaik közé, ezért szeretnék ket minél kevesebb gonddal letudni. Ennek a munkának a legnagyobb hányadát a dokumentum megírása ill. átszerkesztése jelenti. A feladathoz választott metodika és szoftver ezért kulcsfontosságú. Jelen fejezetben három elterjedt hozzáállást, platformot vizsgálunk, azok használhatósága és a használatukból következ egyéb vonatkozások tekintetében. Mindegyik platformnak megvannak az er sségei és a gyengéi. Microsoft Word A PC-s szövegszerkesztés els dleges platformja. Manapság már iskolákban tanítják, de enélkül is találkozott már vele a számítógépes szövegszerkesztéssel próbálkozók túlnyomó többsége. Interaktív felhasználói felülete folyamatosan látni engedi a dokumentum végleges formátumát (WYSIWYG 1 megjelenítés), ezzel megkönnyítve a szerkesztést. A program úgy van kitalálva, hogy minimális tudással is bele lehessen kezdeni a használatába. A program nagy hátránya, hogy formázási lehet ségek százaival igyekszik kényeztetni a felhasználót, aki gyakran él is ezekkel. Az eredmény gyakran kiábrándító, vagy jobb esetben is inkonzisztens. A rengeteg formátumozási paraméternek nem létezik normális küllemet garantáló alapértelmezett értéke, a felhasználó ösztönözve van a kísérletezésre. Azonban megfelel tudás nélkül legtöbbször csak lokálisan állítják ezeket a paramétereket, olykor megfeledkezve a következetességr l. Ennek eredménye általában egy össze-vissza, jó esetben is az adott szerz re jellemz formátumú dokumentum. Erre a problémára igyekszik megoldást nyújtani a sablonok használata, melyek sablontól függ en különböz formátumokat el re beállítanak, mintegy ajánlást téve ezen paraméterek értékeire. Ilyen formátumok pl. a bekezdés, a fejezet és az oldal paraméterei, bet méretek és távolságok. Azonban ezeket az ajánlásokat a program nem kényszeríti ki, a felhasználó nyom nélkül megváltoztathatja ket (f ként lokálisan) egy-egy egérkattintással, ezáltal összeborítva a felépített rendet. A Word, ill. a WYSIWYG szerkesztési mód lehet vé teszi, hogy a képeket, egyéb, a dokumentumba illeszthet részeket is átlássa a szerz már a szerkesztés idején. A Word rendelkezik OLE 2 szerkesztési lehet ségekkel, mellyel egyes beágyazott objektum-típusok helyben, a Word ablakban szerkeszthet k. A Word csak Windows és Macintosh rendszereken elérhet, bár képes menteni más fájlformátumokba, melyek megnyithatók egyéb eszközökkel is. 1 What You See Is What You Get 2 Object Linking and Embedding 5

7 Word OOo TEX WYSIWYG szerkesztés + + Helyesírás-ellen rzés + + Automatikus elválasztás Megbízható nagyobb méret feladatok + esetében is Elérhet a fontosabb platformokon + + Merge-ölhet fájlformátum(cvs/svn) + Egyéb eszközökkel kereshet fájlformátum(cvs/svn) + Csoportmunka támogatása eszközökkel táblázat. A három megoldás összehasonlítása OpenOce.org Writer A Micosoft Word elvei szerint m köd, azt minél pontosabban másolni kívánó, valamint néhány számunkra nem túlzottan lényeges b vítést, valamint jópár extra bugot tartalmazó program. Ezekt l eltekintve felhasználás szempontjából ekvivalensnek tekinthet a Worddel. El nye, hogy használata ingyenes, forráskódja pedig szabadon elérhet, valamint a leggyakoribb platformokon 3 elérhet. TEX/LATEX A LATEX (ill. a TEX) önmagában nem rendelkezik grakus interfésszel. Egy plain-text fájl formájában várja a dokumentum tartalmi részét, mely alig tartalmaz formátumozást. A végs külalakot stíluslapok és a tartalmi részben található szerkezeti utasítások alapján végzi, nagyjából egy programkód fordításához hasonlóan. A LATEXdokumentumban is van lehet ség lokális formázásra, de jóval szolidabb keretek között és jóval bonyolultabb módon, mint a Word/OOo esetében. A LATEXdokumentumok szerkesztéséhez tehát szükség van valamilyen különálló szerkeszt alkalmazásra. A leggyakoribb módszer a forrásfájl kézzel történ szerkesztése, bár léteznek WYSIWYG front-endek 4, mint pl. a LyX. Utóbbiakkal a Word/OOo-hoz hasonlóan szerkeszthet ek dokumentumok, némileg korlátozott lehet ségekkel. A kézzel való szerkesztés megkívánja a LATEXnyelv mélyreható ismeretét, a WYSIWYG szerkeszt kbe pedig id beletanulni a Word/OOo-hoz szokott felhasználónak. Az egyes platformok lehet ségeir l áttekintését az 1.1 táblázat ad Részletek Tekintsük át részletesebben is az immáron kett re sz kült megoldásokat az egyes részproblémák tükrében. Verziózás A verziózás kérdése akkor is fontos, ha a dokumentumon csak egy szerz dolgozik. Ekkor is lényeges, hogy a dokumentum korábbi vezióit bármikor el lehessen 3 UNIX, Mac OS X, Windows 4 adott fapados szoftverhez szosztikáltabb környezetet nyújtó keretek 6

8 keresni. Még nagyobb hangsúlyt kap azonban a kérdés, ha több ember munkáját kell összehangolni. A verziózás feladatát több különböz megoldással is le lehet fedni (pl., általában egy cégnél egy ilyen megoldást használnak. Elterjedt technológiák a Subversion, a CVS 5 és a Microsoft-féle SourceSafe. Ezen rendszerek mind valamilyen formán az egyes verziók közötti különbségek képzésére alapoznak. A legtöbb verziókövet szoftver képes ugyanazon elem több különböz felhasználó által történt módosítását is lekövetni, ha pontosan megállapítható, milyen változtatások történtek az elemen belül. Ehhez elégséges feltétel pl., hogy az adott elem plain-text formátumú legyen. A Word/OOo esetében ez a dokumentumok XML formátumba való mentésével biztosítható. A TEXalapú szoftverek natív formátuma pedig eleve plain-text formátumú. Nagy dokumentumok Egyes dokumentációk több kisebb részb l, több ember különálló munkájából tev dnek össze. Ezek szerkezete felépíthet hierarchikusan, f - és aldokumentumok formájában. Erre mindkét platform kínál lehet ségeket. Ellen rzés Összefoglalás 5 Concurrent Versions System 7

9 2. fejezet Lehet ségek Az el z fejezetben ismertetett platformok, metodikák általános célra készültek, egy adott, nagy felhasználócsoport szerteágazó igényeinek kielégítésére. Az általuk felvonultatott funkciók hadából minden konkrét felhasználó csak egy kis hányadot használ ki, a többi számára tulajdonképpen útban van. Mivel a minél nagyobb felhasználói tábor minél egyszer bb lefedése a cél, ezért bizonyos, sz - kebb körök számára szükséges funkciók kisebb hangsúlyt kaptak, nehézkesebben elérhet ek, vagy egyáltalán nem képezik részét egyik vagy másik platformnak. Ezen okokból merült fel a Chyavanprash megalkotásának ötlete Támogatandó elvárások A cél tehát nem valamely meglev platform kiegészítése, hanem egy új rendszer elkészítése, amely a meglev knél jobban támogtja a specikusan technikai dokumentációk el állításával kapcsolatos feladatokat. Ehhez sok mindennek kell teljesülnie, hiszen a felhasználók nem fognak egy nehézkes, hiányos rendszerre átállni. Megfelel mennyiség plusz funkciót, több kényelmet is kell nyújtania a rendszernek a munkavégzés közben, hogy megérje a többi alternatíva helyett t használni. A tervezett rendszernek tehát könnyen használhatónak kell lennie. Fontos, hogy küls eszközökkel jól managelhet legyen, tehát nem szabad beszorítani a felhasználót a rendszer keretei közé, meglév eszközeit is tudnia kell továbbra is használni. Célkit zéseink között szerepel, hogy igényes eredményt szolgáltasson az egyszer kezelhet ség megtartása mellett. Segítenie kell a dokumentummal kapcsolatos munkák elvégzését a tejes életcikluson keresztül, amelyben a nyersanyag végig jól menedzselhet kell maradjon Felhasználóbarát felület Fontos, hogy a leend felhasználók minél könnyebben beletanulhassanak a rendszerbe, és hogy a használat közben is minden a kezük alá essen. Feltételezhet, hogy a leend felhasználók nagyrésze a Wordhöz és barátaihoz szokott, így érdemes onnan átvenni a szövegszerkesztésben használt funkciókból mindent, amit lehet. A felhasználói felületnek szépnek kell lennie. Egyrészt a munka örömét is 8

10 nagyban rontja, ha csúnya környezetben kell dolgozni, másrészt a készül munka igényességével kapcsolatos igényt is tudja növelni a felhasználóban egy igényes kivitelezés GUI Formázás különválasztása Amint azt már a bevezetésben leírtuk, a dokumentumok kinézetét meghatározó stíluslapot külön kell választani az egyes dokumentumok tartalmi részét l Kapcsolódó feladatok A dokumentum életciklusa során sok egyéb feladatot is meg kell oldani a tartalom megszerkesztésén kívül. Ide tartozik a lektorálás segítése stb. Lektorálás A lektor számára láthatóvá kell tenni a dokumentum jelenlegi, és igény tetsz leges megel z állapotát, valamint a kett közötti változásokat, hogy követni tudja a dokumentum fejl dését. Lehet séget kell biztosítani számára, hogy olyan megjegyzésekkel lássa el a dokumentumot, amelyek segítik a szerz t, hogy kijavíthassa a megtalált problémákat. Egyik-másik megjegyzés megválaszolást, visszakérdezést igényelhet a szerz részér l, majd ismételt választ stb. Ezeket a beszélgetéseket érdemes követni, a dokumentum részeként kezelni mindaddig, amíg azok hasznos információt tartalmaznak Metaadatok A dokumentum adatai A dokumentumnak tartalmaznia kell a készít nevét, a létrehozás és az utolsó változtatás dátumát stb. Ezen adatokat lekérdezhet vé, felhasználhatóvá kell tenni. A metaadatok köre kiterjeszthet kell legyen az alap rendszer részét képez ek körén túl is. Szükség van automatikusan generált metaadatokra, mint pl. az utolsó módosítás, vagy a verziókövet rendszerben lev verzószám lekérdezésére. Metaadatok a muka megkönnyítésére A lektorálás során a lektor. Ezek a megjegyzések természetesen nem kerülnek bele a végleges formátumra hozott, pl. PDF dokumentumba. Fontos azonban, hogy ezeket a megjegyzéseket a dokumentummal együtt kezeljük, azok ne vesszenek el a különböz módosítások során. A megjegyzéseken belül kölönböz típusokat lehet megkülönböztetni, úgy mint egyszer megjegyzés, hibával kapcsolatos gyelmeztetés, hiányosság stb. Szintén fontos, hogy az elvégzend feladatokat követni lehessen. Ilyenek pl. a még dokumentálandó részeknek való helyek kihagyása, a menet közben beérkez kérések (Ezt meg ezt légyszi, írd majd még bele), ötletek vezetése. Eéle TODO elemeket a szerz felvehet a maga emlékeztetésére is, de a lektor, vagy a dokuemtum tervez je is elhelyezheti azokat. Ezen elemek igény szerint megjeleníthet ek kell legyenek lista-szer en is, akár egy projekthez tartozó összes dokumentumra nézve. 9

11 Sokszor jó volna látni, hogy a dokumentum mely része tekinthet véglegesnek, és melyik az, ami még készül, formálódik. E célból a dokumentum egyes részeit érdemes lenne megjelölni (akár pl. háttérszínnel, vagy a margón lev jelzéssel). Ilyen státusok lehetnek a Vázlat, Nyers, Átdolgozandó, Kész' stb Ellen rzés Szerkesztés közbeni helyesírás-ellen rzés Ma már a legtöbb szövegszerkeszt ben támogatott funkció a szöveg beírásakori helyesírás-ellen rzés. Ez nélkülözhetetlennek t nik a Chyavanprash esetében is. Az egyes ellen rz implementációk er sen eltérnek egymástól hibafelismer képességük (mind a fals-pozitív, mind a fals-negatív esetek) tekintetében, de m - ködési elvük szinte azonos: valamilyen algoritmus és egy azt kiegészít adatbázis szerint felismerik a szöveg hibáit, ezeket képesek jelezni, a fals-pozitív hibajelzések megkerülésére pedig valamilyen szótár-le-t használnak. Emiatt érdemes volna a Chyavanprash-on belül a helyesírás-ellen rzést plug-in rendszerben megoldani, így lehet vé téve, hogy a felhasználók a számukra legszimpatikusabb ellen rz t használhassák. Lehet séget kell biztosítani a dokumentumon belül, és azon kívül is, valamilyen közös szótárban a megengedett kivételek tárolására. Emellett meg kell tudni adni a dokumentumon belül, hogy mely területek milyen nyelv alapján ellen rizend ek. Automatikus ellen rzés Nagyobb szoftverek fejlesztésénél megszokott, hogy a készül ben lev alkalmazást, vagy annak kisebb-nagyobb részeit több szempont alapján is teszelik. Ezek között fontos szerepet kap az automatikus tesztelés; a JUnit/NUnit rendszerek a Java-s,.NET-es fejleszt k életét teszik könnyebbé évek óta. Léteznek olyan rendszerek is, melyek a szoftver forráskodú változatából lépések során át képesek legenerálni a végleges változatot. Ilyen rendszer pl. az Apache Maven, mely az egyes lépések közben felmerült problémákról képes riportokat készíteni, és azokat a felel söknek eljuttatni ben. Régóta alkalmazott megoldás az automatikus tesztek integrálása az ilyen fajta build process-ekbe. Az olyan Continuous Integration eszközök, mint pl. a Continuum képesek mindezeknek a teszetléseknek a háttérben történ rendszeres futtatásáról is gondoskodni. A dokumentáció elkészítése során el forduló problémákat nem nehéz párhuzamba állítani a forráskódban el forduló gondokkal. A helyesírási hibák tekinthet k szintaktikai hibáknak, több le-ra kiterjed dokumentumok esetében el forduló hibás linkek 1 a hibásan hivatkozott osztályok referenciáira hajaznak stb. Ezeket a problémákat a forráskód fordításához, teszteléséhez hasonlóan lehet ellen rizni, a projekthez tartozó deliverable-ök build process-ének részévé lehet tenni. Ezzel együtt a dokumentáció automatikus ellen rzése integrálható a Continuous Integration eszközökbe is. Ugyancsak lehet automatikus teszteket készíteni a dokuemntumok állapotának felmérésére is. Hiba lehet pl. egy Kész-nek nyilvánított szövegrészben 1 kapcsolódó dokumentumok, képek stb. 10

12 szerepl, hibajavításra felszólító megjegyzés, de kereshetünk ellentmondásokat magasabb szinteken is, pl. egy Kész dokuemntum félkész elemeket tartalmazó aldokumentumaira keresve. Mindezek akár a Continuous Integration, akár a kézzel indított build folyamat során generálódó riportokba kerülhetnek, melyek tájékoztatják a megfelel személyt a dokumentáció állapotáról Integrálhatóság Sok minden van, amit már megcsinált valaki, sokkal jobban akár, mint ahogy arra a Chyavanprash fejlesztése közben lehet ség lenne. Az ilyen meglev rendszerekkel biztosítani kell a kompatibilitást, integrálhatóságot. Ilyen eszközök pl. a verziókövet rendszerek, helyesírás-ellen rz k stb. Ezért célul t zzük ki, hogy az elkészül rendszer minden szempontból moduláris legyen B víthet ség Kész rendszer nincs. A Word és barátai tanulságából okulva kijelenthetjük, hogy minden igényt kielégít rendszer sem létezik. Ezért biztosítani kell, hogy a szoftverhez könny legyen hozzáfejleszteni Nem támogatott funkciók A Chyavanprash rendszernek nem célja, hogy mindent magába foglaljon. S t: amit csak lehet, igyekszik már meglév, open-source megoldásokkal kiváltani; lehet leg úgy, hogy az adott funkciót ellátó többféle termék közül választani lehessen. Ilyen pl. a verziókezelés, amelyet a Subversionre, vagy a CVS-re bízunk. 11

13 3. fejezet Felépítés 3.1. Felhasználandó technológiák A Chyevanprash rendszer megalkotásához számos, már meglév technológiát kívánunk felhasználni. Az alábbiakban az egyes technilógiák, és a mellettük szóló érvek olvashatók. A használandó technológiák egymásra-épülését a 3.1. ábra mutatja be. Java Platform, Standard Edition 5.0 A rendszert Java alapokon szeretnénk kivitelezni, mivel a platform az utóbbi években bebizonyította, hogy rendkívül jól használható, korszer és b víthet objektum-orientált megoldások készíthet ek vele. Mára igen kinomult fejleszt eszközök érhet k el hozzá, az elkészült alkalmazások pedig a számunkra lényeges platformokon külön ráfordítás, fejlesztés nélkül tudnak m ködni. Ezen kívül rengeteg szabadon felhasználható eszköz áll rendelkezésre opensource keretek között. Equinox Framework 3.2 Mivel rendszerünket a legmesszemen bbekig b víthet re tervezzük, igyekszünk felhasználni azokat a technológiákat, melyek ezt támogatni tudják. Az Equinox Framework 1 egy OSGi 2 Core Framework R4-kompatibilis keretrendszer, ami rengeteg olyan funkciót támogat, melyek szükségesek egy dinamikusan b víthet, managelhet alkalmazás összeállításához: Szolgáltatás-alapú m ködés Dinamikusan beépül, lecserélhet, frissíthet szolgáltatások Eclipse Rich Client Platform 3.2 Az Eclipse fejleszt rendszer alapját is képez, Equinox-alapú Eclipse RCP 3 lehet vé teszi, hogy könnyedén felépítsük rendszerünk grakus intefészeit. Erre leginkább a szövegszerkeszt modulnál lesz szükség. Az Eclipse RCP azonban SWT 4 -t használ, ami 1 Equinox Framework, 2 Open Services Gateway initiative, 3 Eclipse Rich Client Platform, _Platform 4 Standard Widgeting Toolkit 12

14 3.1. ábra. A Chyavanprash architektúrája épp a szövegszerkeszt komponens kivitelezését neheízti meg, mivel az jóval szosztikáltabb grakai megoldásokat igényel, mint amire az SWT önmagában képes. Ezért a szövegszerkeszt komponens Swing 5 alapon fog elkészülni. Apache Maven 2 Az Apache Software Foundation által fejlesztett Maven 6 projektkezel eszköz els sorban a fejlesztés alatt álló szoftverek életciklusának kezelését hivatott könnyíteni. Ide tartozik a fordítás, tesztelés, különböz szoftver- és dokumentáció-csomagok elkészítése. Ezen kívül azonban a Maven egy jól b víthet, plugin-alapú keretrendszer is, mellyel az általa kezelt folyamatokba könnyedén illeszthet k új lépések. A Mavent két területen is szándékozunk felhasználni a rendszerben. Egyrészt az igencsak szerteágazó komponensek fordítási, összeállítási feladatait, az automatikus dokumentáció generálásának, a kód tesztelésének feladatait hárítanánk rá. Másrészt viszont szeretnénk készíteni néhány, a Maven folyamataiba integrálható plug-int, melyekkel a Chyavanprash forrásdokumentumok a Maven build process részeként nyerhetnék el végs formájukat. Mi több, a forráskód teszteléséhez hasonlóan szeretnénk készíteni egy plug-int, ami képes lenne a Chyevanprash forrásdokumentumok ellen rzésére helyesírási, és mindenféle más szempont alapján. MikTeX 2.5 A LATEX 2 ε -t támogató MikTeX szoftvercsomag képezi a TEX fordítás bázisát Windows platformon. 5 Swing, 6 Apache Maven 2, 13

15 3.2. ábra. A Chyavanprash munkamenete TEX Live UNIX-alapú rendszereken a TEX Live szoftvercsalád fogja ellátni a LATEX 2 ε fordítást Apache Xalan Az Apache Xalan egy open-source XSLT transzformátor, mely a Java-alapú szoftvereknél az utóbbi években iparági szabvánnyá n tte ki magát Munkamenet A valamilyen verziókezel rendszerben tárolt forrásdokumentum(ok), valamint a sablon alapján akár a GUI-ban, akár a Maven plug-inekkel elindítható a dokumentum ellen rzése és/vagy a végleges formátum el állítása. A Chyavanprashon belüli munkamenetet a 3.2. ábra mutatja. 14

16 3.3. Megvalósítás Bár a megvalósítandó rendszer egy egyszer en használható eszköz kell legyen, a feladat sokrét sége miatt igen sok komponens elkészítését igényli. Ezért a teljes kivitelezés semmiképp nem fér bele jelen önálló labor kereteibe, s így kénytelenek vagyunk a munkát kisebb részekre osztani Els fázis: Tervezés A legels fázisban elkészülnek a Chyavanprash rendszer részletes tervei, melyek a következ dokumentumokból állnak: A rendszerrel szembeni igények pontosítás leírása (funkcionális specikáció, UML diagramok stb.) A támogatandó stílus- és struktúra-elemek listája A forrás-állomány XML formátuma (UML diagram és XSD formájában) A sablon-állományok formátuma A támogatandó ellen rz k interface-e (UML diagram) A támogatandó kimenetekhez szükséges builderek interface-e (UML diagram) A szükséges Maven-pluginek listája azok funkcióival Második fázis: Prototípus Ebben a fázisban el fog készülni a rendszer egy egyszer sített, Proof of Concept jelleg változata, mely egyel re nem integrálódik a céleszközökkel, csak parancssorból indítható. Ez a prototípus képes lesz egy az alap formázásokat tartalmazó forrásdokumentumot néhány szempont szerint leellen rizni, majd a TEX meghívásával el állítani bel le a céldokumentumot Harmadik fázis: Integráció Ebben a fázisban a kész prototípust beillesztjük a Maven és az Eclipse RCP rendszerek alá, hogy funkciói onnan is elérhet ek legyenek. A fázisban elkészülnek a Maven plugin-ek, melyek az oine ellen rzést és buildelést szolgálják, valamint egy egyszer sített megjelenítést biztosító plain text editor Eclipse alá. Ezzel a funkcionalitással a rendszer akár már felhasználói teszteknek is kitehet Negyedik fázis: Befejezés Ennek a fázisnak a célja az elvarratlan szálak eldolgozása, valamint az Eclipse RCP GUI végleges változatának kifejlesztése, immáron a közelít leg WYSIWYG szerkeszt - és lektorálófelülettel. 15