Lazarus Documentation Editor/sk

│ Deutsch (de) │ English (en) │ español (es) │ français (fr) │ 日本語 (ja) │ polski (pl) │ русский (ru) │ slovenčina (sk) │

Úvod

Dôležitou časťou Lazarus, ktorá stále chýba je dokumentácia. Na pomoc s vytváraním tejto dokumentácie bol vyvinutý nástroj. Táto stránka popisuje prácu s ním. Pre označenie základného adresára v tomto dokumente je použité [$LazDir], takže pri čítaní si to nahraďte adresárom, v ktorom je Lazarus nainštalovaný.

Prečo

Prvou výhodou tohoto projektu je sprístupniť súbory online nápovedy. Aby bola nápoveda platformovo nezávislá začali sme s tvorbou XML súborov pre každú jednodtku použitú v Lazarus. Zatiaľ bolo začaté len s dialogs.pp a buttons.pp.

Tieto XML súbory budú potom použité pre vytvorenie HTML stránok, ktorú budú prístupné cez Internet na stránke dokumentácie. Nakoniec bude vytvorená integrovaná nápoveda, znova pomocou týchto XML súborov.

Začiatok

Ako už bolo spomenuté, pre zachovanie platformovej nezávislosti je použité XML. Aktuálnu dokumentáciu nájdete v [$LazDir]/docs/xml/. Zatiaľ tam sú, v adresári lcl, väčšinou len kostrové súbory. XML súbory, ktoré sú v tomto adresári boli automaticky vytvorené a pre použitie ich treba prispôsobiť.

Takže teraz, keď už viete kde máte hľadať súbory, poďme sa pozrieť na nástroj pre ich vytvorenie/úpravu.

Nástroj

"lazde" je nástroj pre úpravu xml súborov, ale možno ho použiť aj na generovanie základných súborov zo zdrojových kódov a, pomocou externého nástroja, aj na generovanie HTML verzie dokumentácie. Príklad výsledku posledného nástroja môžete vidieť na tejto stránke, ako časť dokumentácie. Keďže nie je poskytovaná kompilovaná verzia lazde, musíte si ju urobiť sami.

Zdrojové kódy "lazde" sú v [$LazDir]/doceditor/. Keď tento program spustíte a otvoríte [$LazDir]/docs/xml/lcl/dialogs.xml stretnete sa touto obrazovkou

Práca

Otvorenie uzla "Packages" zobrazí uzol "LCL", ktorý obsahuje uzol "Dialogs". Zvolením posledne menovaného uzla zaplní dolný treeview prvkami. Tieto prvky predstavujú Konštanty (Constants), Typy (Types) a triedy (Classes) definované v unite Dialogs.pp. Použité unity sú pridané rovnako ako uzly. Ďalšie uzly sú pridané pre vlastnosti (properies) tried, parametre funkcií a tak ďalej.

Zvolením uzla v ľavom dolnom treeview vytvorí obsah daného uzla v pravej časti okna.

Keď navštívite túto stránku, uvidíte prehľad tried definovaných v unite "dialogs". Za každou triedou uvidíte riadok textu. Tento text pochádza z "short" editbox z lazde.

Pod "short" editbox, je memofield, do ktorého môžete zadať viac vypracovaný popis komponentu alebo vlastnosti.

Poznámka: Ak chcete vložiť koniec ridku použite <br/>

Nasledujú Chyby (Errors), Pozrieť aj (See also) a Príklad kódu (Example code File).

"Errors" môžu byť použité pre popis chýb vyvolaných funkciou, ak parametre majú hodnoty, ktoré sú mimo rozsah. Pre príklad pozrite túto stránku.

Hneď pod "See also" a "Example code File" sú tri tlačítka, ktoré dovoľujú pridať alebo odstrániť odkazy na iné stránky alebo príklady kódu.

Výsledok

Pozrite sa na výsledok popisu InputQuery. Na vrchu stránky môžete vidieť o čom stránka je, v tomto prípade "Use InputQuery to show a dialog box to get some input from the user". Prvý riadok textu je to, čo ste zadali do "Short" editbox v lazde.

nasleduje deklarácia tejto funkcie v zdrojovom kóde. Časť deklarácie je vytvorená pomocou html-builder a je vzatá z zo zdrojového kódu. Pretože sú dve verzie tejto funkcie, zdrojová pouícia vraví 0.

Potom sú dané argumenty. Keď otvoríte uzol InputQuery v lazde, uvidíte všetky argumenty označené ako podriadené uzly. Text, zobrazený za argumentami je opäť to, čo bolo zadané v "Short" editbox, keď vybraný príslušný príslušný podriadený uzol.

