Lazarus Documentation Editor/es

│ 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 leas esto, cámbialo 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, veamos la herramienta para 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 abres [$LazDir]/docs/xml/LCL/dialogs.xml, se te presentará esta pantalla

El Trabajo

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 nuevos 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 puedes 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 haya 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:

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 para localizar este archivo. A continuación, escribe un nombre para el archivo de salida. (No olvides la extensión xml!) Y pulsa Aceptar.

"Lazde" generará entonces el documento 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 han de estar documentadas.

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

El resultado final

Lo que me gustaría ver, cuando uso el programa, es cómo se muestra la información en su etapa final (en formato navegable). Para ello, "Lazde" hace uso de una utilidad para crear todos los archivos HTML necesarios.

Esta utilidad se puede llamar desde el menú Extra -> Build. Se nos mostrará la siguiente pantalla

"Package" debe ser el mismo nombre que le diste al crear los archivos xml. Para "Format", selecciona HTML. En "Output" introduce la ruta donde colocar los archivos resultantes. Pulsa el botón "Add all" y todos los documentos con los que estabas trabajando se agregarán al proyecto. A continuación, pasa a la siguiente pestaña

e introduce los ficheros fuente con su directorio.

Después de pulsar construir, tu disco duro comenzará a girar y, al finalizar, se mostrará el siguiente resultado en la pestaña "Build output".

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.

Cuando vayas al directorio que has puesto en "Output", verás un archivo index.html y (en este caso 4) subdirectorios. Abre index.html en tu navegador favorito y mira el resultado de tu arduo trabajo con la documentación. Deberías ser capaz de seguir los enlaces y leerlo todo

Si vas a seguir trabajando en este paquete de documentación, pulsa "Save" y guarda las opciones de creación. Se te pedirá que proporciones un nombre para el archivo y se guardarán las opciones. La próxima vez que quieras construir el HTML, sólo debes llamar a "load" de nuevo.

La Presentación

Cuando estés satisfecho con tu trabajo, sin duda querrás compartirlo con la comunidad de Lazarus. Todo lo que tienes que hacer es |patch, comprimirlo y enviárnoslo.

Una pequeña nota

Ten en cuenta lo siguiente: "Lazde" es un trabajo en desarrollo. Es usable, pero no está terminado del todo todavía. Así que puede tener algunos errores, pero, si puedes, no dudes en solucionarlos.