Difference between revisions of "Lazarus Documentation Editor/es"

From Free Pascal wiki
Jump to navigationJump to search
Line 54: Line 54:
  
 
== La adición de nuevas unidades ==
 
== La adición de nuevas unidades ==
Por supuesto, hay otras unidades que han de estar documentadas. Si es, por ejemplo, una unidad de algún paquete, es probable que no hay ningún archivo xml para empezar. Tienes entonces que empezar de cero, pero "Lazde" tiene una función para hacerle frente al comienzo. Sólo tienes que ir a Archivo -> Nuevo y aparecerá la siguiente pantalla:
+
Por supuesto, hay otras unidades que han de estar documentadas. Si es, por ejemplo, una unidad de algún paquete, es probable que no hay ningún archivo xml para empezar. Tienes entonces que empezar desde cero, pero "Lazde" tiene una función para hacerle frente al comienzo. Sólo tienes que ir a Archivo -> Nuevo y aparecerá la siguiente pantalla:
 
<center> [[Image: Lazdenewdocfromfile.png]] </center>
 
<center> [[Image: Lazdenewdocfromfile.png]] </center>
 
Se comienza dando un nombre al paquete. Todas las unidades que desees agregar a este paquete deben tener el nombre del paquete mismo. Posteriormente se introduce el código fuente a utilizar, puedes navegar por este archivo también. A continuación, escribe un nombre para el archivo de salida. (No olvides la extensión xml!) Y pulsa Aceptar.
 
Se comienza dando un nombre al paquete. Todas las unidades que desees agregar a este paquete deben tener el nombre del paquete mismo. Posteriormente se introduce el código fuente a utilizar, puedes navegar por este archivo también. A continuación, escribe un nombre para el archivo de salida. (No olvides la extensión xml!) Y pulsa Aceptar.
Line 63: Line 63:
  
 
Puedes usar [[FPDoc Updater]] para actualizar fácilmente los archivos FPDoc cuando las unidades Pascal han cambiado.
 
Puedes usar [[FPDoc Updater]] para actualizar fácilmente los archivos FPDoc cuando las unidades Pascal han cambiado.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
There are of 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 to a flying start. Just go to File -> New and the following screen will appear:
 
<center>[[Image:Lazdenewdocfromfile.png]]</center>
 
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 from your source file. Now you are ready to start documenting a new part of Lazarus.
 
 
Have a look at [[LCL Documentation Roadmap]] to see which units still need to be documented.
 
 
You can use [[FPDoc Updater]] to easily update FPDoc files when Pascal units have been changed.
 
  
 
== The Final result ==
 
== The Final result ==

Revision as of 11:10, 9 August 2010

Deutsch (de) English (en) español (es) français (fr) 日本語 (ja) polski (pl) русский (ru) slovenčina (sk)

Introducción

Una parte importante de Lazarus que aún falta es la documentación. Para ayudar en la elaboración de esta documentación se ha desarrollado una herramienta. Esta página describirá el funcionamiento de esta herramienta. Para indicar el directorio base de Lazarus en este documento utilizo [$LazDir]. Así, cuando lea esto, cámbielo por el directorio de instalación de Lazarus.

El camino

El primer objetivo de este proyecto es hacer un archivo de ayuda en línea. Para ayudar a hacer la plataforma de archivos independientes, se han empezado a crear los archivos XML para cada unidad que se utiliza en Lazarus. Hasta ahora, sólo se han iniciado dialogs.pp y buttons.pp.

Estos archivos XML se utilizan para crear páginas HTML a las que se puede acceder a través de la Internet en http://lazarus-ccr.sourceforge.net/docs/lcl/. Luego, en una fase posterior, se desarrollará una ayuda integrada, de nuevo con estos mismos archivos XML.

El inicio

Como se mencionó antes, para mantener la plataforma de documentación independiente se utiliza XML. La documentación actual se puede encontrar en [$LazDir]/docs/xml/. Hasta el momento, en su mayoría, son el esqueleto de ficheros en el directorio lcl. Los archivos XML que se encuentra en este directorio son auto-generados y necesitan ser adaptados para ser utilizables. Ahora que sabemos dónde encontrar los archivos, permite a la herramienta crearlos/adaptarlos.

La Herramienta

