This page was created by the IDL library routine `mk_html_help2`.

Last modified: Tue Sep 6 13:13:28 2005.

# Directory Listing of Routines

# general/misc/

- APPEND_ARRAY
  Append an array to another array. Can also copy an array into a
- AVERAGE_STR
  Average data in res second time segments.
- BYTESCALE
- CART_TO_SPHERE
  transform from cartesian to spherical coordinates
- CDF_FILE_NAMES
  Returns an array of filenames within a timerange.
- COLORS_COM
- DATA_TYPE
  Returns the variable type (ignores dimension).
- DAY_TO_YEAR_DOY
  determines year and day of year given day since 0000 AD
- DIMEN
  Returns the dimensions of an array as an array of integers.
- DIMEN1
- DIMEN2
- DIMEN_SHIFT
  Rotate dimensions of a multidimensional array.
- DIVIDE_DATA
- DOY_TO_MONTH_DATE
  Determines month and date given the year and day of year.
- EXTRACT_TAGS
- FIND_STR_ELEMENT
- FNAME_TO_TIME
  To translate the name of a standard WIND data file into the starting
- GET_COLORS
- GET_FILE_NAMES
  Gets an array of filenames within a time range
- GET_FILE_NAMES_IND
  Gets an array of filenames within a masterfile within a time range
- INTERP
  Linearly Interpolates vectors with an irregular grid.
- LIBS
- LOADCT2
- MAKEGIF
  Creates a GIF file from the currently displayed image.
- MINMAX
- MK_HTML_HELP2
  Creates a html document from a list of IDL procedures.
- NDIMEN
  Returns the number of dimensions in an array.
- NN
- OPLOT_ERR
  Plot error bars over a previously drawn plot.
- PCLOSE
- PLOT_POSITIONS
  Procedure that will compute plot positions for multiple plots per page.
- POPEN
  Change plot device to postscript.
- POPEN_COM
- PRINT_OPTIONS
- PRINTDAT
  Displays information and contents of a data variable.
- SHARE_COLORS
  Procedure that allows multiple IDL sessions to share the same color table.
- STR_ELEMENT
  Find (or add) an element of a structure.
- STRFILTER
  Returns the subset of stringarray that matchs filterstring
- TIME_DOUBLE
  A fast, vectorized routine that returns the number of seconds since 1970.
- TIME_EPOCH
  Returns the EPOCH time required by CDF files.
- TIME_PB5
  Returns the PB5 time required by CDF files.
- TIME_STAMP
  Prints a time stamp along the lower right edge of the current plot box
- TIME_STRING
  Converts time to a date string.
- TIME_STRUCT
  A fast, vectorized routine that returns a time structure.
- TIME_TICKS
  Returns a structure that can be used to create time ticks for a plot.
- TRANGE_STR
- WI

# Routine Descriptions

## APPEND_ARRAY

[Next Routine] [List of Routines]

    PROCEDURE:	append_array, a0, a1
    PURPOSE:
    	Append an array to another array.  Can also copy an array into a
    	subset of another.
    INPUT:
    	a0:	Array to modify.
    	a1:	Array to append to, or copy into, a0.
    KEYWORDS:
    	index:	Index of a0 at which to append or copy a1.  If index is
    		greater than the number of elements of a0, then
    		a0 is enlarged to append a1. Returns the index of the first
    		element of a0 past the section copied from a1.
    	done:	If set, make a0 equal to the first index elements of a0.
    CREATED BY:	Davin Larson
    LAST MODIFIED:	@(#)append_array.pro	1.6 98/08/13

(See append_array.pro)

## AVERAGE_STR

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:	average_str(data, res)
    PURPOSE:
    	Average data in res second time segments.
    INPUTS:
    	DATA:	array of structures.  One element of structure must be TIME.
    	RES:	resolution in seconds.
    KEYWORDS:
    	NAN:	If set, treat the IEEE NAN value as missing data.
    CREATED BY:	Davin Larson
    LAST MODIFIED:	%W% %E%

(See average_str.pro)

## BYTESCALE

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:  bytescale(array)
    PURPOSE:   Takes an array or image and scales it to bytes
    INPUT:     array of numeric values.
    KEYWORDS:
       RANGE:  Two element vector specifying the range of array to be used.
            Defaults to the min and max values in the array.
       ZERO:   Forces range(0) to zero
       TOP:    Maximum byte value  (default is !d.table_size-2)
       BOTTOM: Minimum byte value  (default is 1)
       MIN_VALUE: autoranging ignores all numbers below this value
       MAX_VALUE: autoranging ignores all numbers above this value
       MISSING:  Byte value for missing data. (values outside of MIN_VALUE,
         MAX_VALUE range)  If the value is less than 0 then !p.background is used.
       LOG:    sets logrithmic scaling

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)bytescale.pro	1.22 02/04/17

(See bytescale.pro)

