Difference between revisions of "Lazarus Documentation Editor"

From Free Pascal wiki
(The addition of new units)
(The Final result)
Line 60: Line 60:
  
 
== The Final result ==
 
== 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:
 +
<center>[[Image:Lazdebuild1.png]]</center>
 +
Press "Add all" and all documents your were working on will be added to the project. Then go to the next to tab
 +
<center>[[Image:Lazdebuild2.png]]</center>
 +
and enter the paths to the source files.

Revision as of 13:30, 20 May 2005

Introduction

This is work in progress.

An important part of Lazarus still missing is the documentation. To aid in the making of this documentation a tool has been developed. This page will describe the workings of this tool. To denote the Lazarus base directory in this document I use [$LazDir]. So when you read this replace this with the directory Lazarus is installed in.

The Why

The first goal of this project is to be make a online help-file available. To make the help-file platform independent we start to create XML-files for each unit used in Lazarus. So far only dialogs.pp and buttons.pp have had a start.

These XML-files will then be used to create HTML-pages which can be accessed through the Internet on http://lazarus-ccr.sourceforge.net/docs/lcl/ . Then at a later stage a integrated help will be developed again using these same XML-files.

The Start

As mentioned before, to keep the documentation platform independent XML is used. The current documentation can be found in [$LazDir]/docs/xml/. So far there are mostly skeleton files in the lcl directory. The XML files you find in this directory are auto generated and need to be adapted to be usable. So now we know where to find the files, lets look at the tool to create / adapt them.

The Tool

"lazde" is a tool to edit the xml files, but can also be used to generate the basic files from source files and by means of an external tool to generate a HTML version of the documentation. An example of the results of the last tool can be seen here, a part of the documentation sofar. As there is no compiled version of lazde, you have to make one yourself. The sources for "lazde" can be found in [$LazDir]/doceditor/. When you run this program and you have opened [$LazDir]/docs/xml/lcl/dialogs.xml you will be presented with this screen

Lazdemain.png

The Work

Opening the node "Packages" will show the "LCL" node which contains a "Dialogs" node. Selecting this last node will fill the lower treeview with elements. These elements depict Constants, Types and Classes defined in the Dialogs.pp unit. Used units are added as well as nodes. Other nodes are added for the properies of a class, the parameters for a function and so on.

Selecting a node in the lower left treeview will make the content of that node displayed on the right side of the window.

When you look at this page you will see an overview of classes defined in the "dialogs" unit. After each class you see a line of text. This text comes from the "short" editbox from lazde.

Below the "short" editbox, there is a memofield where you can enter a more elaborate description of the component or the property.

Note: If you want to insert a line break use <br/>

Next are "Errors", "See also" and "Example code File".

"Errors" can be used to tell about errors raised by a function if parameters have values that are out of range. For an example see this page.

Just above "See also" and "Example code File" you see three buttons. These buttons enable you to add and remove links to other pages or code examples respectively.

The Results

Have a look at the description of InputQuery. On the top of the page we see what the page is about, in this case the InputQuery function form the dialogs.pp. The first line of text is what is entered in the "Short" editbox in lazde.

Next is the declaration of this function in the sources. The declaration part is created by the html-builder and is taken from the sources. Because there are two versions of this function the source position says 0.

Then the arguments are given. When you open the InputQuery node in lazde you will see all arguments mentioned as child nodes. The text shown after the arguments is what has been entered in the "Short" editbox when the respective child nodes are selected.

As a fourth paragraph the Function result is shown. The text shown here has been entered in the same way as the arguments.

Finally the description is shown. This is the text entered in the description box of lazde.

The addition of new units

There are off course other units that need to be documented. If it is for instance a unit for some package, chances are there is no xml file to start with. You have to start from scratch then, but lazde has a function to get you off in a flying start. Just go to File -> New from file and the following screen will appear:

Lazdenewdocfromfile.png

You start by giving the package a name. All units you want to add to this package should have the same package name. Afterwards you enter the source file to use, you can browse to this file as well. Then enter a name for the output file. (Do not forget the xml extension!) And press OK.

lazde will then generate the basics for the documentation. The generated file will be opened and the treeview will be populated by all units, classes, types, functions and so on form your source file. Now you are ready to start documenting a new part of Lazarus.

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:

Lazdebuild1.png

Press "Add all" and all documents your were working on will be added to the project. Then go to the next to tab

Lazdebuild2.png

and enter the paths to the source files.