Lazarus Documentation Editor/pl
│
Deutsch (de) │
English (en) │
español (es) │
français (fr) │
日本語 (ja) │
polski (pl) │
русский (ru) │
slovenčina (sk) │
Wprowadzenie
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.
Uzasadnienie
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.
Duża liczba takich plików XML została już napisana i można ich użyć:
- do stworzenia stron HTML, które możesz przeglądać na http://lazarus-ccr.sourceforge.net/docs/lcl/
- 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.
Tworzenie dokumentacji w praktyce
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.
Narzędzie do edycji dokumentacji Lazarusa
„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. 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
Dokumentowanie LCL
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.
Wybranie węzła w lewym dolnym widoku drzewa wyświetla zawartość tego węzła po prawej stronie okna.
Gdy spojrzysz na tą stronę, 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).
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.
Uwaga: Jeśli chcesz wstawić znak podziału wiersza użyj <br/>Pod polem „Opis” znajdują się kolejne pola oznaczone „Błędy” ("Errors"), „Zobacz także” ("See also") i „Example code File” (Przykładowy plik kodu).
Uwaga: Nazwy wielu pól formularzy nie są jeszcze przetłumaczonePole „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ę.
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.
Wynik
Spójrz na opis InputQuery.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.
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.
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.
Wynik funkcji jest pokazany jako czwarty akapit. Tekst pokazany tutaj został wprowadzony w taki sam sposób jak dla argumentów funkcji.
Na koniec wyświetlany jest opis. To jest tekst wpisany w polu „Opis”.
Dodawanie dokumentacji dla nowych modułów
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”:
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.
Następnie wstaw nazwę pakietu poprzez wybranie z menu: Wstaw -> Pakiet (np. lcl) oraz nazwę modułu: Wstaw -> Moduł.
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.
Spójrz na LCL Documentation Roadmap/pl, aby zobaczyć, które jednostki wymagają jeszcze udokumentowania.
Możesz użyć FPDoc Updater, aby łatwo zaktualizować pliki FPDoc po zmianie modułu Pascal.
Wynik końcowy
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.
Narzędzie to można uruchomić z menu Extra -> Build. Wyświetli się następujący ekran:
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
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.
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.
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.
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”).
Przedłożenie swojej pracy
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ć łatkę, spakować ją do archiwum zip i wysłać.
Ulepszenia mile widziane
Uwaga: 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!