********************************************************************************
   P A P C O  - panel plot composer - main help window
********************************************************************************


********************************************************************************
GENERAL
********************************************************************************
   The Panelplot-composer is a window in which you can compose multiple plots
   of various data in a comfortable way. All plots handled by this program 
   consist of data plotted over time.

   - You may add up to 10 plots to the list of plots. 
   - You can change the characteristics of the chosen plots.
   - Height and position of the plots can be changed by using your mouse, and
     while changing height and position, a preview of the plots' positions is 
     displayed.
   - You can change the time-range by using the time-sliders.
   - You can output the chosen plots to the display, a printer or a file.
   - When you have output the chosen plots to the display, you may use your
     mouse to zoom into the plots or to draw detailed plots (slices) of 
     certain areas of your plots.
   - You can save the currently selected plot-configuration to a file and load
     it again later. 
   
   Currently, modules for the following data types are avaiable:
	CRRES 	 
           MEB
	   MEA	 
	   LEPA	
           DEPLO (CRRES level zero) 
           Magnetometer
           MICS
	OMNI	 
	STEP 6.4 
        EVENTS
        Los Alamos Geostationary Energetic particles
        AE index
        WIND
           SWE KP
           SWE
        IMP8 KP
        POLAR
          HYDRA
          HYDRA level zero
          CEPPAD
          CEPPAD level zero
           
   To plot, PAPCO needs those informations:
   - a time-range information.
     This may be the number of an orbit or it may be a manually entered
     time-range.
     Some plots depend on knowing the orbit (MEB, LEPA, MEA), and some don't
     (OMNI, STEP). If you enter a time-range manually, you may additionally add
     an orbit.

********************************************************************************
THE WINDOW - COMPONENTS
********************************************************************************

   On the left side of the window are widgets which control the plot-data.
   On the right side of the window is the big drawing area and under this 
   situated are buttons for output of your data and file-handling.
 
 the left side of the window 
 -------------------------------------------------------------------------------
   The first button stops PAPCO and allows you to recompile one of its
   components or your plot/read routine before continuing with .con
   The other buttons in the top left of the window are for all the modules
   that you have configured PAPCO for in idl_startup_papco.pro

   They are buttons or pulldown menus that you have to use to add plots to your 
   list of plots.
   -----> see THE LIST OF PLOTS

   Under those buttons, you see two sliders. They control the time-range that
   will be plotted. You can not use these sliders until you have selected an
   orbit or a manual time-range or time by day.
   -----> see CHOOSING A TIME RANGE

   Under those sliders buttons, you can see two frames and a button.
   The left frame contains either fields for selecting an orbit, fields
   for manually selecting a time range or a field for specifying a whole day.
   What the left frame displays is controlled by the second frame - if you
   click the 'select time by orbit'-button, you can select an orbit, and
   if you click the 'select time manually'-button, you can manually enter 
   a time-range, if you click 'select time by day' you can enter one whole day.
   -----> see SELECTING ORBITS
   -----> see MANUALLY CHOOSING A TIME RANGE

   To the right of these frames, you see a graphics button labeled 'batch'.
   You can use this button to add the currently selected time-range to the 
   file 'interactive.papco_batch'
   -----> see BATCH-PROCESSING   

   Under those frames, you can see a mouse Action button. It hides a submenu
   which allows you to choose a mouse action; the current action is
   displayed to the right.
   Use those buttons to control the behaviour of the mouse-cursor in the
   drawing-area.
   -----> see ZOOMING AND MOUSE ACTION

   Under the Mouse section two button control the appearance for the FINAL
   output when you send a plot to a postscrip printer. On the screen, only
   portrait is possible.

   And unter those you see a list-box with some buttons to its right and a
   colored area to its left. 
   -----> see THE LIST BOX 
   

 the window's right side
 -------------------------------------------------------------------------------
   The right side consists mainly of a big drawing-area. 
   After you have drawn your plots, you may use the mouse for zooming 
   or slicing your data.
   -----> see ZOOMING AND MOUSE ACTION

   Under that drawing-area are some buttons:
	Draw    Print    Help    Load    Save    Reset   Done
   -----> see THE ACTION-BUTTONS