Ako štvrtý odsek je zobrazený výsledok funkcie. Tu zobrazený text je možné zadať rovnako ako pri argumentoch.

Nakoniecje zobrazený popis, to je text napísaný v okne popisu v lazde.

Doplnenie nových unít

Samozrejme, že je potrebné dokumentovať i ďalšie unity. Ak sa jedná, napríklad o unitu nejakého balíčka, pravdepodobne ešte neexistuje počiatočný XML súbor. Potom treba začať od začiatku a lazde ponúka funkciu, pomocou ktorej môžete priamo začať. Jednoducho použite File -> New a objaví sa nasledujúca obrazovka:

Začnite zadaním mena balíčka. Všetky jednotky, ktoré chcete tohoto balíčka musia mať rovnaké meno balíčka. Potom zadajte meno príslušného zdrojového súboru, môžete ho tiež nájsť pomocou prehľadávania súborového systému. Nakoniec zadajte meno výstupného súboru (nezabudnite na príponu xml!) a stlačte OK.

lazde vygeneruje základ pre dokumentáciu. Vygenerovaný súbor bude otvorený a treeview bude zaplnený všetkými unitami, triedami, typmi, funkciami atď, zo zadaného zdrojového súboru a ste pripravení začať dokumentovať novú časť Lazarus.

Pozrite sa na LCL Documentation Roadmap, aby ste videli, ktoré jednotky ešte treba zdokumentovať.

Pre jednoduchú aktualizáciu súborov FPDoc, pri zmene unít Pascal, môžete použiť aktualizátor FPDoc.

Konečný výsledok

Počas používania programu som zistil, že by bolo dobré vidieť ako sú informácie zobrazené v konečnom štádiu (ako prehliadateľný dokument). Pre tento účel lazde sprístupňuje nástroj pre vybudovanie všetkých potrebných HTML súborov.

Tento nástroj možno spustiť z menu Extra -> Build a zobrazí sa Vám nasledujúca obrazovka:

"Package" musí byť rovnaké ako meno, ktoré ste zadali pri vytváraní xml súborov. Ako "Format" zvoľte HTML. Do "Output" zadajte cestu, kde majú byť výsledné súbory uložené. Stlačte "Add all" a všetky dokumenty, na ktorých ste pracovali, budú pridané do projektu. Potom prejdite na nasledujúcu záložku

a zadajte cestu k zdrojovým súborom. Po stlačení "Build" začne Váš HD rapotať a nakoniec sa v záložke "Build output" objaví nasledujúci výstup

Building docs using command: fpdoc --package="LCL"
--output="/home/matthijs/documentatie/LCL" --format=html --content 
--descr="/home/matthijs/Projecten/Lazarus/doceditor/buttons.xml"
--descr="/home/matthijs/Projecten/Lazarus/doceditor/comctrls.xml"
--descr="/home/matthijs/Projecten/Lazarus/doceditor/dialogs.xml"
--descr="/home/matthijs/Projecten/Lazarus/doceditor/controls.xml"
--input="/home/matthijs/cvsroot/lazarus/lcl/buttons.pp"
--input="/home/matthijs/cvsroot/lazarus/lcl/comctrls.pp"
--input="/home/matthijs/cvsroot/lazarus/lcl/dialogs.pp"
--input="/home/matthijs/cvsroot/lazarus/lcl/controls.pp" 

FPDoc - Free Pascal Documentation Tool
(c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther, sg@freepascal.org

Writing 2788 pages...
Done.
Documentation successfully built.

Keď vojdete do adresára, ktorý ste zadali ako "Output", uvidíte súbor index.html a (v tomto prípade 4) podadresáre. Otvorte index.html vo svojom prehliadači a pozrite si výstup celej svojej ťažkej práce na dokumentácii. Budete môcť následovať odkazy a prečítať tak všetko.

Ak plánujete pokračovať v práci na dokumentácii tohoto balíčka, stlačte "Save" a uložte voľby budovania. Dostanete otázku na meno súboru a voľby budú uložené. Pri ďalšom generovaní HTML súborov ich len jednoducho načítate.

Odoslanie

Keď budete so svojou prácou spokojní, asi ju budete chcieť zdieľať s komunitou Lazarus. Všetko, čo k tomu potrebujete je vytvoriť patch, zazipovať ho a poslať.

Malá poznámka

Pamätajte na nasledujúce: lazde je stále vo vývoji. Je použiteľný, ale zatiaľ nie je úplne dokončený. Preto sa v ňom môžu objaviť chyby, ale budú odstránené.

Spolupracovníci a zmeny

• Preložil --Komunista 16:08, 30 December 2007 (CET)