Lazarus Documentation Editor/fr

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

Introduction

Une partie importante de Lazarus manquant toujours est la documentation. Pour faciliter la fabrication de cette documentation un outil a été développé . Cette page décrira le fonctionnement de cet outil . Pour indiquer le répertoire de base de Lazarus dans ce document j'emploie [$LazDir]. Ainsi quand vous avez lu ceci remplacer ceci avec le répertoire dans lequel Lazarus est installé.

Le pourquoi

Le premier but de ce projet est de rendre disponible un fichier d'aide en ligne. Pour rendre le fichier d'aide indépendant de la plate-forme nous avons commencé à créer des fichiers XML pour chaque unité utilisée dans Lazarus. Jusqu'ici seulement dialogs.pp et buttons.pp ont été commencés .

ces fichiers XML ont ensuite été utilisé pour créer des pages HTML ce qui peut être accédé par Internet à l'adresse http://lazarus-ccr.sourceforge.net/docs/lcl/. Puis ultérieurement une aide intégrée sera développée à nouveau utilisant ces mêmes fichiers XML.

Le début

Comme mentionné avant , pour garder la documentation indépendante de la plate-forme, le XML est employé . La documentation courante peut être trouvé dans [$LazDir]/docs/xml/. Jusqu'ici il y a la plupart du temps des fichiers squelettes dans le répertoire lcl. Les fichiers XML que vous trouvez dans ce répertoire sont auto-produits et doivent être adapté pour être utilisable. Aussi maintenant que nous savons où trouver les fichiers, Jetons un coup d'oeil à l'outil pour les créer/modifier.

L'outil

"lazde" est un outil pour éditer les fichiers xml, mais peut également être employé pour générer les fichiers de base à partir des fichiers sources et à l'aide d'un outil externe de générer une version HTML de la documentation . Un exemple des résultats du dernier outil peut être vu ici,avec jusqu'ici une partie de la documentation. Comme il n'y a aucune version compilée de lazde, vous devez en faire une vous-même. Les sources pour "lazde" peut être trouvé dans [$LazDir]/doceditor/. Quand vous exécutez ce programme et vous avez ouvert [$LazDir]/docs/xml/lcl/dialogs.xml vous serez assités par cet écran

Le travail

L'ouverture du noeud "Packages" montrera le noeud "LCL" qui contient un noeud "Dialogs". La sélection du dernier noeud remplira l'arborescence inférieure avec des éléments. Ces éléments dépeignent des constantes , des Types et des Classes définis dans l'unité Dialogs.pp. Les unités utilisées sont ajoutées comme les noeuds. D'autres noeuds sont ajoutés pour les propriétés de classes, les paramètres pour une fonction et ainsi de suite .

Le choix d'un noeud dans l'arborescence inférieure gauche rendra le contenu de ce noeud affiché sur le coté droit de la fenêtre.

Quand vous regardez sur cette page vous verrez une vue d'ensemble des classes définies dans l'unité "dialogs". Après chaque classe vous voyez une ligne de texte . Ce texte vient du l'éditeur "short" de lazde.

Au-dessous de la boite d'édition "short",il y a un champ memo(memofield) où vous pouvez entrer une description plus raffinée du composant ou de la propriété .

Note: Si vous voulez insérer une retour à la ligne utilisez  <br/>

Vient ensuite les memofields "Errors", "See also" et "Example code File".

"Errors" peut être employé pour discuter au sujet des erreurs soulevées par une fonction si les paramètres ont des valeurs qui sont hors intervalle . Pour un exemple voir cette page .

Juste au dessus de "See also" et "Example code File" vous voyez trois boutons . Ces boutons vous permettent d'ajouter et enlever des liens à d'autres pages ou exemples de codes respectivement.

Les résultats

Aller voir la description de InputQuery. Sur le dessus de la page nous voyons que la page est a propos, 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.

L'addition de nouvelles unités

Il y a naturellement d'autres unités qui doivent être documentées. Si c'est par exemple une unité pour quelque paquet , le hazard est qu'il n'y a aucun fichier xml avec lequel commencer. Vous devez commencer à partir de zéro alors, mais lazde a une fonction pour vous descendre à un début de vol . Aller juste à File -> New et l'écran suivant apparaîtra :

Vous commencez en donnant un nom au paquet. Toutes les unités que vous voulez ajouter à ce paquetdevrait avoir le même nom de paquet. Après vous entrez le fichier source que vous utilisez ; vous pouvez naviguer vers ce fichier aussi. Écrire alors un nom pour le fichier de sortie. (Ne pas oublier l'extension xml !) Et pressez OK.

lazde génèrera alors les fondations pour la documentation . Le fichier produit sera ouvert et l'arborescence sera peuplé par toutes les unités , les classes, les types, les functions et ainsi de suite à partir de votre fichier source . Maintenant vous êtes prêt à commencer à documenter une nouvelle partie de Lazarus.

Aller voir la Feuille de route de documentation LCL pour voir quelles unités ont toujours besoin d'être documentées .

Le résultat final

Ce que j'ai éprouvé pendant l'utilisation du programme est que je voudrais voir comment l'information est montrée à son étape finale (comme document explorable ). À cette fin lazde se sert d'un utilitaire pour construire tous les fichiers HTML nécessaires .

Cet utilitaire peut être démarré à partir du menu Extra -> Build. L'écran suivant sera montré :

"Package" devraient être le même que le nom que vous avez donné quand vous avez créé les fichiers xml . Pour "Format" choisir HTML. Pour "Output" vous entrez le chemin où les fichiers résultants devraient être placés . Appuyer sur "Add all" et tous les documents sur lesquels vous travailliez seront ajoutés au projet . Aller alors au prochain onglet

et entrer les chemins vers les fichiers sources. Après avoir pressé sur le bouton build votre disque dur(HD) commencera à cliqueter et finalement la sortie suivante sera montré sur l'onglet "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.

Quand vous allez au répertoire que vous avez entrés à l'onglet "Output", vous verrez un fichier index.html et (dans ce cas 4) des sous-répertoires . Ouvrir index.html dans votre navigateur favori et voir le résultat de tout votre dur travailsur la documentation . Vous pourrez suivre les liens et le lire complètement.

Quand vous projetez de continuer à travailler sur ce paquet de la documentation , appuyez sur "Save" et enregistrer les options de construction. Vous serez invités à fournir un nom pour le fichier et les options seront enregistrées. La prochaine fois que vous voulez construire les fichiers HTML vous pouvez juste les "télécharger" à nouveau.

La soumission

Quand vous êtes satisfaits avec votre travail vous voulez certainement le partager avec la communauté de Lazarus. Tous que vous devez faire est de réaliser un patch, zippez le et envoyer le dedans .

Une petite note

Noter ce qui suit : lazde est un travail en cours. On peut le faire fonctionner, mais il n'est pas complètement fini. Donc il peut y avoir quelques buggs, mais vous êtes libre de les corriger.