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 „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 „Description” (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 „Description” znajdują się kolejne pola oznaczone „Errors” (błędy), „See also” (zobacz także) i „Example code File” (Przykładowy plik kodu).

Pole „Errors” 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 „ZSee also” 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 „Description”.

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 File -> New i pojawi się następujący ekran:

Zaczynasz od nazwania pakietu. Wszystkie moduły, które chcesz dodać do tego pakietu, powinny mieć tę samą nazwę pakietu. Następnie wprowadź plik źródłowy do użycia. Możesz również przejść do tego pliku. Następnie wprowadź nazwę pliku wyjściowego - nie zapomnij o rozszerzeniu xml! - i kliknij OK.

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, aby zobaczyć, które jednostki wymagają jeszcze udokumentowania.

Możesz użyć FPDoc Updater, aby łatwo zaktualizować pliki FPDoc po zmianie jednostek Pascal.

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.

Submitting your work

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

Improvements welcome

  Uwaga: lazde is a work-in-progress. It does work, but it's certainly not completely finished yet. You may encounter bugs. Feel free to fix them!