Index: trunk/SRC/ToBeReviewed/PLOTS/DIVERS/placedessin.pro
===================================================================
--- trunk/SRC/ToBeReviewed/PLOTS/DIVERS/placedessin.pro	(revision 134)
+++ trunk/SRC/ToBeReviewed/PLOTS/DIVERS/placedessin.pro	(revision 142)
@@ -3,43 +3,124 @@
 ;------------------------------------------------------------
 ;+
-; NAME:placedessin
-;
-; PURPOSE: mise en place du dessin / ouverture de la fenetre ou du PS
-;
-; CATEGORY: pour alleger les programmes plt, pltz, pltt.
-;
-; CALLING SEQUENCE: placedessin, typedessin,posfenetre, posbar
-;
-; INPUTS:
-;   typedessin: une chaine de charactere specifiant quelle procedure
-;   appelle placedessin: 'plt', 'pltz', 'pltt'
-;
-; KEYWORD PARAMETERS: pleins (ce de CALIBRE de WINDOW ...)
-;
-;       LCT: intier designant le numero de la palette de couleur que
-;       l''on veut utiliser pour les plot. 
+;
+; @file_comments 
+; Putting into place of the drawing/ opening of the window or of the PS
+;
+; @categories 
+; Utilities
+;
+; @param TYPEDESSIN
+; It is a chain or characteres specifying what procedure is called by PLACEDESSIN: 'plt', 'pltz' or 'pltt'
+;
+; @keyword LANDSCAPE 
+; Force the page or the window on the screen to be in lenthened position.
+;
+; @keyword LCT 
+; Is an integer designating the number of the palette of color we want to use for the plot. 
 ;	
-; OUTPUTS:
-;
-;       posfenetre: un vecteur de 4 elements contenant la position de
-;       cadre contenant les legendes + le graphe en coordonnes
-;       normalises. Rq: pour positionner le dessin il faut apres
-;       l''appelle de calibre faire !p.position=posfenetre
-;
-;       posbar: cf posfentre mais pour la barre de couleur. meme
-;       remarque pour positionner la barre de couleur, !p.position=posbar
-;
-;
-; COMMON BLOCKS:
-;	common.pro
-;
-; SIDE EFFECTS:
-;
-; RESTRICTIONS:
-;
-; EXAMPLE:
-;
-; MODIFICATION HISTORY: Sebastien Masson (smasson@lodyc.jussieu.fr)
+; @keyword MAP 
+; We use it when we want to do a projection.
+; This keyword can be of two types:
+;     MAP=[P0lat,P0lon,Rot]. For the descrption of these 3 values (see the online help of MAP_SET).
+;     /MAP: In this case, map is automatically caculated have the value: 
+;          map = [0, (lon1+lon2)/2., 0]
+; Comment: A good way to choose the type of the projection we want to do is to have a look at IDL demo:
+; IDL> demo
+; Then choose earth sciences and  mapping.
+; Comment2: By default it  is a cindrical projection which is effectuated (with or without the keyword map). 
+; If we want an other projection, MAP must be activated and we have to add the keyword: /nom_projection.
+; For example, for a polar projection centered on the south pole:
+; IDL> domdef,-180,180,-90,-45
+; IDL> plt, tab, /stereo,map=[-90,0,0]
+;	
+; @keyword NOCOLORBAR 
+; We active it if we do not want the colorbar.
+
+;; @keyword NOFILL 
+; We active it if we only want contours in black and white with a white background.
+;
+; @keyword NOERASE 
+; We active it to make a drawing without creating a new frame.
+;
+; @keyword SMALL 
+; Vector composed of 3 or 4 elements, applyed to make a drawing on a 
+; small portion of a page or screen. It delimit the zone where the drawing will be done.
+;     If there is 4 elements:
+; then is constituated of coordinates (expressed in cm located from the up and 
+; left corner of the page or the window (in portrait like in lanscape)) of the bottom 
+; and left corner and of the up and right corner of the drawing zone.
+;     If there is 3 elements:
+; in this case, we divide the page or the screen in small[0] columns and in small[1] lines 
+; the drawing made in the box numbered small[2]. The numerotation starting up and left by 
+; the number 1 and then, following the writing direction.
+; By default, we make the largest drawing we can do, conserving the aspect rapport 
+; (exept when REMPLI is activated).
+; 
+; @keyword PORTRAIT 
+; Force the page or the window to be in standing position.
+;
+; @keyword POST 
+; Make a postscript. Only works if we made one drawing on the page.
+; If we make several drawing, use \@ps.
+;
+; @keyword REMPLI 
+; Force the drawing to occupy the whole space defined by small.
+;
+; @keyword WINDOW
+; Number of the window on which we want to do the graph (Allow to open several windows). 
+; By default, we open 'IDL0'
+;
+; @keyword CB_TITLE 
+; The colorbar's title
+;
+; @keyword CONTOUR 
+; If we want to trace contours of a different field than the one 
+; whose we have the colored drawing (by examlpe E-P in color and QSR in contours). 
+; It must be a field respecting same caracteristics than the argument number one of plt.
+;
+; @keyword ENDPOINTS 
+; keyword specifing that we want to make a vertical cut in diagonal. Then coorinated of extremities 
+; of these one are difined by the 4 elements of the vector ENDPOINTS: [x1,y1,x2,y2] which are 
+; coordinates. 
+;
+; @keyword VECTEUR
+; It is a structure composed by 2 elements containing the 2 fields U
+; and V of values of the zonal and meridian component of the vector of the fields
+; to draw. These fields can be an array or a structure.
+;       For example: vecteur={matriceu:lec('unsurface'),matricev:lec('vnsurface')}
+;       Comment: name of elements of vectors are inconsenquential.
+;       vecteur={u:lec('unsurface'),v:lec('vnsurface')} is also appropriated.
+;
+; @keyword DIREC
+; 't' 'x' 'y' 'z' 'xys' 'xz' 'yz' 'xyz' 'xt' 'yt' 'zt' 'xyt'
+;       'xzt' 'yzt' 'xyzt' Direction on which do averages 
+;
+; @keyword _EXTRA
+; Used to pass your keywords.
+;
+; @keyword COLOR_C 
+; To draw the contour in color instead of in black
+; with filling in color 
+;
+; @param POSFENETRE {out}
+; It is a vector composed by 4 elements containing the position of the frame 
+; containing captions and the graph in normalized coorinates. 
+; Comment: To position the drawing; we have to do !p.position=posfenetre 
+; after the call of the caliber
+;
+; @param POSBAR {out}
+; Like POSFENETRE but for the color bar. 
+; Same comment to position the color bar, !p.position=posbar
+;
+; @uses
+; common.pro
+;
+; @history
+; Sebastien Masson (smasson@lodyc.jussieu.fr)
 ;                       26/4/1999