********************************************************************************
THE LIST OF PLOTS
********************************************************************************

ADDING PLOTS
--------------------------------------------------------------------------------
   Press one of the buttons in the top of the left window-side. A
   pulldown-menu will appear. After you choose the desired plot, a
   dialog-window will open in wich you can specify further information.

   All dialog-windows have a button called 'Add xxx-Plot'. When you press it,
   the new plot is added to the list of plots.


THE CONTENTS OF THE LIST-BOX
--------------------------------------------------------------------------------
   The list-box contains all plots you have added. If there are no plots, it 
   contains the text 'No plots selected'.

   Each plot's description consists of two rows. The first line contains the
   plot's number and a general description. 

   The second row shows the plot's panel-vector, y-scaling-information and
   further details on your plot.

   Left of the list-box you see a graphics area. For each plot, here are some
   colored bars displayed. Those provide a graphic preview of your plots
   (explained further down the text)

   --- the panel-vector --------------------------------------------------------
   The panel-vector is used to determine position and height of a
   plot. It consists of three integer numbers which are displayed in
   square brackets:

	  [position, totalHeight, thisHeight]
   
   position	   is the position of this plot-panel
		   the bottom-most panel-position is zero
		   the top-most panel-position is the second panel-vector
		   number, 'totalHeight'. 		   

   totalHeight     determines the total height of all panels		 
		   The draw-area is divided in 'totalHeight' rows of equal
		   height. Each of these rows is a position that may be used
		   as first component of the panel-vector.
		   This value, totalHeight, is calculated from the positions
		   and 'thisHeight'-values of all plots chosen.

   thisHeight      relative height of this panel
	           Each panel occupies the positions from 'position' up to
		   'position+thisHeight-1'.
		   Panels may overlap !


   e.g.: When you want have one plot only, then panelVector=[0,1,1]
         This is equivalent to			panelVector=[0,2,2]

         If you have two plots, that both have the same height, 
	 panelVector1=[0,2,1]	  <=>  panelVector1=[0,10,5]
	 panelVector2=[1,2,1]     <=>  panelVector2=[0,10,5]

         If you have three plots, where the first plot is twice as high as the
         second plot, and where the third plot is plotted over the first two
         plots:
            panelVector1=[0,3,2]
	    panelVector2=[2,3,1]
	    panelVector3=[0,3,3]


   --- the graphics plot-preview -----------------------------------------------

   The preview is to the left of the list-box. For each plot, you can see a
   horizontal color-bar.

   Those color-bars resemble the panel-vectors of the plots (if you rotate the
   area containing the color-bars 90 degrees anti-clockwise, they are really a
   preview of your later plot).

   You can use this preview to see quickly, if some of your plots will
   overlap, and to get a feeling for their proportions.

   To get a feeling for this preview, experiment with the sizing-buttons
   (-----> see EDITING PLOT-SIZES in this section)


   --- y-scaling information  --------------------------------------------------
   The editor for each plot contains widgets for specifying y-scaling 
   information. This name is not really exact, because the y-scaling information
   is not a factor but the range of the plotted ordinate-axis for one plot.

   A more comfortable way of defining the y-range of a plot is by
   plotting it with auto-y-scale and then selecting a range of the
   plot using your mouse. (-----> See ZOOMING AND MOUSE ACTION)

   The y-scaling information is displayed in the list of plots. If
   'auto-yscale' is displayed, the ordinate axis of that plot will be
   chosen automatically.  If you've given a certain range of the axis
   as y-scale, the display reads like this: 'y-scl:(lower-bound, upper-bound)'


