Lazarus Documentation Editor/sk: what changed
Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | 1 | ## Úvod | |
| 2 | 2 | ||
| 3 | 3 | 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ý. | |
| 4 | 4 | ||
| 5 | 5 | ## Prečo | |
| 6 | 6 | ||
| 7 | 7 | 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. | |
| 8 | 8 | ||
| 9 | 9 | Tieto XML súbory budú potom použité pre vytvorenie HTML stránok, ktorú budú prístupné cez Internet na [stránke dokumentácie](http://lazarus-ccr.sourceforge.net/docs/lcl/). Nakoniec bude vytvorená integrovaná nápoveda, znova pomocou týchto XML súborov. | |
| 10 | 10 | ||
| 11 | 11 | ## Začiatok | |
| 12 | 12 | ||
| 13 | 13 | 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ť. | |
| 14 | 14 | ||
| 15 | 15 | Takže teraz, keď už viete kde máte hľadať súbory, poďme sa pozrieť na nástroj pre ich vytvorenie/úpravu. | |
| 16 | 16 | ||
| 17 | 17 | ### Nástroj | |
| 18 | 18 | ||
| 19 | 19 | "**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](http://lazarus-ccr.sourceforge.net/docs/lcl/index.html), ako časť dokumentácie. Keďže nie je poskytovaná kompilovaná verzia **lazde**, musíte si ju urobiť sami. | |
| 20 | 20 | ||
| 21 | 21 | 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 | |
| 22 | 22 | ||
| 23 | - | ||
| 24 | - | ||
| 25 | - | ||
| 26 | - | ||
| 27 | - | ||
| 28 | - | ||
| 29 | - | ||
| 30 | - | ||
| 23 | + |  | |
| 31 | 24 | ||
| 32 | 25 | ### Práca | |
| 33 | 26 | ||
| 34 | - | ||
| 35 | - | ||
| 36 | - | ||
| 37 | - | ||
| 27 | + |  | |
| 38 | 28 | ||
| 39 | 29 | 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. | |
| 40 | 30 | ||
| 41 | 31 | Zvolením uzla v ľavom dolnom treeview vytvorí obsah daného uzla v pravej časti okna. | |
| 42 | 32 | ||
| 43 | 33 | Keď navštívite [túto stránku](http://lazarus-ccr.sourceforge.net/docs/lcl/dialogs/index-4.html), 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. | |
| 44 | 34 | ||
| 45 | 35 | Pod "short" editbox, je memofield, do ktorého môžete zadať viac vypracovaný popis komponentu alebo vlastnosti. | |
| 46 | 36 | ||
| 47 | 37 | `Poznámka: Ak chcete vložiť koniec ridku použite <br/>` | |
| 48 | 38 | ||
| 49 | 39 | Nasledujú Chyby (*Errors*), Pozrieť aj (*See also*) a Príklad kódu (*Example code File*). | |
| 50 | 40 | ||
| 51 | 41 | "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](http://lazarus-ccr.sourceforge.net/docs/rtl/dateutils/recodeyear.html). | |
| 52 | 42 | ||
| 53 | 43 | 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. | |
| 54 | 44 | ||
| 55 | 45 | ## Výsledok | |
| 56 | 46 | ||
| 57 | 47 | Pozrite sa na výsledok popisu [InputQuery](http://lazarus-ccr.sourceforge.net/docs/lcl/dialogs/inputquery.html). 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. | |
| 58 | 48 | ||
| 59 | 49 | 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. | |
| 60 | 50 | ||
| 61 | 51 | 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. | |
| 62 | 52 | ||
| 63 | 53 | Ako štvrtý odsek je zobrazený výsledok funkcie. Tu zobrazený text je možné zadať rovnako ako pri argumentoch. | |
| 64 | 54 | ||
| 65 | 55 | Nakoniecje zobrazený popis, to je text napísaný v okne popisu v lazde. | |
| 66 | 56 | ||
| 67 | 57 | ## Doplnenie nových unít | |
| 68 | 58 | ||
| 69 | 59 | 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: | |
| 70 | 60 | ||
| 71 | - | ||
| 72 | - | ||
| 73 | - | ||
| 74 | - | ||
| 75 | - | ||
| 76 | - | ||
| 77 | - | ||
| 78 | - | ||
| 61 | + |  | |
| 79 | 62 | ||
| 80 | 63 | 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. | |
| 81 | 64 | ||
| 82 | 65 | **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. | |
| 83 | 66 | ||
| 84 | 67 | Pozrite sa na [[LCL Documentation Roadmap]], aby ste videli, ktoré jednotky ešte treba zdokumentovať. | |
| 85 | 68 | ||
| 86 | 69 | Pre jednoduchú aktualizáciu súborov FPDoc, pri zmene unít Pascal, môžete použiť [[FPDoc Updater|aktualizátor FPDoc]]. | |
| 87 | 70 | ||
| 88 | 71 | ## Konečný výsledok | |
| 89 | 72 | ||
| 90 | 73 | 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. | |
| 91 | 74 | ||
| 92 | 75 | Tento nástroj možno spustiť z menu **Extra -\> Build** a zobrazí sa Vám nasledujúca obrazovka: | |
| 93 | 76 | ||
| 94 | - | ||
| 95 | - | ||
| 96 | - | ||
| 97 | - | ||
| 98 | - | ||
| 99 | - | ||
| 100 | - | ||
| 101 | - | ||
| 77 | + |  | |
| 102 | 78 | ||
| 103 | 79 | "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 | |
| 104 | 80 | ||
| 105 | - | ||
| 106 | - | ||
| 107 | - | ||
| 108 | - | ||
| 109 | - | ||
| 110 | - | ||
| 111 | - | ||
| 112 | - | ||
| 81 | + |  | |
| 113 | 82 | ||
| 114 | 83 | 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 | |
| 115 | 84 | ||
| 116 | 85 | `Building docs using command: fpdoc --package="LCL"`\ | |
| 117 | 86 | `--output="/home/matthijs/documentatie/LCL" --format=html --content `\ | |
| 118 | 87 | `--descr="/home/matthijs/Projecten/Lazarus/doceditor/buttons.xml"`\ | |
| 119 | 88 | `--descr="/home/matthijs/Projecten/Lazarus/doceditor/comctrls.xml"`\ | |
| 120 | 89 | `--descr="/home/matthijs/Projecten/Lazarus/doceditor/dialogs.xml"`\ | |
| 121 | 90 | `--descr="/home/matthijs/Projecten/Lazarus/doceditor/controls.xml"`\ | |
| 122 | 91 | `--input="/home/matthijs/cvsroot/lazarus/lcl/buttons.pp"`\ | |
| 123 | 92 | `--input="/home/matthijs/cvsroot/lazarus/lcl/comctrls.pp"`\ | |
| 124 | 93 | `--input="/home/matthijs/cvsroot/lazarus/lcl/dialogs.pp"`\ | |
| 125 | 94 | `--input="/home/matthijs/cvsroot/lazarus/lcl/controls.pp" `\ | |
| 126 | - | ||
| 95 | + | ||
| 127 | 96 | `FPDoc - Free Pascal Documentation Tool`\ | |
| 128 | 97 | `(c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther, sg@freepascal.org`\ | |
| 129 | - | ||
| 98 | + | ||
| 130 | 99 | `Writing 2788 pages...`\ | |
| 131 | 100 | `Done.`\ | |
| 132 | 101 | `Documentation successfully built.` | |
| 133 | 102 | ||
| 134 | 103 | 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. | |
| 135 | 104 | ||
| 136 | 105 | 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. | |
| 137 | 106 | ||
| 138 | 107 | ## Odoslanie | |
| 139 | 108 | ||
| 140 | 109 | Keď budete so svojou prácou spokojní, asi ju budete chcieť zdieľať s komunitou Lazarus. Všetko, čo k tomu potrebujete je vytvoriť [[Creating A Patch/sk|patch]], zazipovať ho a poslať. | |
| 141 | 110 | ||
| 142 | 111 | ## Malá poznámka | |
| 143 | 112 | ||
| 144 | 113 | 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é. | |
| 145 | 114 | ||
| 146 | 115 | ## Spolupracovníci a zmeny | |
| 147 | 116 | ||
| 148 | 117 | - Preložil --Komunista 16:08, 30 December 2007 (CET) | |
| 149 | 118 | ||
| 150 | 119 | --- | |
| 151 | 120 | *From the Free Pascal wiki, page "Lazarus Documentation Editor/sk", as it stood on 2015-11-09 after a change by Trsek, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).* |