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ápodvedy. 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 dokemntáciu nájdete v [$LazDir]/docs/xml/. Zatiaľ tam je väčšinou len kostrové súbory v adresári lcl. XML súbory, ktoré sú v tomto adresári sú automaticky vytvorené a treba ich prispôsobiť pre použitie. Takže teraz, keď už viete kde máte hľadať súbory, sa po´dme 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éhonástroja aj na generovanie HTML verzie dokumentácie. Napríklad výsledok posledného nástroja môžete vidieť na tejto stránke, ako časti 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žou 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íkladpozrite 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 jodnoduchú aktualizáciu súborov FPDoc, pri zmene unít Pascal, môžete použiť aktualizátor FPDoc.

The Final result

What I experienced during the use of the program is that I would like to see how the information is shown in its final stage (as a browsable document). For this purpose lazde makes use of a utility to build all necessary HTML-files.

This utility can be started from the menu Extra -> Build. The following screen will be shown:

"Package" should be the same as the name you gave when you created the xml files. For "Format" choose HTML. At "Output" you enter the path where the resulting files should be placed. Press "Add all" and all documents your were working on will be added to the project. Then go to the next to tab

and enter the paths to the source files. After you have pressed build your HD will start to rattle and finally the following output will be shown on the "Build output" tab.

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.

When you go to the directory you entered at "Output" you will see a index.html file and (in this case 4) sub directories. Open index.html in your favorit browser and see the result of all your hard work on the documentation. You will be able to follow the links and read it all.

When you plan to continue working on this package of documentation, press "Save" and save the build options. You will be asked to provide a name for the file and the options will be saved. Next time you want to build the HTML-files you can just "load" them again.

The Submission

When you are satisfied with your work you certainly want to share it with the Lazarus community. All you have to do is make a patch, zip this and send it in.

A small note

Note the following: The lazde is work in progress. It is workable, but not completely finished yet. So there can be some bugs in it, but feel free to fix them.