Difference between revisions of "Lazarus Documentation Editor/fr"

From Free Pascal wiki
Jump to navigationJump to search
 
(13 intermediate revisions by one other user not shown)
Line 30: Line 30:
 
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.
 
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 [http://lazarus-ccr.sourceforge.net/docs/lcl/dialogs/index-4.html 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 "petit" éditeur de lazde.
+
Quand vous regardez sur [http://lazarus-ccr.sourceforge.net/docs/lcl/dialogs/index-4.html 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 "petite",il y a un champ memo(memofield) où vous pouvez entrer une description plus raffinée du composant ou de la propriété .
+
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  <nowiki><br/></nowiki>
 
  Note: Si vous voulez insérer une retour à la ligne utilisez  <nowiki><br/></nowiki>
  
Vient ensuite le memofields "Errors", "See also" et "Example code File".
+
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  [http://lazarus-ccr.sourceforge.net/docs/rtl/dateutils/recodeyear.html cette page ].
 
"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  [http://lazarus-ccr.sourceforge.net/docs/rtl/dateutils/recodeyear.html 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.
+
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.
  
== The Outcome ==
+
== Les résultats  ==
Have a look at the description of [http://lazarus-ccr.sourceforge.net/docs/lcl/dialogs/inputquery.html InputQuery].
+
Aller voir la description de [http://lazarus-ccr.sourceforge.net/docs/lcl/dialogs/inputquery.html 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.
+
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.  
 
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.  
Line 53: Line 53:
 
Finally the description is shown. This is the text entered in the description box of lazde.
 
Finally the description is shown. This is the text entered in the description box of lazde.
  
== The addition of new units ==
+
== L'addition de nouvelles unités  ==
  
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:
+
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 :
 
<center>[[Image:Lazdenewdocfromfile.png]]</center>
 
<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.
+
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 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.
+
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.
  
Have a look at [[LCL Documentation Roadmap]] to see which units still need to be documented.
+
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 . Aller alors au prochain onglet
 
<center>[[Image:Lazdebuild2.png]]</center>
 
<center>[[Image:Lazdebuild2.png]]</center>
and enter the paths to the source files.
+
et entrer les chemins vers les fichiers sources.  
After you have pressed build your HD will start to rattle and finally the following output will be shown on the "Build output" tab.
+
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"
 
  Building docs using command: fpdoc --package="LCL"
 
  --output="/home/matthijs/documentatie/LCL" --format=html --content  
 
  --output="/home/matthijs/documentatie/LCL" --format=html --content  
Line 92: Line 92:
 
  Documentation successfully built.
 
  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.
+
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.
  
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.
+
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.
  
== The Submission ==
+
== La soumission  ==
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 [[Creating A Patch|patch]], zip this and send it in.
+
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 [[Creating A Patch/fr|patch]], zippez le et envoyer le dedans .
  
== A small note ==
+
== Une petite 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.
+
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.

Latest revision as of 21:12, 21 April 2010

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 .

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 :

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 . Aller alors au prochain onglet

Lazdebuild2.png

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.