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



Hasonló dokumentumok
Programozás alapjai Bevezetés

Alkalmazások fejlesztése A D O K U M E N T Á C I Ó F E L É P Í T É S E

Bánsághi Anna Bánsághi Anna 1 of 54

Közösség, projektek, IDE

oda egy nagy adatbázisba: az eszközök nincsenek egy koncentrált helyre begyűjtve, azaz minden egyes eszközt külön-külön kell megszerezni egy

30 MB INFORMATIKAI PROJEKTELLENŐR

Ingrid Signo Felhasználói kézikönyv. Pénztári használatra

Időkönyvelő Projektfeladat specifikáció

Verifikáció és validáció Általános bevezető

Aronic Főkönyv kettős könyvviteli programrendszer

Viczián István IP Systems JUM XIX szeptember 18.

Enterprise extended Output Management. exom - Greendoc Systems Kft. 1

OpenCL alapú eszközök verifikációja és validációja a gyakorlatban

Terület- és településrendezési ismeretek

Az őrültek helye a 21. századi magyar társadalomban

Mérés és értékelés a tanodában egy lehetséges megközelítés

A szoftver-folyamat. Szoftver életciklus modellek. Szoftver-technológia I. Irodalom

Pénzkezelési szabályzat szerkesztő

INFORMATIKA Helyi tantárgyi tanterv

INFORMATIKA Emelt szint

13. Fájlformátumok. Schulcz Róbert Madarassy László 13. Fájlformátumok v

I: Az értékteremtés lehetőségei a vállalaton belüli megközelítésben és piaci szempontokból

Kedvenc Linkek a témakörben: MySQL mindenkinek Vizuális adatbázis tervezés

A szoftverfejlesztés eszközei

Szoftver újrafelhasználás

A Java EE 5 plattform

BEFOGADÓI TÁJÉKOZTATÓ V 1.0. Tájékoztató anyag az elektronikus számlabefogadó oldal számára

Access 2010 Űrlapok és adatelérés

A tudás alapú társadalom iskolája

iphone és Android két jó barát...

P-GRADE fejlesztőkörnyezet és Jini alapú GRID integrálása PVM programok végrehajtásához. Rendszerterv. Sipos Gergely

Pénztárgép Projektfeladat specifikáció

OpenOffice Pilot projekt az NFGM-ben

Szociális és gyermekvédelmi szabályozók NGYE-NSZ. (szolgáltatási standardok) VITAANYAG. Készítette: Dr. Magyar Gyöngyvér Vida Zsuzsanna

Gondolatok a konvergencia programról. (Dr. Kovács Árpád, az Állami Számvevıszék elnöke)

Nyílt forráskódú irodai programkomponensek vállalati környezetbe való integrációjának vizsgálata és implementációja

Bemutató anyag. Flash dinamikus weboldal adminisztrációs felület. Flash-Com Számítástechnikai Kft Minden jog fenntartva!

AZ ENERGIAUNIÓRA VONATKOZÓ CSOMAG A BIZOTTSÁG KÖZLEMÉNYE AZ EURÓPAI PARLAMENTNEK ÉS A TANÁCSNAK

01. gyakorlat - Projektalapítás

Autó szerviz, csere pedelec

11/1985. (XI. 30.) IpM rendelet. a közvilágításról

Microsoft Office 2010

Felhasználóbarát kliensszoftver

Programrendszerek tanúsítása szoftverminőség mérése

ZÁRÓ TANULMÁNY a "FoglalkoztaTárs társ a foglalkoztatásban" kiemelt projekt (TÁMOP / ) keretében

A Clipper evolúciója

Word 2010 magyar nyelvű változat

Informatika. Célok és feladatok. Helyi tantervünket az OM által kiadott átdolgozott kerettanterv alapján készítettük.

ALKALMAZÁS KERETRENDSZER

AllBestBid. Felhasználói kézikönyv az AllBestBid online aukciós szolgáltatás használatához március DFL Systems Kft.