+;
+; @version
+; $Id$
+;
 ;-
 ;------------------------------------------------------------
@@ -65,8 +146,8 @@
   ENDIF
 ;-------------------------------------------------------------
-; 1) determination de la taille des marges (unite=nbre de lignes ou colonnes)
-; a gauche, a droite, en bas, en haut
-; ATTENTION ds margebar le dernier element est le coint en haut a droite au
-; lieu de la marge en haut
+; 1) Determination of the size of margins (unity=number of lines or columns)
+; to the left, to the right, up and down.
+; BEWARE in margebar, the last element is the right up corner 
+; instead of the up margin
 ;-------------------------------------------------------------
   if n_elements(typedessin) EQ 0 then typedessin = 'autre'
@@ -103,5 +184,5 @@
   ENDELSE
 ;--------------------------------------------------------------
-; portrair ou landscape
+; Portrait or landscape
 ;--------------------------------------------------------------
   IF NOT keyword_set(noerase) THEN BEGIN 
@@ -113,5 +194,5 @@
   ENDIF 
 ;--------------------------------------------------------------
-; Quel type de rapport d''aspect (sera ecrase si YXASPECT existe)
+; What type of aspect rapport (it will be crushed if YXASPECT exist)
 ;--------------------------------------------------------------
   case typedessin of
@@ -122,6 +203,6 @@
   endcase
 ;-------------------------------------------------------------
-; 2) calcul de !p.position
-; cf calibre.pro.
+; 2) calculation of !p.position
+; see calibre.pro.
 ;------------------------------------------------------------
 ;
@@ -134,27 +215,27 @@
   !p.position = posfenetre
 ;------------------------------------------------------------
-; 3) ouverture de la fenetre graphique ou du postscript
+; 3) opening of the graphic window or of the postscript
 ;------------------------------------------------------------
   case 1 of
-; cas du premier dessin sur un postcript
+; case of the first drawing on a postcript
     keyword_set(post) AND !d.name ne 'PS':openps, _extra = ex
-; cas du premier dessin sur un ecran
+; case of the first drawing on a screen
     keyword_set(post) EQ 0 AND keyword_set(noerase) EQ 0 $
       AND !d.name ne 'PS' AND !d.name ne 'Z':BEGIN
       if not keyword_set(window) then window = 0
-; pour l''utilisation de @ps, @oups et de @vzoom
-      if lmgr(/demo) EQ 0 then BEGIN ; on est en mode demo??
-        if !journal NE 0 then journal ; on ferme le journal s''il est ouvert
+; For the using of \@ps,\@oups et de \@vzoom
+      if lmgr(/demo) EQ 0 then BEGIN ; Are we in the demo mode??
+        if !journal NE 0 then journal ; We close te journal if it is open
         homedir = isadirectory(io = homedir, title = 'Bad definition of homedir')
         def_myuniquetmpdir
-        journal, myuniquetmpdir+'idlsave.pro' ; on en ouvre un nouveau
-        help, /recall_commands, output = listecommande ; on recupere la derniere commande
+        journal, myuniquetmpdir+'idlsave.pro' ; We open a new one
+        help, /recall_commands, output = listecommande ; We recuperate the last command
         listecommande = strmid(strcompress(listecommande[1]), 2)
-        journal, listecommande ; on l''ecrit dans le journal
+        journal, listecommande ; We write it in the journal
       ENDIF
       windsize = givewindowsize()
       window, window, xsize = windsize[0], ysize = windsize[1],  retain = 2, _extra = ex
-; qd on utilise des couleurs codees sur 24 bit, je n''arrive pas a stipuler la couleur du
-; fond d''une fenetre a l'aide de !p.background, je suis oblige de faire cette bidouille!!!
+; When we used colors which are coded on 24bit, we can not stipulate the background color 
+; of a window thanks to !p.background, so we have to to this:
 ;          if !d.n_colors gt 256 then begin
 ;             device, decomposed=1
