Difference between revisions of "Lazarus Documentation Editor/fr"

From Free Pascal wiki
Jump to navigationJump to search
Line 63: Line 63:
 
Aller voir la [[LCL Documentation Roadmap|Feuille de route de documentation LCL]] pour voir quelles unités  ont toujours besoin d'être documentées .
 
Aller voir la [[LCL Documentation Roadmap|Feuille de route de documentation LCL]] pour voir quelles unités  ont toujours besoin d'être documentées .
  
== The Final result ==
+
== Le résultat final  ==
  
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.
+
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 .
  
This utility can be started from the menu Extra -> Build. The following screen will be shown:
+
Cet utilitaire peut être démarré à partir du menu Extra -> Build. L'écran suivant sera montré :
 
<center>[[Image:Lazdebuild1.png]]</center>
 
<center>[[Image:Lazdebuild1.png]]</center>
"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.
+
"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 .
Press "Add all" and all documents your were working on will be added to the project. Then go to the next to tab
+
Appuyer sur "Add all" et tous les documents sur lesquels vous travailliez seront ajoutés au projet . Then go to the next to tab
 
<center>[[Image:Lazdebuild2.png]]</center>
 
<center>[[Image:Lazdebuild2.png]]</center>
 
and enter the paths to the source files.
 
and enter the paths to the source files.

Revision as of 12:19, 25 June 2007

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

Lazdemain.png

Le travail

Lazdeelements.png

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 .

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.

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 :

Lazdenewdocfromfile.png

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é :

Lazdebuild1.png

"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 . 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.