Szoftver-technológia II. Architektúrák dokumentálása UML-lel. Irodalom. Szoftver-technológia II.

A NetBeans IDE Ubuntu Linux operációs rendszeren

IV. Szakmai szolgáltatások funkcionális tervezése

WebService tesztelés. SOAPui Pro, GreenPepper és Confluence használatával. Verhás & Verhás Szoftver Manufaktúra KNOW-HOW

Okos gyógyszeres doboz Projektfeladat specifikáció

AZ EURÓPAI KÖZÖSSÉGEK BIZOTTSÁGA. Javaslat AZ EURÓPAI PARLAMENT ÉS A TANÁCS HATÁROZATA

A NEVELÉSI-OKTATÁSI INTÉZMÉNYEK PEDAGÓGIAI PROGRAMJÁRA VONATKOZÓ JOGSZABÁLYI ELŐÍRÁSOK

OBJEKTUMORIENTÁLT TERVEZÉS ESETTANULMÁNYOK. 2.1 A feladat

Az egyetemi publikációs adatbázis

ÁLTALÁNOS SZERZŐDÉSI FELTÉTELEK az IZINTA Kft. vásárlói részére

Segédlet a lakásszövetkezetek tisztségviselőinek megválasztásához

feladatok meghatározása során elsősorban az eszközök ismeretére, az eszközökkel megvalósítható lehetőségek feltérképezésére és az alkotó

Intelligens partner rendszer virtuális kórházi osztály megvalósításához

Az információs társadalom lehetőségeivel csak azok a személyek tudnak megfelelő módon élni, akik tudatosan alkalmazzák az informatikai eszközöket,

AZ EURÓPAI UNIÓ TANÁCSA. Brüsszel, november 22. (OR. en) 15074/04 CORDROGUE 77 SAN 187 ENFOPOL 178 RELEX 564

Tervezett erdőgazdálkodási tevékenységek bejelentése

Szoftver-technológia II. Szoftver újrafelhasználás. (Software reuse) Irodalom

Aronic Bér Bérszámfejtés és munkaügyi nyilvántartás program

Programtervezés. Dr. Iványi Péter

Az EDIMART Tolmács-és Fordításszolgáltató általános szerződési feltételei (a továbbiakban: ÁSZF)

AZ EURÓPAI UNIÓ KÖVETELMÉNYRENDSZERÉNEK MEGFELELŐ ELEKTRONIKUS TANANYAGOK ELŐÁLLÍTÁSÁNAK LEHETŐSÉGEI, MÓDSZEREI

Az ellenőrzés módszertana

Értékelés a BUS programhoz elkészült termékek magyar változatáról Készítette: Animatus Kft. Jókay Tamás január 07.

Technikai információk fejlesztőknek

Felhívás észrevételek benyújtására az állami támogatások kérdéskörében a Bizottság általános csoportmentességi rendelettervezetére vonatkozóan

PÁLYÁZATI FELHÍVÁS és ÚTMUTATÓ

NYUGAT-MAGYARORSZÁGI EGYETEM PÁLYÁZATI SZABÁLYZAT

Tex and Co Kft Budapest, Francia út 54. ÁLTALÁNOS SZERZŐDÉSI FELTÉTELEK (egységes szerkezetbe foglalt) I. Általános rendelkezések

Modellek dokumentálása

Tartalomjegyzék. 5. A közbeszerzési eljárás főbb eljárási cselekményei. 6. Eljárási időkedvezmények a közbeszerzési törvényben

A középszintű szóbeli vizsga értékelési útmutatója. Orosz nyelv. Általános útmutató

Ficsor Lajos Általános Informatikai Tanszék Miskolci Egyetem

E-ÉPÍTÉSI NAPLÓ KÉZIKÖNYV

Flex tutorial. Dévai Gergely

Önértékelési kézikönyv KOLLÉGIUMOK SZÁMÁRA

Szervezési, irányítási és ellenőrzési modell

AZ ÉPÍTÉSI MUNKÁK IDŐTERVEZÉSE