## CART_TO_SPHERE

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  cart_to_sphere, x, y, z,  r, theta, phi
    PURPOSE:
                transform from cartesian to spherical coordinates
    INPUTS:     x, y, z          (array or scalor)
    OUTPUTS:    r, theta, phi    (same as x,y,z)
    KEYWORDS:   ph_0_360:   if positive, 0<=phi<=360, if zero, -180<=phi<=180,
                            ***if negative, best guess phi range returned***
                ph_hist:   a two element array of max and min values for phi.
                            eg: if ph_0_360 is not set, and ph_hist=[-220,220]
                                then if d(phi)/dt is positive near 180, then
                                phi => phi+360 when phi passes the 180/-180
                                discontinuity until phi reaches 220.
                CO_LATITUDE:  If set theta will be in co-latitude. (0<=theta<=180)
                MIN_VALUE:
                MAX_VALUE:
    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)cart_to_sphere.pro	1.13 02/04/17

    NOTES:
       -90 < theta < 90   (latitude not co-lat)

(See cart_to_sphere.pro)

## CDF_FILE_NAMES

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION: cdf_file_names
    PURPOSE:
       Returns an array of filenames within a timerange.
    USAGE:
       files=cdf_file_names(FORMAT,trange=trange,/verbose)
    INPUT:
       FORMAT is a string that will be interpreted as one of two things:
         CASE 1:
            e.g.    FORMAT = '/home/wind/dat/wi/3dp/k0/????/wi_k0_3dp*.cdf'
            if FORMAT contains * or ? then filenames are returned that match that
            pattern and for which YYYYMMDD falls within the specified timerange.
            for example:
            (UNIX only)
         CASE 2:
            e.g.    FORMAT = 'fa_k0_ees_files'
            The name of an indexfile that associates filenames with start and
            end times. If his file is not found, then the environment variable
            getenv('CDF_INDEX_DIR') is prepended and searched for.
            See "MAKE_CDF_INDEX" for information on producing this file.
         SPECIAL NOTE:
            If strupcase(FORMAT) is the name of an environment varible. Then
            the value of that environment variable is used instead.
    KEYWORDS:
         TRANGE:
            Two element array specifying the time range for which data files should
            be returned.  If not provided then "TPLOT/help_list.html#TIMERANGE">TIMERANGE" is called to provide
            the time range.  See also "TPLOT/help_list.html#TIMESPAN">TIMESPAN".
         NFILES:
            Named variable that returns the number of files found.
         VERBOSE:
            Set to print some useful info.
         FILEINFO:  OBSOLETE!
            Set to a named variable that will return a table of file info.
    NOTES:
         UNIX only!

(See cdf_file_names.pro)

## COLORS_COM

[Previous Routine] [Next Routine] [List of Routines]

    COMMON BLOCK  colors_com
    WARNING!  Don't rely on this file to remain stable!
    USE "GET_COLORS" to get color information.
    SEE ALSO:
      "GET_COLORS","BYTESCALE","LOADCT2"
    CREATED BY: Davin Larson
    File:      96/08/30
    Version:   1.2
    Last Mod:  colors_com.pro

(See colors_com.pro)

## DATA_TYPE

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:  data_type(x)
    PURPOSE:
       Returns the variable type (ignores dimension).
    INPUTS: x:   Any idl variable.
    OUTPUT: integer variable type:
       0 = undefined
       1 = byte
       2 = integer
       3 = long
       4 = float
       5 = double
       6 = complex
       7 = string
       8 = structure
       9 = double precision complex

    KEYWORDS:
       STRUCTURE: When set and if input is a structure, then an array
           of data types are returned.

    SEE ALSO:  "DIMEN", "NDIMEN"

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)data_type.pro	1.7 00/07/05

(See data_type.pro)

## DAY_TO_YEAR_DOY

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
       day_to_year_doy
    PURPOSE:
       determines year and day of year given day since 0000 AD
    USAGE:
       day_to_year_doy,daynum,year,doy
    INPUT:
       daynum:   (long int)  day since 0 AD
    OUTPUT:
       year:     year         (0 <= year <= 14699 AD)
       doy:      day of year  (1 <= doy  <=  366)
    NOTES:
      This procedure is reasonably fast, it works on arrays and works from
      0 AD to 14699 AD

    CREATED BY:	Davin Larson  Oct 1996
    FILE:  day_to_year_doy.pro
    VERSION:  1.2
    LAST MODIFICATION:  97/01/27

(See day_to_year_doy.pro)

## DIMEN

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:   dimen(x)
    PURPOSE:
      Returns the dimensions of an array as an array of integers.
    INPUT:  matrix
    RETURNS:  vector of dimensions of matrix.
       If the input is undefined then 0 is returned.
       if the input is a scaler then 1 is returned.

    SEE ALSO:  "dimen", "DATA_TYPE", "DIMEN1", "DIMEN2"

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)dimen.pro	1.6 96/12/16

(See dimen.pro)

