Lazarus Documentation Editor/pl: what changed
Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.
| Old | New | Line | |
|---|---|---|---|
| 1 | 1 | Edytor dokumentacji Lazarusa | |
| 2 | 2 | ||
| 3 | 3 | ## Wprowadzenie | |
| 4 | 4 | ||
| 5 | 5 | Dobra, wszechstronna dokumentacja jest ważną brakującą częścią Lazarusa. Aby pomóc w opracowaniu potrzebnej dokumentacji, opracowano narzędzie o nazwie LazDE. Ta strona opisuje użycie tego narzędzia do edycji istniejącej dokumentacji lub do tworzenia nowych plików dokumentacji. W tym dokumencie wiki używam \[\$LazDir\] do oznaczenia ścieżki do katalogu bazowego Lazarusa. Więc kiedy znajdziesz w tekście \[\$LazDir\], po prostu zastąp go ścieżką odpowiednią dla instalacji Lazarusa w twoim systemie. | |
| 6 | 6 | ||
| 7 | 7 | ## Uzasadnienie | |
| 8 | 8 | ||
| 9 | 9 | Głównym celem tego projektu dokumentacji jest udostępnienie pliku pomocy online. Aby stworzyć pliki pomocy niezależne od platformy, używamy plików XML do rejestrowania i przechowywania danych dokumentacji. Każda jednostka Lazarusa ma swój własny plik danych XML. | |
| 10 | 10 | ||
| 11 | 11 | Duża liczba takich plików XML została już napisana i można ich użyć: | |
| 12 | 12 | ||
| 13 | 13 | - do stworzenia stron HTML, które możesz przeglądać na <http://lazarus-ccr.sourceforge.net/docs/lcl/> | |
| 14 | 14 | - do stworzenia plików CHM, które możesz przeglądać w trybie offline (po umieszczeniu w poprawnie zarejestrowanym katalogu lokalnym) jako pomoc dla Lazarus, która jest dostępna nawet wtedy, gdy nie masz dostępu do Internetu. | |
| 15 | 15 | ||
| 16 | 16 | ## Tworzenie dokumentacji w praktyce | |
| 17 | 17 | ||
| 18 | 18 | Jak wspomniano powyżej, XML został wybrany jako format danych dokumentacji, ponieważ jest niezależny od platformy. Aktualną dokumentację można znaleźć w \[\$LazDir\]/docs/xml/. Do tej pory w katalogu /lcl/ znajdują się głównie puste pliki szkieletu, które zawierają niewiele (lub nie zawierają) użytecznej dokumentacji. Pliki XML, które znajdziesz w tym katalogu, są generowane automatycznie i wymagają dostosowania, aby były użyteczne. Teraz gdy wiemy, gdzie znaleźć te pliki, spójrzmy na narzędzie, które zastosujemy aby stworzyć i dostosować pliki danych dokumentacji. | |
| 19 | 19 | ||
| 20 | 20 | ### Narzędzie do edycji dokumentacji Lazarusa | |
| 21 | 21 | ||
| 22 | 22 | „Lazde” jest narzędziem przeznaczonym do edycji plików dokumentacji XML. Można go również użyć do wygenerowania podstawowego szkieletu pliku XML pochodzącego ze źródłowego pliku modułu (unit) Pascala i (za pomocą zewnętrznego narzędzia FPDoc) do wygenerowania wersji HTML dokumentacji. Przykład wyniku działania FPDoc można zobaczyć [tutaj](http://lazarus-ccr.sourceforge.net/docs/lcl/index.html). Jest to część dotychczas utworzonej dokumentacji. Ponieważ skompilowane wersje wykonywalne programu lazde nie są dostarczane, musisz go zbudować dla siebie. Pliki źródłowe „lazde” można znaleźć w \[\$LazDir\]/doceditor/. Po zbudowaniu i uruchomieniu tego programu oraz po otwarciu pliku \[\$LazDir\]/docs/xml/lcl/dialogs.xml zostanie wyświetlony ten ekran | |
| 23 | 23 | ||
| 24 | 24 |  | |
| 25 | 25 | ||
| 26 | 26 | ### Dokumentowanie LCL | |
| 27 | 27 | ||
| 28 | 28 |  | |
| 29 | 29 | ||
| 30 | 30 | Otwarcie węzła „Pakiety” (en: "Packages") pokazuje węzeł „LCL”, który zawiera węzeł „Dialogs” (Okna dialogowe). Wybranie tego ostatniego węzła wypełnia dolny widok drzewa elementami. Te elementy zawierają listę stałych, typów i klas zdefiniowanych w module dialogs.pp. Wszelkie moduły używane przez dialogs.pp są również dodawane jako kolejne węzły. Inne węzły są dodawane dla właściwości klasy, parametrów funkcji i procedur i tak dalej. | |
| 31 | 31 | ||
| 32 | 32 | Wybranie węzła w lewym dolnym widoku drzewa wyświetla zawartość tego węzła po prawej stronie okna. | |
| 33 | 33 | ||
| 34 | 34 | Gdy spojrzysz na [tą stronę](https://lazarus-ccr.sourceforge.io/docs/lcl/dialogs/index-4.html), zobaczysz przegląd klas zdefiniowanych w module „dialogs”. Po każdej nazwie klasy zobaczysz linię tekstu, którą została wpisana w pole edycyjne „Short” (krótki opis). | |
| 35 | 35 | ||
| 36 | 36 | Poniżej pola edycji „Short” znajduje się pole notatnika „Opis” (en: "Descryption" - pole typu memo), w którym można wprowadzić dłuższy opis komponentu lub właściwości. | |
| 37 | 37 | ||
| 38 | 38 | > **Note:** Jeśli chcesz wstawić znak podziału wiersza użyj \<br/\> | |
| 39 | 39 | ||
| 40 | 40 | Pod polem „Opis” znajdują się kolejne pola oznaczone „Błędy” ("Errors"), „Zobacz także” ("See also") i „Example code File” (Przykładowy plik kodu). | |
| 41 | 41 | ||
| 42 | 42 | > **Note:** Nazwy wielu pól formularzy nie są jeszcze przetłumaczone | |
| 43 | 43 | ||
| 44 | 44 | Pole „Błędy” jest używane do przekazywania informacji o błędach zgłaszanych przez funkcję, jeśli parametry mają wartości spoza zakresu. Na przykład zobacz [tą stronę](https://lazarus-ccr.sourceforge.io/docs/rtl/dateutils/recodeyear.html). | |
| 45 | 45 | ||
| 46 | 46 | Pola „Zobacz także” i „Example code File” zawierają po trzy przyciski (\[+\], \[^\], \[-\]). Te przyciski umożliwiają dodawanie i usuwanie linków odpowiednio do innych stron lub przykładów kodu. | |
| 47 | 47 | ||
| 48 | 48 | ## Wynik | |
| 49 | 49 | ||
| 50 | 50 | Spójrz na opis [InputQuery](https://lazarus-ccr.sourceforge.io/docs/lcl/dialogs/inputquery.html).U góry strony możesz zobaczyć, o czym jest strona (w tym przypadku funkcja InputQuery z dialogs.pp). Pierwszy wiersz tekstu jest tym, który został wprowadzony w polu edycji „Short” w lazde. | |
| 51 | 51 | ||
| 52 | 52 | Dalej jest deklaracja tej funkcji zaczerpnięta z pliku źródłowego dialogs.pp. Część deklaracji jest tworzona przez program budujący HTML i jest analizowana bezpośrednio ze źródeł. Ponieważ istnieją dwie wersje tej funkcji, pozycja źródłowa mówi 0. | |
| 53 | 53 | ||
| 54 | 54 | Następnie podane są argumenty. Kiedy otworzysz węzeł InputQuery w lazde, zobaczysz każdy argument osobno jako węzeł potomny. Tekst wyświetlany po każdym argumencie odpowiada temu, co zostało wprowadzone w polu edycji „Short”, gdy wybrany został odpowiedni węzeł potomny. | |
| 55 | 55 | ||
| 56 | 56 | Wynik funkcji jest pokazany jako czwarty akapit. Tekst pokazany tutaj został wprowadzony w taki sam sposób jak dla argumentów funkcji. | |
| 57 | 57 | ||
| 58 | 58 | Na koniec wyświetlany jest opis. To jest tekst wpisany w polu „Opis”. | |
| 59 | 59 | ||
| 60 | 60 | ## Dodawanie dokumentacji dla nowych modułów | |
| 61 | 61 | ||
| 62 | 62 | Oczywiście wiele innych modułów czeka na opisanie dokumentacji. Jeśli moduł jest częścią pakietu, prawdopodobnie nie ma pliku XML, z którego można zacząć. Będziesz wtedy musiał zacząć od zera, a lazde ma funkcję, która zabierze Cię do szybkiego startu. Wystarczy przejść do menu Plik -\> Nowy i pojawi się dodatkowa zakładka o nazwie „Nowy dokument”: | |
| 63 | 63 | ||
| 64 | 64 |  | |
| 65 | 65 | ||
| 66 | 66 | Zaczynasz od nazwania pakietu poprzez zapisanie go do nowego liku, któremu nadajesz nazwę. Wszystkie moduły, które chcesz dodać do tego pakietu, powinny mieć tę samą nazwę pakietu. Wprowadzając nazwę pliku wyjściowego nie zapomnij o rozszerzeniu xml! - i kliknij OK. | |
| 67 | 67 | ||
| 68 | 68 | Następnie wstaw nazwę pakietu poprzez wybranie z menu: Wstaw -\> Pakiet (np. lcl) oraz nazwę modułu: Wstaw -\> Moduł. | |
| 69 | 69 | ||
| 70 | 70 | Lazde wygeneruje wówczas szkielet dokumentacji. Wygenerowany plik zostanie otwarty, a widok drzewa zostanie zapełniony wszystkimi modułami, klasami, typami, funkcjami itd. z pliku źródłowego. Teraz możesz rozpocząć dokumentowanie nowej części Lazarusa. | |
| 71 | 71 | ||
| 72 | 72 | Spójrz na [[LCL Documentation Roadmap/pl]], aby zobaczyć, które jednostki wymagają jeszcze udokumentowania. | |
| 73 | 73 | ||
| 74 | 74 | Możesz użyć [[FPDoc Updater]], aby łatwo zaktualizować pliki FPDoc po zmianie modułu Pascal. | |
| 75 | 75 | ||
| 76 | 76 | ## Wynik końcowy | |
| 77 | 77 | ||
| 78 | 78 | Podczas korzystania z programu doświadczyłem tego, że chciałem zobaczyć, w jaki sposób informacje są wyświetlane w końcowym etapie (jako dokument możliwy do przeglądania). W tym celu Lazde korzysta z narzędzia do budowy wszystkich niezbędnych plików HTML. | |
| 79 | 79 | ||
| 80 | 80 | Narzędzie to można uruchomić z menu Extra -\> Build. Wyświetli się następujący ekran: | |
| 81 | 81 | ||
| 82 | 82 |  | |
| 83 | 83 | ||
| 84 | 84 | Nazwa w „Package” powinna być taka sama, jak nazwa nadana podczas tworzenia plików XML. Jako „Format” wybierz HTML. W „Output” podaj ścieżkę, w której powinny być umieszczone pliki wynikowe. Naciśnij „Add all”, a wszystkie dokumenty, nad którymi pracowałeś, zostaną dodane do projektu. Następnie przejdź do następnej karty | |
| 85 | 85 | ||
| 86 | 86 |  | |
| 87 | 87 | ||
| 88 | 88 | i wprowadź ścieżki do plików źródłowych. Po naciśnięciu „Build” dysk zacznie pracować, a na końcu w zakładce „Build output” pojawi się następujący wynik. | |
| 89 | 89 | ||
| 90 | - | ||
| 91 | - | ||
| 92 | - | ||
| 93 | - | ||
| 94 | - | ||
| 95 | - | ||
| 96 | - | ||
| 97 | - | ||
| 98 | - | ||
| 99 | - | ||
| 90 | + | ```text | |
| 91 | + | Building docs using command: fpdoc --package="LCL" | |
| 92 | + | --output="/home/matthijs/documentatie/LCL" --format=html --content | |
| 93 | + | --descr="/home/matthijs/Projecten/Lazarus/doceditor/buttons.xml" | |
| 94 | + | --descr="/home/matthijs/Projecten/Lazarus/doceditor/comctrls.xml" | |
| 95 | + | --descr="/home/matthijs/Projecten/Lazarus/doceditor/dialogs.xml" | |
| 96 | + | --descr="/home/matthijs/Projecten/Lazarus/doceditor/controls.xml" | |
| 97 | + | --input="/home/matthijs/cvsroot/lazarus/lcl/buttons.pp" | |
| 98 | + | --input="/home/matthijs/cvsroot/lazarus/lcl/comctrls.pp" | |
| 99 | + | --input="/home/matthijs/cvsroot/lazarus/lcl/dialogs.pp" | |
| 100 | + | --input="/home/matthijs/cvsroot/lazarus/lcl/controls.pp" | |
| 100 | 101 | ||
| 101 | - | ||
| 102 | - | ||
| 102 | + | FPDoc - Free Pascal Documentation Tool | |
| 103 | + | (c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther, sg@freepascal.org | |
| 103 | 104 | ||
| 104 | - | ||
| 105 | - | ||
| 106 | - | ||
| 105 | + | Writing 2788 pages... | |
| 106 | + | Done. | |
| 107 | + | Documentation successfully built. | |
| 108 | + | ``` | |
| 107 | 109 | ||
| 108 | 110 | Po przejściu do katalogu podanego w „Output” zobaczysz plik index.html i (w tym przypadku 4) podkatalogi. Otwórz index.html w swojej ulubionej przeglądarce i zobacz wyniki ciężkiej pracy nad dokumentacją. Będziesz mógł podążać za linkami i przeczytać wszystko. | |
| 109 | 111 | ||
| 110 | 112 | Jeśli planujesz kontynuować pracę nad tym pakietem dokumentacji, naciśnij „Save” i zapisz opcje kompilacji. Zostaniesz poproszony o podanie nazwy pliku, a opcje zostaną zapisane. Następnym razem, gdy chcesz zbudować pliki HTML, możesz po prostu „załadować” je ponownie („Load”). | |
| 111 | 113 | ||
| 112 | 114 | ## Przedłożenie swojej pracy | |
| 113 | 115 | ||
| 114 | 116 | Kiedy będziesz zadowolony z pracy nad dokumentacją lazarusa, z pewnością będziesz chcieć podzielić się nią ze społecznością Lazarusa. Wszystko, co musisz zrobić, to przygotować [[Creating A Patch|łatkę]], spakować ją do archiwum zip i wysłać. | |
| 115 | 117 | ||
| 116 | 118 | ## Ulepszenia mile widziane | |
| 117 | 119 | ||
| 118 | 120 | > **Note:** Lazde jest w trakcie tworzenia. Działa, ale z pewnością nie jest jeszcze całkowicie ukończony. Możliwe, że napotkasz błędy. Jeśli możesz, napraw je! | |
| 119 | 121 | ||
| 120 | 122 | --- | |
| 121 | 123 | *From the Free Pascal wiki, page "Lazarus Documentation Editor/pl", as it stood on 2022-06-02 after a change by Slawek, 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).* |