EDITING PLOT-SIZES AND POSITIONS
--------------------------------------------------------------------------------
   To change height and position of a plot, first select its description in
   the list-box with your mouse - one of its lines of description must be
   highlighted by a black bar.

   Then, use the four buttons that are to the right of the list-box (those
   with the symbols on it). They have this meanings:

   1st button (Arrow-up-symbol)
	      use this button to move the plot one position upwards. 
	      Effectively, you increase the first element of the panel-vector.

   2nd button (Arrow-down-symbol)
	      use this button to move the plot one position down. 
	      Effectively, you decrease the first element of the panel-vector.

   3rd button (double arrow - arrows pointing outwards
	      use this button to enlarge the plot's height
	      Effectively, you increase the third element of the panel-vector.

   4th button (double arrow - arrows pointing inwards)
	      use this button to shrink the plot's height
	      Effectively, you decrease the third element of the panel-vector.

   Whenever you press one of those buttons, the panel-vecors change and the
   preview is updated.


EDITING A PLOT'S CHARACTERISTICS
--------------------------------------------------------------------------------
   To edit the characteristics of a plot, double click on its description in 
   the list-box.

   Or do this to edit a plot: first select its description in the list-box
   with your mouse - one of its lines of description must be highlighted by a
   black bar.
   Then, click the edit-button that's  right of the list-box.
      

CHANGING A PLOT'S TYPE
--------------------------------------------------------------------------------
   To change a plot's type, first select its description in the list-box with
   your mouse - one of its lines of description must be highlighted by a black
   bar.
   Then, click the 'edit' button that's  right of the list-box. This opens
   a submenu where you can choose to edit the plot, or change type to a
   completely different type. If you choose change type a window with all
   the current plot types and subtypes is displayed - click on the new plot
   type to open it's panel editor.


DELETING PLOTS
--------------------------------------------------------------------------------
   To delete a plot, first select its description in the list-box with your
   mouse - one of its lines of description must be highlighted by a black bar.

   Then, press the 'delete' button that's  right of the list-box.
   You will be asked, if you really want to delete that plot. Answer yes.


REFORMAT
--------------------------------------------------------------------------------
   If your panels get out of order ot you loose track of whats where you can
   use this button to automatically format the contents in the list box.
   'reformat' opens a submenu with three options - 'join' takes out any
   gaps between plots, 'reflow' goes back to all panels unit size, bottom
   one on top of list, and 'resort' puts the panles in order of actual position
   (bottom one at top of list).

********************************************************************************
TIME-RANGES
********************************************************************************
   I use the word 'time range' in two different contexts - first, there is the 
   time range that you select manually or by choosing an orbit.
   Second, there is the time-range that is used for the plotting.

   The first of those time-range only selects the minimum and maximum time of 
   the time-sliders. You can not use the sliders for selecting a plot-time-range
   until you entered a time-range manually or have choosen an orbit.

   After having done that, you can drag the sliders for choosing a time-range   
   for the plot.


********************************************************************************
SELECTING ORBITS
********************************************************************************
   You have to select an orbit, if you want to draw plots, that rely on knowing
   an orbit. (e.g.: If you draw a CRRES-plot without having entered an orbit, 
   an empty plot will be drawn in which an error-message is displayed).
   
   You may select an orbit, if you want to use its time-range.

   To select an orbit:
   First, make sure that the 'select time by orbit'-button is highlighted.

   If you already know its number, click in the orbit entry-field and type it
   in.  You should press enter afterwards ! This validates the orbit. If you
   don't press enter, you can plot using this orbit, but the orbit will not be
   validated until you choose to draw or to print. Furthermore, you won't be
   able to select a time-range until the orbit was validated.

   If you don't know its number yet, click the 'select orbit' button. Some
   seconds later, a window containing info on all known orbits will be shown.

   Selection by orbit currently is only supported for CRRES data.

********************************************************************************
MANUALLY CHOOSING A TIME RANGE
********************************************************************************
   To manually select a time-range:
   Make sure, that the button 'select time manually' is highlighted.

   Don't get confused with the time-fields! Enter the time-range information in
   the fields 'times from:' and 'to:" and not in the fields above the time-
   sliders. The fields 'times from:' and 'to:' are not shown until you highlight
   the 'select time manually'-button.
   
   Afterwards, enter the start-time and the end-time. Then press return (in one 
   of those entry-fields). If you press return, before both entry fields contain
   valid times, nothing will happen. 

   If you don't press return after entering both values, you can't use the time-
   sliders.

   Time-Format: In the 'times from:' and in the 'to:' field, you can enter the 
   		time in these formats:

      'day time'
      'day'

   The day may be entered using these formats:
      doy/yy		  e.g. 1/90
      doy/yyyy		  e.g. 2/1990
      dom.month.yy	  e.g. 1.3.91
      dom.month.yyyy	  e.g. 1.3.1991
      month/day/yy	  e.g. 3/1/91
      month/day/yyyy	  e.g. 3/1/1991

   The time can be entered using these formats:
      hh:mm:ss		  e.g. 12:20:1
      hh:mm		  e.g.  5:1

   You may omit the time. If you only enter the date, the time is assumed to 
   be midnight - 00:00:00.


********************************************************************************
SELECTING THE PLOT-TIME-RANGE USING THE TIME-SLIDERS
********************************************************************************
   You can't select a plot-time-range until you selected an orbit or until you 
   manually selected a time-range.

   To select a time-range, drag the 'start time' or the 'end-time' slider. The
   actual chosen range is displayed in the entry fields above the sliders. If
   you have already done a plot, the chosen range will be graphically
   displayed in the drawing area also.

   Another way of choosing a time-range is clicking in the time-range entry
   fields, entering a date and time and pressing enter (!). If you don't press
   enter after typing the new time, nothing will happen. You can enter a time
   in this format:
      'day time'

   The day may be entered using these formats:
      doy/yy		  e.g. 1/90
      doy/yyyy		  e.g. 2/1990
      dom.month.yy	  e.g. 1.3.91
      dom.month.yyyy	  e.g. 1.3.1991
      month/day/yy	  e.g. 3/1/91
      month/day/yyyy	  e.g. 3/1/1991

   The hour can be entered using these formats:
      hh:mm:ss		  e.g. 12:20:1
      hh:mm		  e.g.  5:1


********************************************************************************
ZOOMING AND MOUSE ACTION
********************************************************************************
   You can't zoom or slice until you've drawn your plots to the display!

ZOOMING
--------------------------------------------------------------------------------
   You can choose a plot's y-scaling or the time-range using zooming.

   To activate zooming, press the 'mouse does zoom'-button on the left side of
   the window.

   Move the mouse in the drawing area and over a drawn panelplot. Now, click
   somewhere and drag the mouse while pressing the button. A rectangular area
   will be displayed and a zoom-window will be opened (press its help-button
   for further help).

   The use of this functionalioty must be supported in your plot routine!

MOUSE ACTION
--------------------------------------------------------------------------------
   Depending on which mouse action has been supported by the modules, you
   can use the mouse to obtain more detailed information on the data in
   a given panel. The types of mouse actions supported should be described
   in that panel's panel editor's help.

   The most basic mouse function is zooming as described above. Further
   possible mouse actions are:
   
       mouse views slice:
          used for color plots or three dimensional data to draw a slice
          at the position of the mouse click. E.g., draws a line spectrum
          for color spctograms, or a line pitch angle distribution in color
          pitch angle plots.
       mouse views slice polar:
          only used by CRRES MEB overview plots.
       mouse accesses level zero
          calls up a level-zero data application if one exisits.
          currently only supported by HYDRA and SWE. This spawns
          an external IDL widget application and only hands over the
          cursor time and y-value.
       mouse views ephemeris:
          calls up a 3-d view of the orbit ephemeris  for a given panel in
          GSM coordinates. Currently only supported by POLAR.     

   To activate a mouse function, select one from the list under the 'mouse
   action' button.

   Move the mouse in the drawing area and over a drawn panelplot. Now, click
   somewhere. Some mouse actions update fast enough so that you can drag the   
   mouse while pressing the button. A vertical line will be displayed in the 
   panel for the time chosen.

********************************************************************************
BATCH-PROCESSING   
********************************************************************************
   You can use PAPCO to output the current list of plots for multiple 
   time-ranges.
   To do this, you have to create a file containing the time-ranges you wish to 
   plot. And then, you have to use this file as BATCH-control file for PAPCO.

   PAPCO supports you in creating a batch-control-file. In the middle of the   
   left half of the PAPCO-screen, you can see a graphics button that displays a 
   right-arrow and the text 'BATCH'. Each time you press this button, the 
   currently selected plot-time-range is added to the file 
	'interactive.papco_batch' 
   that resides in your home-directory. You can not change the name of this 
   file.

   Therefor, if you want PAPCO to help you in creating the batch-control-file,
   do this:

   1. open a shell
      remove the file 'interactive.papco_batch' 
		(issue the command 'rm ~/interactive.papco_batch')

   2. in PAPCO, select a time-range
      press the 'add to batch'-graphics-button 

   3. repeat 2. for each time-range you wish to add

   4. open a shell
      rename the file 'interactive.papco_batch'
		(e.g. 'mv ~/interactive.papco_batch ~/mybatch.papco_batch')

   Another way to create a file is, to edit it in an editor. Your filename 
   should end on '.papco_batch':

	- empty lines are ignored
   	- lines starting with '#' are ignored. You may use this for comments
	
	- each non-empty line that does not start with '#' has to contain 
	  exactly one time-range. The format of a line is this:

 	      line=orbit [, time-range] | time-range
	      orbit = aNumber
	      time-range= t90-time "-" t90-time
	      t90-time=date [" " time]
	      date = doy"/"year | day_om"."month"."year | month"/"day_om"/"year
	      (doy=aNumber, year=aNumber, day_om=aNumber, month=aNumber)
	      time = hour":"minutes[":"seconds]
	      (time=aNumber, minutes=aNumber, seconds=aNumber)

   Example for a valid file:

      # use orbit 11, plot times starting on 7/30/90 at 8:17:32 a.m
      #			         ending   on 7/30/90 at 5:50:32 p.m.
	11, 30.7.90 08:17:32 - 30.7.90 17:50:32

      # use orbit 106, plot all of orbit 106
	106

      # use orbit 106, start at 0:00 of 9/7/90, end at 0:00 of 9/8/90
	106, 7.9.90 - 8.9.90

      # use no orbit information, start plotting at 9:04:32a.m. of 7th sept. 90
      #			            end plotting at 6:37:32p.m. of 8th sept. 90
	7.9.90 09:04:32 - 8.9.90 18:37:32

      # use no orbit information, start plotting at  0:00 a.m. of 7th sept. 90
      #		         	    end plotting at 10:00 a.m. of 8th sept. 90
	7.9.90 - 8.9.90 10:00
    
   Doing BATCH-print:
       
   Either use the 'batch-preview' or the 'batch print to file' entry of the 
   print-menu. 

   The 'batch-preview' command draws the currently selected plots to the display
   for each time found in the batch-control file. After a plot is done, you are
   required to press a 'continue' button

   The 'batch print to file' plots the currently selected panels for each time
   found in the batch-control file to the PAPCO-default file. So, before using 
   this command, make sure, that you default-filename uses some of the templates
	    '%', '<', '>'
   If it doesn't, PAPCO might write different plots to the same file-name.

  
********************************************************************************
THE ACTION BUTTONS
********************************************************************************
   These are situated unter the drawing area. They are:
   
	Draw    Print    Help    Load    Save    Reset   Done
 
   Draw		press this button to draw the currently selected plots to the 
		display

   Print	use this button to output the currently selected plots to a
		 printer or a file. If you press this button, a pulldown-menu
	        appears. Its functions are:
		
		...to standard printer: <<name>>   output the plots to the
						   default printer

		...to standard file: <<a filename> print them to the 
						   file

		...select printer		   ask for a printer/file
						   and then plot in it

		...select default printer	   select the default
						   printer

                batch preview			   batch-print, and output
						   to display
 	  	 				   ---> see BATCH-PROCESSING

		batch print to file		   batch-print, output to	
						   a file
 	  	 				   ---> see BATCH-PROCESSING

   Help		well, as you are reading this, you know what this button does

   Load		Load the list of plots and the orbit from a previously saved
		file
   
   Save		save the currently listed plots and the orbit to a file

   Reset	reset PAPCO to its initial state

   Done		leave PAPCO