## DIMEN1

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:   dimen1
    INPUT:  matrix
    RETURNS:  scaler int:  size of first dimension  (1 if dimension doesn't exist)

    CREATED BY:	Davin Larson
    LAST MODIFICATION;	@(#)dimen1.pro	1.3 95/08/24

(See dimen1.pro)

## DIMEN2

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:   dimen2
    INPUT:  matrix
    RETURNS:  scaler int:  size of second dimension  (1 if dimension doesn't exist)

    CREATED BY:	Davin Larson
    LAST MODIFICATION;	@(#)dimen2.pro	1.3 95/08/24

(See dimen2.pro)

## DIMEN_SHIFT

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:  dimen_shift(x,shift)
    NAME:
      dimen_shift
    PURPOSE:
      Rotate dimensions of a multidimensional array.
      This function is very similar to transpose but works on multi-dimensional
      arrays to shift the dimensions around.
      It has no effect on scalars and one dimensional arrays.
    INPUT:
      x   multi-dimensional array of any type
      shift:  1 or -1  direction of shift.
    CREATED BY: Davin Larson
    LAST MODIFICATION:	@(#)dimen_shift.pro	1.4 98/07/09

(See dimen_shift.pro)

## DIVIDE_DATA

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:	divide_data

    PURPOSE:

      Divides successive channels of SST data by powers of 'factor', to

      separate the traces. Also, optionally, multiplies data by an overall factor,

      'conv_factor', to convert units.

    INPUT:		in_name (string), the name of the input TPLOT variable
    			structure.
                   out_name (string), the name of the output TPLOT variable
    			structure.

    KEYWORDS:      factor (float), by which fluxes in successive channels are

                   	divided.
    		conv_factor (optional float), by which fluxes in all channels
    			are multiplied.

    CREATED BY:	Ted Freeman

    FILE:  divide_data.pro

    LAST MODIFIED:  @(#)divide_data.pro	1.2 99/09/01

    NOTES:	  "LOAD_3DP_DATA" and "GET_SPEC" must be called first.

(See divide_data.pro)

## DOY_TO_MONTH_DATE

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:
      doy_to_month_date, year, doy, month, date
    NAME:
      doy_to_month_date
    PURPOSE:
     Determines month and date given the year and day of year.
     fast, vector oriented routine that returns the month and date given year and
     day of year (1<=doy<=366)

    CREATED BY:	Davin Larson  Oct 1996
    FILE:  doy_to_month_date.pro
    VERSION:  1.2
    LAST MODIFICATION:  97/01/27

(See doy_to_month_date.pro)

## EXTRACT_TAGS

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  extract_tags, newstruct, oldstruct
    PURPOSE: takes the named tag elements from oldstruct and puts them into
       newstruct.  This procedure is very useful for creating a structure that
       can be passed onto the PLOT or OPLOT subroutines using the _EXTRA keyword.
       If no tag keywords are included then all tag elements of oldstruct are
       added to newstruct.  The mode keyword PRESERVE is used to prevent the
       overwritting of an existing keyword.
    INPUTS:
      newstruct:  new structure to be created or added to.
      oldstruct:  old structure from which elements are extracted.
    KEYWORDS:  Only one of the following should be given:;
     (TAG KEYWORDS)
      TAGS:  array of strings.  (tag names) to be taken from oldstruct and put in
          newstruct
      EXCEPT: array of strings.  Tag names not to be copied from old to new.
      OPLOT:  (flag)  If set, then TAGS is set to an array of valid keywords
         for the OPLOT subroutine.
      PLOT:   (flag)  If set, then TAGS is set to an array of valid keywords
         for the PLOT subroutine.
      CONTOUR: (flag) If set, then TAGS is set to an array of valid keywords
         for the CONTOUR procedure.   (might not be complete)
    If no KEYWORDS are set then all elements of oldstruct are put into newstruct
      (MODE KEYWORDS)
      PRESERVE: (flag) Prevents the overwritting of an existing, non-null keyword.
         Adds tags to newstruct that were not already there, or if they were there
         and their values were either "" or 0.
    CREATED BY:	Davin Larson
    FILE:  extract_tags.pro
    VERSION  1.21
    LAST MODIFICATION: 02/04/17

(See extract_tags.pro)

## FIND_STR_ELEMENT

[Previous Routine] [Next Routine] [List of Routines]

     **** OBSOLETE!!! Please use "STR_ELEMENT"instead! ***

    FUNCTION:  find_str_element
    PURPOSE:  find an element within a structure
     Input:
       struct,  generic structure
       name,    string  (tag name)
     Purpose:
       Returns index of structure tag.
       Returns -1 if not found
       Returns -2 if struct is not a structure
    KEYWORDS:
      If VALUE is set to a named variable then  the value of that element is
       returned in it.

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)find_str_element.pro	1.6 95/10/06

(See find_str_element.pro)

## FNAME_TO_TIME

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:	fname_to_time, fname, time
    PURPOSE:
    	To translate the name of a standard WIND data file into the starting
    	time of the data.
    INPUT:
    	fname: filename (string) to be translated
    	time: variable in which to return time (double)

    CREATED BY:	Peter Schroeder
    LAST MODIFICATION:	%W% %E%

(See fname_to_time.pro)

## GET_COLORS

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:    get_colors
    PURPOSE:   returns a structure containing color pixel values
    INPUT:    none
    KEYWORDS:
       NOCOLOR:  forces all colors to !d.table_size-1.

    Written by: Davin Larson    96-01-31
    FILE: get_colors.pro
    VERSION:  1.2
    LAST MODIFICATION: 99/04/07

(See get_colors.pro)

## GET_FILE_NAMES

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  get_file_names,  fnames
    PURPOSE:
       Gets an array of filenames within a time range
    INPUT:
       fnames:  named variable in which the output array of filenames is placed.
    KEYWORDS:
       TIME_RANGE: Two element vector (double or string) specifying the time range.
         If time range is not set, then "TPLOT/help_list.html#GET_TIMESPAN">GET_TIMESPAN" will be called
         to get a time range.
       MASTERFILE: Use this keyword to pass in one of the following:
    	1) Name of a masterfile that contains times and associated
    	     	filenames.  The file should have the format:
    yyyy-mm-dd/hh:mm:ss   yyyy-mm-dd/hh:mm:ss   fullpathfilename
         		with one line for each file.
    	     (Hint: for CDF files, the masterfile can be created using the
    	     UNIX program 'kpdfile' or the IDL procedure "MAKE_CDF_INDEX".)
    	2) Full path/file names with wildcard characters to search for
    		relevant files.  Input should be in the form:
    		/path/xxx* for files of form /path/xxx_date.
    	3) The name of a previously defined environment variable containing
    		data in the form of 1 or 2 above.
       ROOT_DIR:   Optional root_directory of the masterfile.  This will properly
          manage operating system dependancies.

    CREATED BY:	Davin Larson
    MODIFIED BY:	Peter Schroeder
    VERSION:	1.26 00/10/04 get_file_names.pro

(See get_file_names.pro)

## GET_FILE_NAMES_IND

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  get_file_names_ind,  fnames
    PURPOSE:
       Gets an array of filenames within a masterfile within a time range
    INPUT:
       fnames:  named variable in which the output array of filenames is placed.
    KEYWORDS:
       TIME_RANGE: Two element vector (double or string) specifying the time range.
         If time range is not set, then "TPLOT/help_list.html#GET_TIMESPAN">GET_TIMESPAN" will be called
         to get a time range.
       MASTERFILE: Name of a masterfile that contains times and associated
         filenames.  The file should have the format:
    yyyy-mm-dd/hh:mm:ss   yyyy-mm-dd/hh:mm:ss   fullpathfilename
         with one line for each file.
         (Hint: for CDF files, the masterfile can be created using the
         UNIX program 'kpdfile' or the IDL procedure "MAKE_CDF_INDEX".)
       ROOT_DIR:   Optional root_directory of the masterfile.  This will properly
          manage operating system dependancies.
       NO_DUPLICATES:  (N;  integer)
          when set the first N characters of file names are compared and only
          the highest version is returned.

    CREATED BY:	Davin Larson
    VERSION:	@(#)get_file_names_ind.pro	1.1 97/06/23

(See get_file_names_ind.pro)

## INTERP

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:   interp(y,x,u)
    PURPOSE:
      Linearly Interpolates vectors with an irregular grid.
      INTERP is functionally the same as INTERPOL, however it is typically
      much faster for most applications.
    USAGE:
      result = interp(y,x,u)
    INPUTS:
           Y:      The input vector can be any type except string.

           X:      The absicissae values for Y.  This vector must have same # of
                   elements as Y.  The values MUST be monotonically ascending
                   or descending.

           U:      The absicissae values for the result.  The result will have
                   the same number of elements as U.  U does not need to be
                   monotonic.
    KEYWORDS:
      NO_CHECK_MONOTONIC:   set this keyword to skip the check for monotonic data.
      INDEX:  Set to named variable to return the index of the closest x less than u.
          (same dimensons as u)
      NO_EXTRAPOLATE:  Set this keyword to prevent extrapolation.
      INTERP_THRESHOLD:  Set to minimum allowed gap size.

    CREATED BY:	Davin Larson  4-30-96
    FILE:  interp.pro
    VERSION:  1.15
    LAST MODIFICATION:  02/04/17

(See interp.pro)

## LIBS

[Previous Routine] [Next Routine] [List of Routines]

    Name: libs
    Purpose:
      Displays location of source files.

    Usage:
      libs,string  ; string is the name of an IDL source file.
                     It may contain wildcard characters
    Restrictions:
       UNIX only

(See libs.pro)

## LOADCT2

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE loadct2, colortable

    KEYWORDS:
       FILE:  Color table file
              Uses the environment variable IDL_CT_FILE to determine
              the color table file if FILE is not set.
    common blocks:
       colors:      IDL color common block.  Many IDL routines rely on this.
       colors_com:
    See also:
       "GET_COLORS","COLORS_COM","BYTESCALE"

    Created by Davin Larson;  August 1996
    Version:           1.4
    File:              00/07/05
    Last Modification: loadct2.pro

(See loadct2.pro)

## MAKEGIF

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  makegif, filename
    NAME:
      makegif
    PURPOSE:
      Creates a GIF file from the currently displayed image.
    NOTES:
      extension '.gif' is added automatically
    Restrictions:
      Current device should have readable pixels (ie. 'x' or 'z')

    Created by:  Davin Larson
    FILE:  makegif.pro
    VERSION:  1.11
    LAST MODIFICATION:  02/11/06

(See makegif.pro)

## MINMAX

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:   minmax,array
    PURPOSE:  returns a two element array of min, max values
    INPUT:  array
    KEYWORDS:
      MAX_VALUE:  ignore all numbers greater than this value
      MIN_VALUE:  ignore all numbers less than this value
      POSITIVE:   forces MINVALUE to 0

    CREATED BY:    Davin Larson
    LAST MODIFICATION:     @(#)minmax.pro	1.2 02/04/17

(See minmax.pro)

## MK_HTML_HELP2

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	MK_HTML_HELP2

     PURPOSE:
           Creates a html document from a list of IDL procedures.
    	Given a list of IDL procedure files (.PRO), VMS text library
           files (.TLB), or directories that contain such files, this procedure
           generates a file in the HTML format that contains the documentation
           for those routines that contain a DOC_LIBRARY style documentation
           template.  The output file is compatible with World Wide Web browsers.
           This version is enhanced over the routine supplied by IDL, It will
           also cross reference, print the purpose, and add links to the source
           code.

     CATEGORY:
    	Help, documentation.

     CALLING SEQUENCE:
    	MK_HTML_HELP, Sources, Outfile

     INPUTS:
         Sources:  A string or string array containing the name(s) of the
    		.pro or .tlb files (or the names of directories containing
                   such files) for which help is desired.  If a source file is
                   a VMS text library, it must include the .TLB file extension.
                   If a source file is an IDL procedure, it must include the .PRO
                   file extension.  All other source files are assumed to be
                   directories.  If not provided, searches down directory tree
    		from current directory for files.

         Outfile:	The name of the output file which will be generated without
    		HTML extension.

         If no inputs are given: All directories in the current directory tree
                   are used with the exception of: directories named: 'obsolete'
                   or 'SCCS.'  (UNIX only)

     KEYWORDS:
         TITLE:	If present, a string which supplies the name that
    		should appear as the Document Title for the help.
         FILENAME: Alternative method of specifying Outfile (see above)
         VERBOSE:	Normally, MK_HTML_HELP does its work silently.
    		Setting this keyword to a non-zero value causes the procedure
    		to issue informational messages that indicate what it
    		is currently doing. !QUIET must be 0 for these messages
                   to appear.
         STRICT:   If this keyword is set to a non-zero value, MK_HTML_HELP will
                   adhere strictly to the HTML format by scanning the
                   the document headers for characters that are reserved in
                   HTML (",&,").  These are then converted to the appropriate
                   HTML syntax in the output file. By default, this keyword
                   is set to zero (to allow for faster processing).
         CROSSLINK:If this keyword is set MK_HTML_HELP will create a cross
                   reference between library files.
         CLTURBO:  If this keyword is set to a single character string, then the
                   cross reference procedure will only cross reference lines that
                   contain the character given in CLTURBO.  This greatly increases
                   the speed of the routine.  By default the double quote (") is
                   used
         PRINT_PURPOSE:  If this keyword is set then the first line after PURPOSE:
                   is printed in the output file.
         MASTLIST:	If set, create master list only.  Do not create subdirectory
    		file listings.

     COMMON BLOCKS:
    	None.

     SIDE EFFECTS:
    	A help file with the name given by the Outfile argument is
    	created.

     RESTRICTIONS:
    	The following rules must be followed in formatting the .pro
    	files that are to be searched.
    		(a) The first line of the documentation block contains
    		    only the characters ";+", starting in column 1.
                   (b) There must be a line which contains the string "NAME:",
                       which is immediately followed by a line containing the
                       name of the procedure or function being described in
                       that documentation block.  If this NAME field is not
                       present, the name of the source file will be used.
    		(c) The last line of the documentation block contains
    		    only the characters ";-", starting in column 1.
    		(d) Every other line in the documentation block contains
    		    a ";" in column 1.

           Note that a single .pro file can contain multiple procedures and/or
           functions, each with their own documentation blocks. If it is desired
           to have "invisible" routines in a file, i.e. routines which are only
           for internal use and should not appear in the help file, simply leave
           out the ";+" and ";-" lines in the documentation block for those
           routines.

    	No reformatting of the documentation is done.

     MODIFICATION HISTORY:
           July 5, 1995, DD, RSI. Original version.
           July 13, 1995, Mark Rivers, University of Chicago. Added support for
                   multiple source directories and multiple documentation
                   headers per .pro file.
           July 17, 1995, DD, RSI. Added code to alphabetize the subjects;
                   At the end of each description block in the HTML file,
                   added a reference to the source .pro file.
           July 18, 1995, DD, RSI. Added STRICT keyword to handle angle brackets.
           July 19, 1995, DD, RSI. Updated STRICT to handle & and ".
                   Changed calling sequence to accept .pro filenames, .tlb
                   text librarie names, and/or directory names.
                   Added code to set default subject to name of file if NAME
                   field is not present in the doc header.
           September, 1995, D. Larson. SSL Berkeley. Added crosslink, print_purpose
                   clturbo.
           October 4, 1995, D. Larson. SSL Berkeley. Added link to source file.
           October 3, 1996, F. Marcoline. SSL Berkeley.  Added Alphabet Jumpline.
           October 10, 1996, D. Larson. Added Listing by Directory.

    FILE:  mk_html_help2.pro
    VERSION 1.26
    LAST MODIFICATION: 99/04/22

(See mk_html_help2.pro)

## NDIMEN

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION: ndimen
    PURPOSE:
      Returns the number of dimensions in an array.
    INPUT:  array
    RETURNS number of dimensions  (0 for scalers,-1 for undefined)

    SEE ALSO:  "DIMEN", "DATA_TYPE"

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)ndimen.pro	1.6 97/03/10

(See ndimen.pro)

## NN

[Previous Routine] [Next Routine] [List of Routines]

    NAME:                  nn
    PURPOSE:               Find the index of the data point(s) nearest to the specified time(s)

    CALLING SEQUENCE:      ind=nn(data,time)
    INPUTS:                data:  a data structure, a tplot variable name/index,
                              or a time array
                           time:  (double) seconds from 1970-01-01, scalar or array
                                  if not present, "TPLOT/help_list.html#CTIME">CTIME" is called to get time(s)
    OPTIONAL INPUTS:       none
    KEYWORD PARAMETERS:    x, y, & v:  set to named keywords to return the values
    			of the x, y, & v arrays, if applicable

    OUTPUTS:               a long scalar index or long array of indicies
                           on failure, returns: -2 if bad inputs,
                                                -1 if nearest neighbor not found
    EXAMPLE:               ctime,times,npoints=2
                           inds=nn('Np',times)
                           get_data,'Np',data=dens & get_data,'Tp',data=temp
                           plot,dens.y(inds(0):inds(1)),temp(inds(0):inds(1))
    LAST MODIFICATION:     @(#)nn.pro	1.8 02/04/17
    CREATED BY:            Frank Marcoline

(See nn.pro)

## OPLOT_ERR

[Previous Routine] [Next Routine] [List of Routines]

     PROCEDURE:
    	oplot_err, x, low, high
     PURPOSE:
    	Plot error bars over a previously drawn plot.

(See oplot_err.pro)

## PCLOSE

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   pclose
    INPUT:  none
    PURPOSE: Close postscript file opened with popen, and change device back to
      default.
      If common block string 'printer_name' is set, then file is sent to that
      printer.
    SEE ALSO: 	"PRINT_OPTIONS"
    		"POPEN"

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)pclose.pro	1.10 99/02/18

(See pclose.pro)

## PLOT_POSITIONS

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:   plot_positions
    PURPOSE:
      Procedure that will compute plot positions for multiple plots per page.
    Created by Davin Larson

(See plot_positions.pro)

## POPEN

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: popen, filename
    PURPOSE:
      Change plot device to postscript.
    INPUT:    optional;  if:
      string   :  string used as filename,  '.ps' extension is added automatically
      integer X:  filename set to 'plotX.ps'.  value of x is incremented by 1.
      none:       filename set to 'plot.ps'
    KEYWORDS: See print_options for info.
      COPY:    pass COPY keyword to set_plot
      INTERP:  pass INTERP keyword to set_plot  (default is to have interp off)

    SEE ALSO:	"PCLOSE",
    		"PRINT_OPTIONS",
    		"POPEN_COM"

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)popen.pro	1.21 98/06/23

(See popen.pro)

## POPEN_COM

[Previous Routine] [Next Routine] [List of Routines]

    COMMON BLOCK:	popen_com
    PURPOSE:	Common block for print routines

    SEE ALSO:	"POPEN","PCLOSE",
    		"PRINT_OPTIONS"

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)popen_com.pro	1.10 97/12/05

(See popen_com.pro)

## PRINTDAT

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: printdat,x, [name]
    PURPOSE:
       Displays information and contents of a data variable.
       This routine is most useful for displaying contents of complex
       data structures.

    Keywords:
       WIDTH:   Width of screen.
       MAX:     Maximum number of array elements to print.  (default is 5)
       NSTRMAX  Maximum number of structure (or pointer) elements to print.
                (default is 3)

    Written by Davin Larson, May 1997.

(See printdat.pro)

## PRINT_OPTIONS

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: print_options
    PURPOSE:  controls postscript printing options
    KEYWORDS:
      PORT:   print pages in portrait format (default)
      LAND:   print pages in landscape format
      BW:     Use black and white mode  (untested)
      COLOR:  Use Color postscript (default)
    FUTURE OPTIONS:
      Ecapsulated postscript format
      changing plotting area

    SEE ALSO:	"POPEN","PCLOSE"

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)print_options.pro	1.16 97/05/30

(See print_options.pro)

## SHARE_COLORS

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:
      share_colors
    PURPOSE:
      Procedure that allows multiple IDL sessions to share the same color table.
      The procedure should be called in each session before any
      windows are created.
    USAGE:
      Typically this procedure will be put in a startup routine. such as:
      share_colors,first=f
      if f then loadct,39

    KEYWORDS:
      FIRST Named variable that will be set to 1 if this is the
          first session, and set to 0 otherwise.
    SIDE EFFECTS:
      Creates a temporary file with the name 'idl_cmap:NAME' on the users home
      directory where NAME is the name of the display machine.
      This file is deleted upon exiting IDL.
      The procedure is only useful on UNIX for users with a common home directory.

(See share_colors.pro)

## STRFILTER

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:
      res =  strfilter(stringarray,filterstring)
    PURPOSE:
      Returns the subset of stringarray that matchs filterstring
      '*' will match all (non-null) strings
      ''  will match only the null string
      Output can be modified with keywords
    INPUT:
      stringarray:  An array of strings to be filtered
      filterstring: A string that may contain wildcard characters ("*")
               (If filterstring is an array then results are OR'd together)
    RETURN VALUE:
      Either:
         Array of matching strings.
      or:
         Array of string indices.
      or:
         Byte array with same dimension as input string.
      Depends upon keyword setting (See below)

    KEYWORDS:
      STRING: if set then the matching strings are returned.  (default)
      INDEX:  if set then the indices are returned.
      BYTES:  if set then a byte array is returned with same dimension as input string.
      NEGATE: pass only strings that do NOT match.
      COUNT:  A named variable that will contain the number of matched strings.
    Limitations:
      This function still needs modification to accept the '?' character
      July 2000;  modified to use the IDL strmatch function so that '?' is accepted
    EXAMPLE:
      Print,strfilter(findfile('*'),'*.pro',/negate) ; print all files that do NOT end in .pro
    AUTHOR:
      Davin Larson,  Space Sciences Lab, Berkeley; Feb, 1999
    VERSION:  01/10/08

(See strfilter.pro)

## STR_ELEMENT

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  str_element, struct,  tagname, value
    PURPOSE:
     Find (or add) an element of a structure.
     This procedure will not
     Input:
       struct,  generic structure
       tagname,    string  (tag name)
     Output:
       value,  Named variable in which value of the structure element is returned.
     Purpose:
       Retrieves the value of a structure element.  This function will not produce
       an error if the tag and/or structure does not exist.
    KEYWORDS:
      SUCCESS:  Named variable that will contain a 1 if the element was found
         or a 0 if not found.
      INDEX: a named variable in which the element index is returned.  The index
         will be -2 if struct is not a structure,  -1 if the tag is not found,
         and >= 0 if successful.
      ADD_REPLACE:  Set this keyword to add or replace a structure element.
      DELETE:   Set this keyword to delete the tagname.
      CLOSEST:  Set this keyword to allow near matchs (useful with _extra)
      VALUE: (obsolete) alternate method of returning value. (Will not work with recursion)
    Notes:
      Value remains unchanged if the structure element does not exist.
      If tagname contains a '.' then the structure is recursively searched and
        index will be an array of indices.
      If struct is an array then results may be unpredictable.

    Modifications:
      5/7/97: Added recursive searching of structure hierarchy.  D. Larson

    CREATED BY:	Davin Larson
    FILE:  str_element.pro
    VERSION  1.10
    LAST MODIFICATION: 01/10/08

(See str_element.pro)

## TIME_DOUBLE

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION: time_double(time)
    NAME:
      time_double
    PURPOSE:
     A fast, vectorized routine that returns the number of seconds since 1970.
    INPUT:  input can be of type:
      double(s)      seconds since 1970   (returns the input)
      string(s)      format:  YYYY-MM-DD/hh:mm:ss  see "TIME_STRING"
      structure(s)   format returned in "TIME_STRUCT"
      long array     (MUST be 2 dimensional!)  PB5 time  (req. by CDF)

    OUTPUT:
      double, number of seconds since 1970  (UNIX time)
    KEYWORDS:
      EPOCH:  if set, it implies the input is double precision EPOCH time.

    SEE ALSO:  "TIME_STRING", "TIME_STRUCT", "TIME_EPOCH", "TIME_PB5"

    NOTE:
      This routine works on vectors and is designed to be fast.
      Output will have the same dimensions as the input
      Out of range values are interpreted correctly.
      ie.  1994-13-1/12:61:00  will be treated as:  1995-1-1/13:01:00

    CREATED BY:	Davin Larson  Oct 1996
    FILE:  time_double.pro
    VERSION:  1.9
    LAST MODIFICATION:  01/07/12

(See time_double.pro)

## TIME_EPOCH

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
      time_epoch
    PURPOSE:
      Returns the EPOCH time required by CDF files.
    USAGE:
      epoch = time_epoch(t)
     NOT TESTED!!!

    CREATED BY:	Davin Larson  Oct 1996
    FILE:  time_epoch.pro
    VERSION:  1.1
    LAST MODIFICATION:  96/10/16

(See time_epoch.pro)

## TIME_PB5

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
      time_pb5
    PURPOSE:
      Returns the PB5 time required by CDF files.
    USAGE:
      pb5 = time_pb5(t)
    OUTPUT:
      2 dimensional long integer array with dimensions:  (n,3)  Where n is the number
      of elements in t
    Not fully TESTED!!!!

    CREATED BY:	Davin Larson  Oct 1996
    FILE:  time_pb5.pro
    VERSION:  1.3
    LAST MODIFICATION:  97/01/27

(See time_pb5.pro)

## TIME_STAMP

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   time_stamp,charsize=charsize
    PURPOSE:
         Prints a time stamp along the lower right edge of the current plot box
    KEYWORDS:
         CHARSIZE:  The character size to be used.  Default is !p.charsize/2.
         ON:        if set, then timestamping is turned on. (No other action taken)
         OFF:       if set, then timestamping is turned off. (Until turned ON)

(See time_stamp.pro)

## TIME_STRING

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION: time_string(time)
    NAME:
      time_string
    PURPOSE:
      Converts time to a date string.
    INPUT:  input can be a scaler or array of any dimension of type:
      double(s)      seconds since 1970
      string(s)      format:  YYYY-MM-DD/hh:mm:ss
      structure(s)   format:  given in "TIME_STRUCT"
      float(s)
      longs(s)
                     values outside normal range will be corrected.
    KEYWORDS:
      FORMAT:         specifies output format.
        FORMAT=0:  YYYY-MM-DD/hh:mm:ss
        FORMAT=1:  YYYY Mon dd hhmm:ss
        FORMAT=2:  YYYYMMDD_hhmmss
        FORMAT=3:  YYYY MM dd hhmm:ss
      SQL:            produces output format: "YYYY-MM-DD hh:mm:ss.sss"
                      (quotes included) which convenient for building SQL queries.
      PRECISION:      specifies precision
          -5:   Year only
          -4:   Year, month
          -3:   Year, month, date
          -2:   Year, month, date, hour
          -1:   Year, month, date, hour, minute
           0:   Year, month, date, hour, minute, sec
          >0:   millisecs
      AUTOPREC  If set PREC will automatically be set based on the array of times
      DELTAT:   (float) PREC set based on this precision.
      DATE_ONLY:   Same as PREC = -3
      MSEC:        Same as PREC = 3

    OUTPUT:
      string with the following format: YYYY-MM-DD/hh:mm:ss (Unless
      modified by keywords.)

    See Also:  "TIME_DOUBLE"  , "TIME_STRUCT" or "TIME_TICKS"

    NOTE:
      This routine works on vectors and is designed to be fast.
      Output will have the same dimensions as the input.

    CREATED BY:	Davin Larson  Oct 1996
    FILE:  time_string.pro
    VERSION:  1.14
    LAST MODIFICATION:  02/11/01

(See time_string.pro)

## TIME_STRUCT

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION: time_struct(time)
    NAME:
      time_struct
    PURPOSE:
     A fast, vectorized routine that returns a time structure.
    INPUT:  input can be of type:
      double(s)      seconds since 1970
      string(s)      format:  YYYY-MM-DD/hh:mm:ss
      structure(s)   similar to format below.

    OUTPUT:
      structure with the following format:
    ** Structure TIME_STRUCT, 11 tags, length=40:
       YEAR            INT           1970            ; year    (0-14699)
       MONTH           INT              1            ; month   (1-12)
       DATE            INT              1            ; date    (1-31)
       HOUR            INT              0            ; hours   (0-23)
       MIN             INT              0            ; minutes (0-59)
       SEC             INT              0            ; seconds (0-59)
       FSEC            DOUBLE           0.0000000    ; fractional seconds (0-.999999)
       DAYNUM          LONG            719162        ; days since 0 AD  (subject to change)
       DOY             INT              0            ; day of year (1-366)
       DOW             INT              3            ; day of week  (subject to change)
       SOD             DOUBLE           0.0000000    ; seconds of day

    See Also:  "TIME_DOUBLE", "TIME_STRING", "TIME_EPOCH", "TIME_PB5"

    NOTE:
      This routine works on vectors and is designed to be fast.
      Output will have the same dimensions as the input

    CREATED BY:	Davin Larson  Oct 1996
    FILE:  time_struct.pro
    VERSION:  1.15
    LAST MODIFICATION:  02/11/01

(See time_struct.pro)

## TIME_TICKS

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:  time_tk_str = time_ticks(timerange,offset)
    NAME:
      time_ticks
    PURPOSE:
      Returns a structure that can be used to create time ticks for a plot.
      See "timetick" for more info
    INPUT:
      timerange: Two element vector specifying the time range of the plot
          this input can be obtained from: "TIME_DOUBLE", "TIME_STRUCT"
          or "TIME_STRING"
      offset: named variable in which offset time is placed.
    KEYWORDS:
      NUM_LAB_MIN:   minimum number of labels for bottom axis.

    OUTPUT:
      a structure that can be used with the _EXTRA keyword of the PLOT routine

    See Also: "box", "TPLOT"

     NOTES:

         The returned time_tk_str has tags named so that it can be used
         with the special _EXTRA keyword in the call to PLOT or OPLOT.

         The offset value that is returned from timetick must be
         subtracted from the time-axis data values before plotting.
         This is to maintain resolution in the PLOT routines, which use
         single precision floating point internally.  Remember that if
         the CURSOR routine is used to read a cursor position from the
         plot, this offset will need to be added back to the time-axis
         value to get seconds since  1970-01-01/00:00:00.

    NOTE:
      This routine is an enhanced version of the routine "timetick"
      See this routine for more info on usage

    WARNING!:
      This routine does not yet work on very small time scales.

    CREATED BY:	Davin Larson  Oct 1996
    FILE:  time_ticks.pro
    VERSION:  1.16
    LAST MODIFICATION:  02/04/17

(See time_ticks.pro)

## TRANGE_STR

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:   trange_str,t1,t2
    INPUT:  t1,t2   doubles,   seconds since 1970
    OUTPUT:  string  with the format:  'YYYY-MM-DD/HH:MM:SS - HH:MM:SS'

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)trange_str.pro	1.10 97/12/22

(See trange_str.pro)

## WI

[Previous Routine] [List of Routines]

    PROCEDURE: 	wi, wnum

    PURPOSE:	Switch or open windows.

    INPUT:
    	wnum - the window number.

    CREATED BY:	REE, 95-10-23
    FILE: wi.pro
    VERSION: 1.6
    LAST MODIFICATION: 97/06/03

(See wi.pro)