"Lazde" es una herramienta para editar los archivos xml, pero también puede ser usada para generar ficheros básicos desde archivos de origen y, por medio de una herramienta externa, generar una versión HTML de la documentación. Se puede ver un ejemplo de los resultados de la herramienta, con una parte de la documentación hasta la fecha aquí. Como no existe una versión compilada de "Lazde", tienes que hacerlo tú mismo. Las fuentes de "Lazde" se puede encontrar en [$LazDir]/doceditor/. Cuando se ejecuta el programa, si abre [$LazDir]/docs/xml/LCL/dialogs.xml se le presentará esta pantalla

Lazdemain.png

El Trabajo

Lazdeelements.png

Al abrir el nodo "Packages" se verá el nodo "LCL", que contiene el nodo "Dialogs". Al seleccionar este último nodo se llenará el panel inferior con elementos. Estos elementos representan constantes, tipos y clases que se definen en la unidad Dialogs.pp. las unidades añadidas se mostraran como nodos. Se agregarán otros nodos para las propiedades de una clase, los parámetros de una función y así sucesivamente.

Seleccionando un nodo en el panel inferior izquierdo hará que se muestre el contenido en la parte derecha de la pantalla.

Si miras en esta página podrás ver un resumen de las clases definidas en la unidad "dialogs". Después de cada clase se ve una línea de texto. Este texto aparece en el cuadro de edición "short" de "Lazde".

A continuación del cuadro de edición "short", hay un editor donde puede introducir una descripción detallada del componente o la propiedad.

Nota: si deseas insertar un salto de línea usa <br/>

Lo siguiente son "Errors", "See also" and "Example code File".

"Errors" se puede utilizar para mostrar los errores generados por una función si los parámetros tienen valores que están fuera de rango. Para ver un ejemplo mira esta página.

Justo encima de "See also" y "Example code File" aparecen tres botones. Estos botones te permiten agregar y quitar vínculos a otras páginas o ejemplos de código, respectivamente.

El documento final

Echa un vistazo a la descripción de InputQuery. En la parte superior de la página vemos el "acerca de", en este caso de la función InputQuery de dialogs.pp. La primera línea de texto es lo que está escrita en el cuadro de edición "short" de "Lazde".

Lo siguiente es la declaración de esta función en los ficheros fuente. La parte de declaración es creada por el constructor de HTML y se toma de los ficheros fuente. Debido a que hay dos versiones de esta función, el fichero fuente se posiciona en el 0.

A continuación se dan los argumentos. Al abrir el nodo InputQuery en "Lazde", podrás ver todos los argumentos mencionados como nodos secundarios. El texto que figura después de los argumentos es lo que se ha escrito en el cuadro de edición "short" cuando los respectivos nodos secundarios son seleccionados.

El cuarto párrafo muestra el resultado de la función. Este texto se ha introducido de la misma forma que los argumentos.

Por último, se muestra la descripción. Este es el texto introducido en la caja "description" de "Lazde".

La adición de nuevas unidades

Por supuesto, hay otras unidades que han de estar documentadas. Si es, por ejemplo, una unidad de algún paquete, es probable que no hay ningún archivo xml para empezar. Tienes entonces que empezar desde cero, pero "Lazde" tiene una función para hacerle frente al comienzo. Sólo tienes que ir a Archivo -> Nuevo y aparecerá la siguiente pantalla:

Lazdenewdocfromfile.png

Se comienza dando un nombre al paquete. Todas las unidades que desees agregar a este paquete deben tener el nombre del paquete mismo. Posteriormente se introduce el código fuente a utilizar, puedes navegar por este archivo también. A continuación, escribe un nombre para el archivo de salida. (No olvides la extensión xml!) Y pulsa Aceptar.

"Lazde" entonces genera la base para la documentación. El archivo generado se abrirá en la vista de árbol y se llenará con todas las unidades, clases, tipos, funciones y así sucesivamente, desde el archivo de código fuente. Ahora estás listo para empezar a documentar una nueva parte de Lazarus.

Echa un vistazo a LCL Documentación Hoja de ruta para ver qué unidades aún han de estar documentados.

Puedes usar FPDoc Updater para actualizar fácilmente los archivos FPDoc cuando las unidades Pascal han cambiado.

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

"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

Lazdebuild2.png

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.

The Submission

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

A small note

Note the following: The lazde is work in progress. It is workable, but not completely finished yet. So there can be some bugs in it, but feel free to fix them.