A teljesítményértékelés és minősítés a közigazgatási szervek vezetésében

2015/32. SZÁM TARTALOM. 36/2015. (VIII. 27. MÁV-START Ért. 32.) sz. vezérigazgatói utasítás a MÁV-START Zrt. Tűzvédelmi Szabályzatáról...

Gyarmati Dezső Sport Általános Iskola. Informatika HELYI TANTERV 6-8. ÉVFOLYAM. KÉSZÍTETTE: Oroszné Farkas Judit Dudásné Simon Edit

A DIÁKHITEL Rt. szoftver és hozzá kapcsolódó oktatás beszerzése Az ajánlatkérő neve, címe, távirati címe, telefon és telefax számai:

Minőségbiztosítási Kézikönyv

Az ErdaGIS térinformatikai keretrendszer

Diplomamunkák, szakdolgozatok és Önálló labor dokumentációk formai és tartalmi követelményei

Tartalom. Konfiguráció menedzsment bevezetési tapasztalatok. Bevezetés. Tipikus konfigurációs adatbázis kialakítási projekt. Adatbázis szerkezet

Petőfi Irodalmi Múzeum. megújuló rendszere technológiaváltás

Versenykiírás, Szervezeti Leírás

Informatikai projektellenőr szerepe/feladatai Informatika / Az informatika térhódítása Függőség az információtól / informatikától Információs

Nagy bonyolultságú rendszerek fejlesztőeszközei

Átírás:

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) 2007. április 26.

Tartalomjegyzék 1. Bevezetés 2 1.1. IT projektek dokumentálása..................... 2 1.2. A dokumentációval szembeni elvárások............... 2 1.3. A munka menete........................... 3 1.3.1. A folyamat résztvev i.................... 4 1.3.2. A szerz k és lektorok munkája............... 4 1.4. Problémák a dokumentációval kapcsolatban............ 5 1.4.1. Részletek........................... 6 1.4.2. Összefoglalás......................... 7 2. Lehet ségek 8 2.1. Támogatandó elvárások....................... 8 2.1.1. Felhasználóbarát felület................... 8 2.1.2. Formázás különválasztása.................. 9 2.1.3. Kapcsolódó feladatok.................... 9 2.1.4. Metaadatok.......................... 9 2.1.5. Ellen rzés........................... 10 2.1.6. Integrálhatóság........................ 11 2.1.7. B víthet ség......................... 11 2.1.8. Nem támogatott funkciók.................. 11 3. Felépítés 12 3.1. Felhasználandó technológiák..................... 12 3.2. Munkamenet............................. 14 3.3. Megvalósítás............................. 15 3.3.1. Els fázis: Tervezés...................... 15 3.3.2. Második fázis: Prototípus.................. 15 3.3.3. Harmadik fázis: Integráció.................. 15 3.3.4. Negyedik fázis: Befejezés.................. 15 1

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. 1.2. 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

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. 1.3. 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

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. 1.3.1. 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. 1.3.2. 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

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

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 + 1.1. 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. 1.4.1. 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

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 1.4.2. Összefoglalás 5 Concurrent Versions System 7

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. 2.1. 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. 2.1.1. 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

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. 2.1.2. 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. 2.1.3. 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. 2.1.4. 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

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. 2.1.5. 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 emailben. 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

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. 2.1.6. 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. 2.1.7. 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. 2.1.8. 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

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, http://www.eclipse.org/equinox/framework/ 2 Open Services Gateway initiative, http://www.osgi.org/ 3 Eclipse Rich Client Platform, http://wiki.eclipse.org/index.php/rich\_client\ _Platform 4 Standard Widgeting Toolkit http://www.eclipse.org/swt/ 12

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, http://java.sun.com/jfc/ 6 Apache Maven 2, http://maven.apache.org/ 13

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 2.7.0 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. 3.2. 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

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. 3.3.1. 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 3.3.2. 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. 3.3.3. 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. 3.3.4. 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