NAME:
      WCSXY2SPH_SMEI 

 PURPOSE:
      Convert x and y (map) coordinates to spherical coordinates
 EXPLANATION:
      To convert x and y (map) coordinates to spherical (longitude and 
      latitude or sky) coordinates.    This procedure is the inverse of
      WCSSPH2XY.

     This is a lower level procedure -- given a FITS header, the user will 
     usually use XYAD which will then call WCSXY2SPH with the appropriate 
     parameters.
 CATEGORY:
      Mapping and Auxilary FITS Routine

 CALLING SEQUENCE:

      wcsxy2sph_smei, x, y, longitude, latitude, [map_type], [ CTYPE = ,$
             FACE = ,PV2 = ,CRVAL =, CRXY =, LONGPOLE=, LATPOLE=]

 INPUT PARAMETERS:

       x - x coordinate of data, scalar or vector, in degrees, NOTE: x 
               increases to the left, not the right
       y - y coordinate of data, same number of elements as x, in degrees
       map_type - optional positional parameter, scalar corresponding to a 
               particular map projection.  This is not a FITS standard, it is 
               simply put in to allow function similar to that of less general 
               map projection procedures (eg AITOFF).  The following list gives
               the map projection types and their respective numbers.

  FITS  Number  Name                       Comments
  code   code
  ----  ------  -----------------------    -----------------------------------
   DEF     0    Default = Cartesian
   AZP     1    Zenithal perspective       pv2_1 required
   TAN     2    Gnomic                     AZP w/ pv2_1 = 0
   SIN     3    Orthographic               pv2_1, pv2_2 optional
   STG     4    Stereographic              AZP w/ pv2_1 = 1
   ARC     5    Zenithal Equidistant
   ZPN     6    Zenithal polynomial        PV2_0, PV2_1....PV2_20 possible
   ZEA     7    Zenithal equal area
   AIR     8    Airy                       pv2_1 required
   CYP     9    Cylindrical perspective    pv2_1 and pv2_2 required
   CAR    10    Cartesian
   MER    11    Mercator
   CEA    12    Cylindrical equal area     pv2_1 required
   xy    13    Conical perspective        pv2_1 and pv2_2 required
   COD    14    Conical equidistant        pv2_1 and pv2_2 required
   COE    15    Conical equal area         pv2_1 and pv2_2 required
   COO    16    Conical orthomorphic       pv2_1 and pv2_2 required
   BON    17    Bonne's equal area         pv2_1 required
   PCO    18    Polyconic
   SFL    19    Sanson-Flamsteed
   PAR    20    Parabolic
   AIT    21    Hammer-Aitoff
   MOL    22    Mollweide
   CSC    23    Cobe Quadrilateralized     inverse converges poorly
                Spherical Cube
   QCS    24    Quadrilateralized
                Spherical Cube
   TSC    25    Tangential Spherical Cube
   SZP    26    Slant Zenithal perspective  PV2_1,PV2_2, PV2_3 optional 

 OPTIONAL KEYWORD PARAMETERS:

       CTYPE - One, two, or three element vector containing 8 character 
               strings corresponding to the CTYPE1, CTYPE2, and CTYPE3 
               FITS keywords: 

               CTYPE[0] - first four characters specify standard system
               ('RA--','GLON' or 'ELON' for right ascension, galactic 
               longitude or ecliptic longitude respectively), second four 
               letters specify the type of map projection (eg '-AIT' for 
               Aitoff projection)
               CTYPE[1] - first four characters specify standard system
               ('DEC-','GLAT' or 'ELAT' for declination, galactic latitude
               or ecliptic latitude respectively; these must match 
               the appropriate system of ctype1), second four letters of 
               ctype2 must match second four letters of ctype1.
               CTYPE[2] - if present must be the 8 character string,'CUBEFACE',
                only used for spherical cube projections to identify an axis 
               as containing the face on which each x and y pair of 
               coordinates lie.
       FACE - a input variable used for spherical cube projections to 
               designate the face of the cube on which the x and y 
               coordinates lie.   Must contain the same number of elements
               as X and Y.
       CRVAL - 2 element vector containing standard system coordinates (the 
               longitude and latitude) of the reference point
       CRXY - 2 element vector giving the x and y coordinates of the 
               reference point, if this is not set the offset of the x 
               coordinate is assumed to be 0.
       LATPOLE -  native latitude of the standard system's North Pole
       LONGPOLE - native longitude of standard system's North Pole, default
               is 180 degrees, numeric scalar
       pv2_1 - scalar with first projection parameter (PV2_1), this may
               or may not be necessary depending on the map projection used
       pv2_2 - scalar with second projection parameter (PV2_2), this may
               or may not be necessary depending on the map projection used

 OUTPUT PARAMETERS:

       longitude - longitude of data, same number of elements as x, in degrees
       latitude - latitude of data, same number of elements as x, in degrees

       Longitude and latitude will be set to NaN, wherever elements of X,Y
       have no corresponding longitude, latitude values. 
 NOTES:
       The conventions followed here are described in more detail in the paper
      "Representations of Celestial Coordinates in FITS" by Calabretta &
       Greisen (2002, A&A, 395, 1077, also see 
       http://www.aoc.nrao.edu/~egreisen) .The general scheme
       outlined in that article is to convert x and y coordinates into a 
       "native" longitude and latitude and then rotate the system into one of 
       three generally recognized systems (celestial, galactic or ecliptic).

       This procedure necessitates two basic sections.  The first converts 
       x and y coordinates to "native" coordinates while the second converts 
       "native" to "standard" coordinates.  The first section contains the 
       guts of the code in which all of the map projection is done.  The 
       second step is performed by WCS_ROTATE and only involves rotation of 
       coordinate systems.  WCSXY2SPH can be called in a form similar to 
       AITOFF, EQPOLE, or QDCB by calling wcsxy2sph with a fifth parameter 
       specifying the map projection by number and by not using any of the 
       keywords related to the map projection type (eg ctype1 and ctyp2).

 PROCEDURE:
       The first task of the procedure is to do general error-checking to 
       make sure the procedure was called correctly and none of the 
       parameters or keywords conflict.  This is particularly important 
       because the procedure can be called in two ways (either using 
       FITS-type keywords or using a number corresponding a map projection 
       type).  All variables are converted into double precision values.

       The second task of the procedure is to take x and y coordinates and 
       convert them into "native" latitude and longitude coordinates.  
       Map-specific error-checking is done at this time.  All of the 
       equations were obtained from "Representations of Celestial 
       Coordinates in FITS" and cases needing special attention are handled 
       appropriately (see the comments with individual map projections for 
       more information on special cases).     WCS_ROTATE is then called to 
       convert the "native" coordinates to "standard" coordinates by rotating
       the coordinate system.  This rotation is governed by the keywords 
       CRVAL, and LONGPOLE.  The transformation is a straightforward 
       application of euler angles.  Finally, longitude values are converted 
       into the range from 0 to 360 degrees.

 CALLS: ***
	WCS_ROTATE
 COMMON BLOCKS:
       none
 PROCEDURES CALLED:
       WCS_ROTATE

 COPYRIGHT NOTICE:

       Copyright 1991, The Regents of the University of California. This
       software was produced under U.S. Government contract (W-7405-ENG-36)
       by Los Alamos National Laboratory, which is operated by the
       University of California for the U.S. Department of Energy.
       The U.S. Government is licensed to use, reproduce, and distribute
       this software. Neither the Government nor the University makes
       any warranty, express or implied, or assumes any liability or
       responsibility for the use of this software.

 AUTHOR:

       Rick Balsano

 MODIFICATIONS/REVISION LEVEL:

 1.1    8/31/93
 1.2    9/12/93   W. Landsman Vectorized CRXY, CRVAL, CTYPE
 1.3    29/12/93  I. Freedman Eliminated LU decomposition
 1.4    22/09/94  W. Landsman If scalar input, then scalar output
 1.5    02/03/05  W. Landsman Change variable name BETA for V4.0 compatibility
 1.6    06/07/05  W. Landsman Change loop index from integer to long
       Converted to IDL V5.0   W. Landsman   September 1997
 1.7    02/18/99  W. Landsman Fixed implementation of ARC algorithm
 1.8    June 2003 W. Landsman Update conic projections, add LATPOLE keyword
 1.81   Sep 2003 W. Landsman Avoid divide by zero 
 1.82   Sep 2003 W. Landsman CTYPE keywords need not be 8 characters
 1.83   Sep 2003 W. Landsman Preserve input array sizes
 1.9    Jan 2004 W. Landsman don't modify scalars, fix PARabolic code
 2.0    Feb 2004 W. Landsman Fix AIR and AZP projections
 2.1    Feb 2004 W. Landsman Fix tangent projection for matrix input
 3.0    May 2004  W. Landsman Support extended SIN (=NCP), slant zenithal
                  (SZP), and zenithal polynomial (ZPN) projections, use
                   PV2 keyword vector instead of PROJP1, PROJP2
 3.1    May 2004 W. Landsman/J. Ballet Handle NaN values, flag invalid output
                   for AITOFF projection
 3.1_smei Sep 2005 SJT: Remove invalid prints on Aitoff again -- it's
                                                                 nothing but a pest

 NAME:
	wedge_bounding_box
 PURPOSE:
	Calculate boundary and bounding box for a wedge specified as two points
	in polar coordinates
 CATEGORY:
	gen/idl/toolbox
 CALLING SEQUENCE:
	b_box = wedge_bounding_box(p_box [, center=center, wedge=wedge])
 INPUTS:
	p_box		array[2,2]; type: float
					limiting values in phase angle and radius of the wedge
					in the form [[angle1,radius1],[angle2,radius2]].
					Angle1 and angle2 are in radians between [-!pi,+!pi].
					The wedge runs counterclockwise from 'angle1' to 'angle2'
					over less than 180 degrees: either angle2 > angle1 with
					angle2-angle1 < !pi or angle2 < angle1 with
					angle+2*!pi-angle1 < !pi. Always radius1 < radius2.
 OPTIONAL INPUT PARAMETERS:
	center=center
				array[2]; type: float
					center in same units as the radius in p_box.
					This defines the center for the polar coordinates specified in p_box.
	dimension=dimension
				array[2]; type: integer
					size of full image. If present, these are used to modify b_box so
					that it contains valid indices into an array with these dimension
	/degrees	if set units of all angles are in degrees (default: radians)
 OUTPUTS:
	b_box		array[2,2]; type: integer
					corners of the smallest square in the image that completely encloses
					the wedge in pixel coordinates in the form [[x1,y1],[x2,y2].
					Always x1 <= x2, y1 <= y2.
 OPTIONAL OUTPUT PARAMETERS:
	wedge		array[2,n]; type: float
					boundary of wedge as a closed array (first=last point)
					in rectangular (pixel) coordinates.
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
+
 CALLS: ***
	CV_COORD, InitVar, IsType, REVERSE, ToRadians
 CALLED BY:
	even_light, qImage_cw_Wedge, wedge_content
 PROCEDURE:
	The bounding box usually refers to a subsection of a 2D image:
		img[b_box[0,0]:b_box[1,0],b_box[0,1]:b_box[1,1]]
	However, there is no guarantee that b_box lies inside the image, i.e.
	b_box[0,0] or b_box[0,1] might be negative, b_box[1,0] and b_box[1,1]
	might be larger than the image dimensions. Set the 'dimension' keyword to
	force the indices in b_box to be valid indices into the full image array.
 MODIFICATION HISTORY:
	FEB-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Extracted from qimage_cw_wedge.pro for use outside widget

 NAME:
	wedge_content
 PURPOSE:
	Calculates parameters for wedge in image plane
 CATEGORY:
	gen/idl/toolbox
 CALLING SEQUENCE:
	FUNCTION wedge_content, image, p_box, b_box=b_box, exclude_p_box=exclude_p_box,	$
		center=center, prorate=prorate,	degrees=degrees,							$
		zval=zval, centroid=centroid, p_centroid=p_centroid, wedge=wedge
 INPUTS:
	image 		array[n,m]; type: any
					2D-image array containing wedge
					b_box SET: image is the section of the original full
						image defined by the bounding box, i.e.
						image = full_image[b_box[0]:b_box[2],b_box[1]:b_box[3]]
					b_box NOT SET: image is the full image (the bounding box
						is calculated internally using p_box)
	p_box		array[2,2]; type: float
					limiting values in phase angle and radius of the wedge
					in the form [[angle1,radius1],[angle2,radius2]].
					The radius is specified in units of a pixel.
					Angle1 and angle2 are in radians between [-!pi,+!pi].
					The wedge runs counterclockwise from 'angle1' to 'angle2'
					over less than 180 degrees: either angle2 > angle1 with
					angle2-angle1 < !pi or angle2 < angle1 with
					angle+2*!pi-angle1 < !pi. Always radius1 < radius2.
 OPTIONAL INPUT PARAMETERS:
	b_box		array[2,2]; type: integer
					corners of the smallest square in the image that completely encloses
					the wedge in pixel coordinates in the form [[x1,y1],[x2,y2].
					Always x1 <= x2, y1 <= y2.
					Usually this is the output from wedge_bounding_box. If b_box is not
					specified then is calculated from p_box using the same function.
	exclude_p_box=exclude_p_box
				array[2,2; type: float
					another wedge specified in the same way as p_box.
					This wedge should lie completely inside the p_box wedge.
					If this box is specified then the return values refer to the
					area in between the two wedges. This box is passed unmodified to
					Inside_Wedge.
	center		array[2]; type: float
					center in pixel coordinates
					This defines the center for the polar coordinates specified in p_box.
	prorate=prorate
				array[2]; type: integer; default: [0,0] (no prorating)
					activates prorating of pixels straddling the boundary of the wedge
					as the number of subpixels in both dimension used to subdivide the
					boundary pixels. If the product of the two parameters is zero then
					no prorating is done (this is the default).
	/degrees	if set units of all angles are in degrees (default: radians)
 OUTPUTS:
	zpix		scalar; type: float or integer
					# pixels in wedge (non-integer values result from pro-rating)
					if the wedge is empty then zero is returned
 OPTIONAL OUTPUT PARAMETERS:
	zval		array[4]; float
					minimum, maximum, average and standard deviation across the wedge
					if the wedge is empty then 4 x !values.f_nan is returned
	centroid	array[2]; type: float
					centroid of the wedge in rectangular pixel coordinates
					if the wedge is empty then 2 x !values.f_nan is returned
	p_centroid=p_centroid
				array[2]; type: float
					centroid of the wedge in polar coordinates
					if the wedge is empty then 2 x !values.f_nan is returned

	wedge		array[2,n]; type: float
					boundary of wedge as a closed array (first=last point)
					in rectangular (pixel) coordinates (output from qImage_cw_Wedge)
					(will exist only if b_box was NOT set)
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	BadValue, CV_COORD, CenterOfMass, InitVar, Inside_Wedge, IsType, STDDEV, SuperArray
	gridgen, wedge_bounding_box
 CALLED BY:
	qImage_cw_ZWedge
 PROCEDURE:
 MODIFICATION HISTORY:
	FEB-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Split off from qImage_cw_zwedge for use outside the widget.

 NAME:
	WhatIs
 PURPOSE:
	Get info about variables
 CALLING SEQUENCE:
	WhatIs, a [,b,c,d,e,f,g,h]
 INPUTS:
	a,b,c,d,e,f,g,h
		any type of variable
 CALLS: ***
	IsType, WhatIs0
 CALLED BY:
	RemoteView_Display2D, RemoteView_PlotVertices, WhatIs0, even_light, qvu_whatis
	smei_frm_summary, smei_htm_testcase, smei_orient_test, smei_star_fit
	unitvectors, vox_read, vu_read, vu_whatis
 RESTRICTIONS:
	Number of arguments is restricted to a maximum of 8
 PROCEDURE:
	The routine WhatIs0 is used as an internal procedure
	(code included with WhatIs)

	WhatIs0, a, type, scalar, dims, amin, amax, cone
	a			any variable
	type		variable type
	scalar		0 if var is array, 1 if var is scalar
	dims		string containing dimensions
	amin		minimum value
	amax		maximum value
	cone		start of first element of string var
 MODIFICATION HISTORY:
	MAY-1995, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	WhatIs0
 PURPOSE:
	(Internal use only)
 CALLING SEQUENCE:
	WhatIs0, a, type, scalar, dims, amin, amax, cone
 INPUTS:
	a		any variable
	type		variable type
	scalar		0 if var is array, 1 if var is scalar
	dims		string containing dimensions
	amin		minimum value
	amax		maximum value
	cone		start of first element of string var
 CALLS: ***
	IsType, WhatIs
 CALLED BY:
	WhatIs
 RESTRICTIONS:
 PROCEDURE:
 MODIFICATION HISTORY:
	MAY-1995, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	where_common
 PURPOSE:
	Find common entries in a list as compared with a second reference list
 CATEGORY:
	Toolbox: generic	
 CALLING SEQUENCE:
	L = where_common(list, reflist, inref=inref, absent=absent, count=count)
 INPUTS:
	list			array; type: any
 OPTIONAL INPUT PARAMETERS:
	reflist			array; type: same as 'list'
 OUTPUTS:
	L				array; type: long integer
						indices in 'list' of elements that are also present in 'reflist'
						if no common elements are found then -1 is returned
 OPTIONAL OUTPUT PARAMETERS:
	count			scalar; type: long integer
						# common elements in 'list' (in common with 'reflist')
	inref			array; type: long integer
						indices in 'reflist' of common elements
	absent			array; type: long integer
						indices in 'list' that are not in common with 'reflist'
						i.e. the complementary list of indices.
 INCLUDE:
	@compile_opt.pro			; On error, return to caller
 CALLED BY:
	FindAllFiles, FindPeaks, big_body, big_eph, big_eph_short, boost, findfile_fix
	flt_format, jpl_body, mpc_body, qLine_Sequence, sgp_body, smei_buf_getframe
	smei_frm_base, smei_frm_get, smei_frm_property, smei_getfile, smei_sky_read
	smei_star_alias, smei_star_list, usno_body, vu_insitu_raw, vu_new_time
	www_help_crosslinks, www_help_names, www_help_verify_name
 PROCEDURE:
	If the reference list contains duplicate values the first entry is used.
 MODIFICATION HISTORY:
	MAR-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	who_am_i
 PURPOSE:
	Returns file name of procedure calling this function
 CATEGORY:
	gen/idl/toolbox/files	
 CALLING SEQUENCE:
	FUNCTION who_am_i, env=env, directory=directory, procedure=procedure, caller=caller 
 INPUTS:
	(none)
 OPTIONAL INPUTS:
	/procedure	if set, the name of the calling IDL procedure is returned
					(in lowercase!!)
	/directory	if set, only the directory of the calling function is returned
	env=env		scalar; type: string
					name of environment variable
					if full file name starts with this environment
					variable is replaced by ~ in the returned value
 OUTPUTS:
	Result		scalar; type: string
					full path to the file calling this function
 INCLUDE:
	@compile_opt.pro                ; On error, return to caller
 CALLS: ***
	FILEPATH, GetFileSpec, InitVar
 CALLED BY:
	CvSky, RemoteView_Colors, RemoteView_rgbo, jpl_init, jpl_test, mpc_body, mpc_eph
	nso_fe_start, qImage_cw_Where, sgp4_eph, sgp4_tlm, sgp_body, smei_base_testcase
	smei_buf_read, smei_coriolis, smei_cv_catalogue, smei_frm_base, smei_frm_drive
	smei_frm_flatfield, smei_frm_hbar, smei_frm_hbar_inside, smei_frm_path
	smei_frm_property, smei_frm_read, smei_frm_rebin, smei_htm_testcase
	smei_mkstdstar, smei_roi_mask, smei_setup_roi, smei_sgp4_orbits, smei_star_list
	smei_star_standard, smeidb_mounted, usno_body, usno_test, www_help_get_info
	www_help_section
 PROCEDURE:
	Uses IDL help, /call command
 MODIFICATION HISTORY:
	SEP-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	wso_read
 PURPOSE:
	Read file with Stanford synoptic map data into 2D array
 CATEGORY:
	gen/idl/util
 CALLING SEQUENCE:
	FUNCTION wso_read, wsofile, Y,  $
		_extra		= _extra	, $
		rotation	= rotation	, $
		longitude	= longitude , $
		cvariable	= cvariable , $
		align		= align 	, $
		header		= header	, $
		todegrees	= todegrees , $
		padto90 	= padto90	, $
		dropfirst	= dropfirst , $
		droplast	= droplast	, $
		fill		= fill		, $
		badfillvalue= badfillvalue, $
		errormessage= errormessage
 INPUTS:
	wsofile			scalar; type: string
						name of WSO data file
 OPTIONAL INPUTS:
	align=align 	scalar; type: integer; default: not set
						longitude at start of array.
						Used to rearrange the first (longitudinal) dimension of
						the array to put longitude 'align' at the start of the
						array.
	todegrees=todegrees
					if 30 numbers per longitude are read the grid is assumed to
					have equal steps of sine(latitude) from -14.5/15 to +14.5/15
					If /todegrees is set this is converted to 29 equal steps in
					latitude from -70 to +70 degrees in steps of 5 degrees
					(using spline interpolation).
	padto90=padto90
					If 29 numbers per longitude are read (or 30 with /todegrees
					set) the grid is assumed to cover -70 to +70 degrees in
					steps of 5 degrees. If /padto90 is set then 4 rows of bad
					values are added to the top and bottom of the array so that
					the grid covers -90 to +90 degrees.

	/dropfirst		remove the first longitude (as stored in input file)
	/droplast		remove the last longitude (as stored in input file)
						the output array will have only 72 longitudes.
	/fill			fill bad values read from file by a call to gridfill or set
						them to badfillvalue (if set).
						This only applied to bad values read from the data file;
						NOT for the padding to +/- 90 degrees if /padto90 is set.
	badfillvalue=badfillvalue
					scalar; type: float; default: none
						used to fill bad values (NaNs) if keyword /fill is set
 OUTPUTS:
	status			scalar; type: integer
						return status (0=Failure,1=Success)
	map				2D-array[N,M]; type: float
						map=-1 if status=0
						2D magnetic field map (in units stored on file)
						N=73, M=30: equal steps in sine(latitude) from -14.5/15 to +14.5/15
						N=73, M=29: equal steps in latitude from -70 to +70 degrees
						N=73, M=37: equal steps in latitude from -90 to +90 degrees
									(with 4 rows of bad data at top and bottom)
						The first dimension stores data in order of increasing
						heliographic longitude (i.e. later data first).
						The second dimension stores data in order of increasing
						latitude.
 OPTIONAL OUTPUTS:
	rotation=rotation
					array[N]; type: integer
						Carrington rotation for each column in Z
	longitude=longitude
					array[N]; type: integer
						heliographic longitude for each column in Z
	cvariable=cvariable
					array[N]; type: double
						Carrington variable = rotation+(1-longitude/360)
						If keyword align is used then this array is NOT in
						monotonic decreasing order anymore !!!
	header=header	scalar or array; type: string
						records preceeding the magnetic data.
						(May not exist on return).
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 RESTRICTIONS:
	The most recent synoptic map on the WSO map sites could be incomplete.
	In that case the returned array Z will contain less than 73 longitudes
 CALLS: ***
	BadValue, FXPAR [1], FXPAR [2], GetFileSpec, InitVar, IsType, READFITS [1]
	READFITS [2], READFITS [3], REVERSE, TimeSplit, TimeString, TimeUnit, boost, flt_read
	gridfill, gridgen, hide_env
 PROCEDURE:
	The output array covers 360 degrees in longitude (not necessarily starting
	at 0 degrees) and -90 to +90 in latitude in steps of 5 degrees.
	The data only extend up to +/-70 degrees latitude, i.e the top and bottom
	four rows are filled with bad values.

	The input map maps may be in equal steps of sine(latitude). These are
	converted to equal steps in latitude by cubic spline interpolation.
 MODIFICATION HISTORY:
	NOV-2002, Paul Hick (UCSD/CASS)
	JAN-2003, Paul Hick (UCSD/CASS)
		Added /fill and bad fillvalue keywords to fill bad values (NaNs).
		These were set to zero before.
	OCT-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Added check for bad values of -9999.90 in the WSO files.
		The NOAA files occasionally use this value to fill missing data. These
		are set to BadValue() in the output array by flt_read.
	MAY-2006, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		If keyword 'OBSTIME' is not found then the time assigned to the file
		is extracted from keyword 'UTLAST' (in Feb 2006 the Fits header were
		changed and OBSTIME is now store in UTLAST, it seems.

 NAME:
	wso_write
 PURPOSE:
	Write magnetic field data array in format of ascii WSO files
 CATEGORY:
	gen/idl/util
 CALLING SEQUENCE:
	PRO wso_write, data_file, data, cvariable=cvariable, rotation=rotation, 		$
		longitude=longitude, header=header, fill=fill, badfillvalue=badfillvalue,	$
		addfirst=addfirst, addlast=addlast, 										$
		hdr_append=hdr_append, data_append=data_append, obstime=obstime
 INPUTS:
	data_file	scalar; type: string
					
	data		array[N,30]; type: float
					N=72 or N=73; magnetic field data
 OPTIONAL INPUT PARAMETERS:
	rotation=rotation
					array[N]; type: integer
						Carrington rotation for each column in Z
	longitude=longitude
					array[N]; type: integer
						heliographic longitude for each column in Z
	cvariable=cvariable
					array[N]; type: double
						Carrington variable = rotation+(1-longitude/360)
	/addfirst		only used if N=72
	/addlast		only used if N=72
						If there are only 72 longitudes we need to add one
						extra longitude
						If /addfirst is set then add a copy of the last longitude
						at the start of the file (with rotation decreased by one).
						If /addlast is set then add a copy of the first longitude
						at the end of the file (with rotation increased by one)
	header=header	scalar or array; type: string
						is added to the start of the file
	/fill			before writing to file, bad values (NaNs) are filled using gridfill
						or is set to badfillvalue (if set).
						If no filling is done then bad values are written as 'NaN'.
						(Xuepus program produces isolated NaNs, mostly close to the current sheet.
						A badfillvalue of zero is the easiest way to get rid of these).
	badfillvalue=badfillvalue
					scalar; type: float; default: none
						used to set bad values (NaNs) is keyword /fill is set
 OUTPUTS:
	(written to file 'data_file')
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	AngleRange, FXADDPAR [1], FXADDPAR [2], GetFileSpec, InitVar, IsType, MKHDR [1]
	MKHDR [2], REVERSE, WRITEFITS [1], WRITEFITS [2], destroyvar, flt_string, gridfill
 SEE ALSO:
	wso_read
 PROCEDURE:
	Data for each of the N longitudes are written in four lines using
	format = '(A2,I4.4,A1,I3.3,8X,6F9.3,3(/,8F9.3))'

	Each group of four records starts with a string CTrrrr:lll
	where rrrr is the Carrington rotation number (from keyword rotation
	or integer part of cvariable) and lll the heliographic longitude
	(from keyword longitude or the fraction of cvariable.

	Longitudes are written from large to small heliographic longitudes
	(i.e. earlier data first). Latitudes are written from North to South.

	Keyword cvariable takes precedence over keywords rotation and longitude
	(these keywords will usually be output from wso_read)
 MODIFICATION HISTORY:
	NOV-2002, Paul Hick (UCSD/CASS)
	JAN-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Bug fix. The routine replicated the wrong record at the end of the file
		when the number of longitudes in data is 72.
		Added /fill keyword.
	MAY-2003, Paul Hick (UCSD/CASS)
		Added /addfirst and /addlast keywords. The default is /addlast, so
		without the keywords the routine behaves as before.
	DEC-2003, Paul Hick (UCSD/CASS)
		Added option to write fits file (if extension of output file is
		.fts, .fit, or .fits). Also allowed appending extra map from keywords
		hdr_append and data_append. This is used primarily to append the
		original photospheric synoptic magnetic field map to the source surface
		map produces by Xuepues hcss program.
	OCT-2006, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Added obstime keyword

 NAME:
	wvalid
 PURPOSE:
	Check whether a window index refers to an existing window
 CATEGORY:
	Environment
 CALLING SEQUENCE:
	B = wvalid(window_index)
 INPUTS:
	index		scalar; type: integer
 OUTPUTS:
	B			scalar; type: byte
					0 if window does not exist
					1 if window exists
 CALLED BY:
	twin
 PROCEDURE:
	Uses catch error handler to check whether wset is
	executed without causing an error.
 MODIFICATION HISTORY:
	JUL-2000, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	www_help
 PURPOSE:
	Extract headers from source code files. Locations of source code can
	be specified as regular files or directories, or (vms only) as text libraries.
	An html-based help system is created from the headers.
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	www_help, files, paths=paths, destination=destination
 INPUTS:
	files			array; type: string
						list of files. These may include directory specification
						and a wildcard in the file name. On VMS text libraries
						are permitted.
	paths=paths		array; type: string
						list of directories to be searched

	destination = destination
					scalar; type: string
						The name of the directory for the html files

	The 'files' and 'paths' arguments are passed unmodified to FindAllFiles.
	Several other arguments are permitted to modify file selection.
	These are explained in FindAllFiles:

	/recursive
	/symlink
	excl_files=excl_files
	excl_paths=excl_paths
	excl_recursive=excl_recursive

 OPTIONAL INPUT PARAMETERS:
	style=style		array[1]; type: structure
						One of the structures returned from the procedure
						www_help_style. The structure content is described
						there. Defaults are available for several types of source
						code (e.g. IDL and Fortran) with several options for
						changing defaults.

	list=list		scalar; type: string
						name of file containing list of valid section headings.
						Usually valid section headings are set using information
						in the 'style' keyword (see www_help_section). This
						keyword overrides that selection.;
	cgi_bin=cgi_bin
					scalar; string; default: none
						directory where web server looks for cgi files.
						Typically has the form:
							server.domain.edu/cgi-bin/
						This is the directory where the python script
						www_help.cgi should be installed. If this keyword is
						specified the file name in the html files will be
						hyperlinks to the cgi script. If not specified these
						links are not created.

	email=email		array; type: string
						list of email addresses. If any of these addresses is
						found it is converted to an html link

	swap_style=swap_style
					array[n]; type: structure
						same layout as keyword style
						adds a linkto enable swapping to the help system for
						 another group of source files.

	/add_corpses	if set then files containing no headers are added with a
					dummy header (this only makes sense if the cgi-script
					www_help.cgi is working to provide access to the source code).

	/automatic		EXPERIMENTAL: can only be used for IDL code.
					If set then first an attempt is mode to get a list of referenced
					procedures and function by a call to www_help_get_info.
					If this fails then the information in the CALLS section is used.

	tempdir=tempdir	directory to be used for storing scratch files. Only needed
					if keyword /automatic is set.
					(alternatively, set environment variable 'www_help')

	Two keywords are passed unmodified to www_help_crosslinks.
	These control how information from other www_help collections in the
	same destination directory are used to create hyperlinks.

	incl_sets=incl_sets
					array; type: string
	excl_sets=excl_sets
					array; type: string

 OUTPUTS:
	(number of html files)
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	CheckDir, InitVar, IsType, www_help_crosslinks, www_help_files, www_help_make
	www_help_master, www_help_section, www_help_style
 CALLED BY:
	www_help_rsi
 RESTRICTIONS:
	Has not been tested on VMS
	On VMS text libraries are processed by extracting modules into SYS$TEMP.
	After processing these files are deleted.
 PROCEDURE:
 >	For each header the fully-qualified file name of the corresponding file is
	put in the html file. If the keyword cgi-bin is used then the file name
	becomes a link to the cgi-script $SSW_SMEI/gen/python/www_help.cgi, which
	will try to pull up the actual source code. The script is assumed to accessible
	at the server specified in cgi-bin.

 >	The www_help package depends on the a couple of procedures not included
	with the package itself:
	CheckDir, FindAllFiles, FindAllSubDirs, GetFileSpec, IsSymLink, os_separator
	SetFileSpec, strposn, SyncDims, where_common

 >	For more information check the file sections_ssw.txt (should be located in the
	same directory as this file).
 MODIFICATION HISTORY:
	JAN-2001, Paul Hick (UCSD/CASS)
	JUN-2001, Paul Hick (UCSD/CASS); added /anycase keyword.
		See www_help_get_header for more information.
	JAN-2002, Paul Hick (UCSD/CASS)
		Added cgi-bin keyword
		Added /automatic mode for IDL code. Now at V2.1
		Added /automatic mode for Fortran code. Now at V2.2.
			Note that this requires the program ftnchek. The current
			setup only works for Fortran code in the SSW_SMEI tree.
	FEB-2002, Paul Hick (UCSD/CASS)
		Added keyword 'mask' to www_help_make. This allows correct processing of a
		whole software tree while creating separate catalogues for each branch
		below the top level directory and cross-referencing of procedures
		across the whole tree (i.e. also between branches). See www_help_tree.
		Now at V2.3.
	JUN-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Couple of bug fixes in www_help_files. Streamlined www_help_tree.
		Now at V2.5

 NAME:
	www_help_add_header
 PURPOSE:
	Add header information to list of header
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	no_header = www_help_add_header(name, header, origin, style, section, is_incl, lines
 INPUTS:
	name
	header			array; type: structure
						all the headers. One header will be added to the list.
	origin			array[2]; type: string
						string array describing location of source code
						origin[0] : full name of the source file or text library
						origin[1] : the module name when processing a library
	style
	section
	is_incl			set to 1 if the header was extracted from an include file (*.h)
	lines			all lines in the header
 OUTPUTS:
	no_header		scalar; type: integer
						always zero
	header			array; type: structure
						list of headers; one more than the input list.
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	www_help_clean
 CALLED BY:
	www_help_get_header
 PROCEDURE:
	Each header is stored in a structure of the form

	tmp = {HEADER_INFO,			$
		name	: name,			$			; Procedure name
		link	: link,			$			; Link name (=name visible on screen)
		flink	: flink,		$			; Full html link of form <a "file.htm#link">link</a>
		version	: version,		$			; Non-zero for duplicate entries (used in link name)
		origin	: origin,		$			; Full file name of source file
		is_incl	: is_incl,		$			; 1 if the file was an include file
		auto	: 0,			$			; 1 if CALLS section determined automatically
		calls	: ***
	www_help_clean
 MODIFICATION HISTORY:
	FEB-2002, Paul Hick (UCSD/CASS)
	JUL-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Fixed bug setting up header.flink for the first version of a module
		when multiple versions exist.

 NAME:
	www_help_break
 PURPOSE:
	Break list of html links into lines with effective width of ~80 chars
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	www_help_break, vis_name, htm_name, content, header
 INPUTS:
	vis_name		array; type: string
						list of names as they will appear in a browser
						i.e. without the html directives
	htm_name		array; type: string
						list of links, including the html directives
	content			array; type: string
						current content
	header			array; type: structure
						structure with header info
	this_section		scalar; type: string
						name of section being processed
						(only used if /checkdups is set)
 OPTIONAL INPUT PARAMETERS:
	/checkdups		print a message if duplicate routine names are found
					in the CALLS and SEE ALSO sections.
 OUTPUTS:
	content			array; type: string
						same as input array with extra lines at the end
						containing the htm_name links
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	UNIQ [1], UNIQ [2], UNIQ [3]
 CALLED BY:
	www_help_called_by, www_help_names
 RESTRICTIONS:
	'content' must exist on entry
 PROCEDURE:
 >	The accumulated # chars in vis_name determine where the list
	is broken into length of effective length close to 80 chars.
 >	A comma is inserted between the entries on a line.
 >	In the output list the entries are sorted
 MODIFICATION HISTORY:
	JAN-2001, Paul Hick (UCSD/CASS)
	SEP-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Suppress warning message for very long word (with no white space)
		if it contains an hmtl hyperlink.

 NAME:
	www_help_called_by
 PURPOSE:
	Add a CALLED BY, INCLUDE BY or EXTERNAL BY section to the headers.
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	on = www_help_called_by(line, ithis, header, mask, section, iu, htm, letter, srce_section, dest_section, calls)
 INPUTS:
	line			scalar; type: string
						header line
	ithis			scalar; type: integer
						header number (index into array 'header')
	header			array; type: structure
						structure with header info
	mask
	section			array; type: string
						list of valid section headings
	content			array; type: string
						collect html lines
	style			array[1]; type: structure
						defined in www_help
						used: style.html_name, style.html_type
	letter			scalar; type: string
						initial letter of name of current htm output file
	srce_section		scalar; type: string
						section providing 'calls' information (CALLS, INCLUDED, EXTERNAL)
	dest_section		scalar; type: string
						name of new section to be created (CALLED BY,
						INCLUDED BY or EXTERNAL BY)
	calls			scalar; type: pointer to heap variable
						contains information from all CALLS section
						(created by www_help_get_calls)
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 OPTIONAL INPUT PARAMETERS:
	/force			setting this keyword forces writing of the CALLED BY section
 OUTPUTS:
	on			scalar; type: byte
					0: CALLED BY section not yet written
					1: CALLED BY section written

	(output to html file)
 CALLS: ***
	InitVar, www_help_break, www_help_is_section, www_help_is_text
 CALLED BY:
	www_help_make
 PROCEDURE:
 >	Called by www_help_make for every line in the header looking for a spot
	to write the CALLED BY section.
 >	The CALLED BY section is inserted in front of 'line' as soon as 'line'
	contains one of the section headings listed after CALLS. This should result
	in inserting the CALLED BY section immediately after the CALLS section.
 >	Returning on=1 indicates that the CALLED BY section was written for header 'ithis'
	and www_help_make will not call this procedure again for 'ithis'.
 >	Returning on=0 indicates that the CALLED BY section was not written and
	www_help_make will call this procedure again with the next line from the header.
 >	The /force keyword will write the CALLED BY section unconditionally. This is
	used by www_help_make if after processing the entire header the CALLED BY section
	is still not written.
 MODIFICATION HISTORY:
	JAN-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	www_help_calls
 PURPOSE:
	Adds the content of 'line' to the information from all CALLS sections
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	on = www_help_calls(style, line, ithis, header, section, calls=calls)
 INPUTS:
	style			array[1]; type: structure
						www_help_style structure
						passed to www_help_is_text and www_help_is_code
	line			scalar; type: string
						line of CALLS section from header ithis
	ithis			scalar; type: integer
						header index (index into header array)
	header			array; type: structure
						structure with header info
	section			array; type: string
						list of valid section headings
	calls=calls		scalar; type: pointer to heap variable
						information from CALLS section
						the pointer points to an array of structures
 OUTPUTS:
	calls=calls		scalar; type: pointer to heap variable
						updated information from CALLS section
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	www_help_is_code, www_help_is_text, www_help_ptr
 CALLED BY:
	www_help_get_calls
 PROCEDURE:
	This procedure is called by www_help_get_calls after the start of the CALLS
	section of header 'ithis' is detected. For the first call 'line' is the first
	line of the section. www_help_get_calls keeps feeding subsequent lines until the return
	value of this procedure indicates that the end of the section has been reached.

	The entries into 'calls' are structures defined as follows
	*calls = {www_help_called,
		name:name,							index of procedure header into 'header' array
		called_by:ptr_new(/allocate))}		headers that have 'name' in their CALLS section.

 MODIFICATION HISTORY:
	JAN-2001, Paul Hick (UCSD/CASS)
	FEB-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Put management of the 'calls' heap variable in a separate subroutine www_help_ptr

 NAME:
	www_help_calls_file
 PURPOSE:
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	www_help_calls_file, name, nline, line
 INPUTS:
 OUTPUTS:
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS:
 CALLED BY:
	www_help_make
 PROCEDURE:
 MODIFICATION HISTORY:
	JUN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	www_help_change_tabs
 PURPOSE:
	Changes text written with tab length of tab_len_from to text
	with a tab length of tab_len_to
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	R = www_help_change_tabs(line, tab_len_from, tab_len_to)
 INPUTS:
	line			scalar; type: string
						string to be checked; the comment char at the
						beginning of the line has already been stripped.
 OPTIONAL INPUT PARAMETERS:
	tab_len_from	scalar; type: integer; default: 4
	tab_len_to		scalar; type: integer; default: 8
 OUTPUTS:
	R				scalar; type: string
						updated value of input value of 'line'
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	InitVar
 CALLED BY:
	www_help_get_header
 PROCEDURE:
	In the IDL editor a tab is usually set to 4 spaces.
	HTML usually sets a tab equal to 8 spaces. This procedure
	changes from IDL to HTML format while retaining text alignment.
 MODIFICATION HISTORY:
	JAN-2001, Paul Hick (UCSD/CASS)
	JUN-2001, Paul Hick (UCSD/CASS); fixed a bug which crashed the procedure when
		processing a line containing just a single tab.
	MAY-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Changed to process lines with comment char already removed instead
		of still present.

 NAME:
	www_help_check
 PURPOSE:
	Check for miscellaneous links to be created in the headers
	- substrings of the form 'href=entry=' are converted to a link to 'entry'
	- email addresses are converted to mailto links
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	pro www_help_check, header, htm, email, crosslinks
 INPUTS:
	header		array; type: structure
					all the headers
	mask		array; type: integer
					list of indices into 'header'. Only the headers on
					this list are processed
	style		array[1]; type: structure
					defined in www_help, passed to www_help_check_marker
	email		array; type: string
					list of email addresses to search for
	crosslinks
 OUTPUTS:
	header		array; type: structure
					updated headers
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	WWW_HELP_MAILTO, www_help_check_marker
 CALLED BY:
	www_help_make
 RESTRICTIONS:
	This procedure should only make fixes to individual header line
	(in particularly, the order of the headers processed should not matter)
 PROCEDURE:
	Three types of links are created.
	1.	Entries in the 'email' list are turned into a 'mailto' hyperlink.
	2.	Strings of type 'href=entry=' are replaced by an html link.
		If the first letter of 'entry' is the same as 'letter' (case-insensitive)
		the the replacement string '<a href="#entry">entry</a>'
		If the first letter is not the same then the replacement string is
		'<a href=file#entry">entry</a>' where 'file' is constructed from htm and letter:
		file = html_name_'letter'.html_type

	Only the first links are created in this procedure. The others are done
	by calling www_help_check_marker.
 MODIFICATION HISTORY:
	JAN-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	www_help_check_marker
 PURPOSE:
	Checks headers for special marker HREF=name=.
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	R = www_help_check_marker(line, cref, style, firschar, subject, header)
 INPUTS:
	line			scalar; type: string
						header line to be checked for markers
	cref			scalar; type: string
						marker string, e.g. 'href' (without trailing equal sign)
	style			array[1]; type: structure
						defined in www_help
						used: style.html_name, style.html_type
	subject			scalar; type: string
						subject name of current header (used in message)
	header
	crosslinks
 OUTPUTS:
	R				scalar; type: string
						input 'line' with markers replaced by hyperlinks
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLED BY:
	www_help_check
 PROCEDURE:
	If a marker is found, check for a header in 'header' and, if present, in 'crosslinks'
 MODIFICATION HISTORY:
	MAR-2001, Paul Hick (UCSD/CASS)
	SEP-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Suppresed warning message when an http link is encountered to prevent
		it from being identified as an unmatched header entry.

 NAME:
	www_help_clean
 PURPOSE:
	Replaces any occurrence of HTML reserved characters (<,>,&,")
	with the appropriate HTML counterpart.
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	www_help_clean, txt
 INPUTS:
	txt		array; type: string
				text to be checked
 OUTPUTS:
	txt		array; type: string
				updated input array
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLED BY:
	www_help_add_header
 PROCEDURE:
 >	Ampersands:			 &  --->	&amp.
	Since ampersands are special HTML characters this replacement must be done first.
 >	Left angle brackets: <	---> &lt;
 >	Right angle brackets:>  ---> &gt;
 > Double quotes		 "  --->  &quot;
 MODIFICATION HISTORY:
	JAN-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	www_help_crosslinks
 PURPOSE:
	Reads links of links to other www_help collections in the same
	destination directory.
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	www_help_crosslinks, destination, style, crosslinks
 INPUTS:
	destination		scalar; type: string
						destination directory of html files
	style			array[1]; type: structure
						www_help_style structure
 OPTIONAL INPUT PARAMETERS:
	incl_sets   = incl_sets
					list of catalogues to be read
					if not specified all catalogues are read
	excl_sets = excl_sets
					list of catalogues to be excludee

	/keep_style		by default the current catalogue is not read.
					Override this by setting this keyword.
 OUTPUTS:
	crosslinks		array[2,n]; type: string
						array of links read from the catalogues
						array[0,*]: names of all routines
						array[1,*]: corresponding html links
						If no catalogues were read the array doesn't exist
 OPTIONAL OUTPUT PARAMETERS:
	list=list		array[n]; type: string
						names of all catalogues (similar to entries
						style.html_name) read
						If no catalogues were read the array doesn't exist
	files=files		array[n]; type: string
						fully-qualified files of all catalogue files read
						If no catalogues were read the array doesn't exist
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	FILEPATH, GetFileSpec, IsType, SetFileSpec, destroyvar, hide_env, strposn
	where_common
 CALLED BY:
	www_help, www_help_master
 PROCEDURE:
 >	Information is collected from files in the destination directory
	matching the template '*_list.htm'.

 >	By default all files are read except for the master list
	'master_list.htm' and the list associated with the current list
	style.html_name+'_list.htm'.

 >	Set 'include_sets' to read a specific subset of lists
	Note that the return crosslinks array respects the order specified
	in 'include_sets'.

 >	Set 'excl_sets' to exclude specific lists

 >	Keyword /keep_style puts the current list back into the mix.

 >	Information is collected by reading all lines starting with <li> from
	the *_list.htm files.
 MODIFICATION HISTORY:
	FEB-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	www_help_files
 PURPOSE:
	Extract headers from source code files. Locations of source code can
	be specified as regular files or directories, or (vms only) as text libraries.
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	nhdr = www_help_files(style, section, files, paths=paths, header, /nosort)
 INPUTS:
	style			array[1]; type: structure
						One of the structures returned from the procedure
						www_help_style. The structure content is described
						there. Defaults are available for several types of source
						code (e.g. IDL and Fortran) with several options for
						changing defaults.
	section			array; type; string
						list of valid section headings

	files			array; type: string
						list of files. These may include directory specification
						and a wildcard in the file name. On VMS text libraries
						are permitted.
	paths=paths		array; type: string
						list of directories to be searched

	The 'files' and 'paths' arguments are passed unmodified to FindAllFiles.
	Several other arguments are permitted to modify file selection.
	These are explained in FindAllFiles:

	/recursive
	/symlink
	excl_files=excl_files
	excl_paths=excl_paths
	excl_recursive=excl_recursive

	header		array; type: structure
					if this array exists on input (from previous calls to this
					function) then new headers will be added at the end of the array.
 OPTIONAL INPUT PARAMETERS:
	/add_corpses	if set then files containing no headers are added with a dummy header
					(this only makes sense if the cgi-script www_help.cgi is working to
					provide access to the source code).
	/nosort		by default the headers are sorted using header.name and header.version
					The sorting can be suppressed with the /nosort keyword (useful mainly when
					this function is used to accumulate headers with several calls in sequence.
 OUTPUTS:
	nhdr		scalar; type: integer
					# headers (= n_elements(header))
	header		array; type: structure
					all the header information
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	FindAllFiles, GetFileSpec, InitVar, SetFileSpec, hide_env, www_help_get_header
 CALLED BY:
	www_help, www_help_tree
 RESTRICTIONS:
	Has not been tested on VMS
	On VMS text libraries are processed by extracting modules into SYS$TEMP.
	After processing these files are deleted.
 PROCEDURE:
 >	The start of a new section is in general defined by an uppercase word with a trailing
	colon (no whitespace). Only section headings read from the template file are
	recognized. For SSW the rules for detecting section headings are more relaxed.
 >	All lines in the header start with the string style.commentchar.
	Headers start with the line style.start_char and end with style.stop_char.
	Files may contain more than one header.
 >	For more information see the file sections_ssw.txt (should be located in the
	same directory as this file).
 MODIFICATION HISTORY:
	JAN-2001, Paul Hick (UCSD/CASS)
	JAN-2002, Paul Hick (UCSD/CASS)
	JUN-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Fixed bug for case where no files are found (would return nhdr=0
		instead of n_elements(header)).
		Fixed bug with use of keyword /nosort (sorting would be skipped if
		no files are found).

 NAME:
	www_help_frames
 PURPOSE:
	Defines the html frame layout of www_help
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	frame = www_help_frames, name, first_set, type
 INPUTS:
	name		scalar; type: string
					name of the www_help catalogue
					(usually style.html_name)
	first_set	scalar; type: string
					name of the html file to be displayed in the text window.
					Identifies the www_help catalogue (usually the same as
					'name' with postfixed a two character string of the form
					'_a', identifying the 1st letter for which headers are
					present in the catalogue
	type		scalar: type: string
					file extension of html files
					(usually style.html_type)
 OUTPUTS:
	frame		array; type: string
					html strings defining the frame
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLED BY:
	www_help_make, www_help_master
 PROCEDURE:
	Returns html lines starting with <frameset ...> and ending
	with </frameset>
 MODIFICATION HISTORY:
	FEB-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	www_help_get_calls
 PURPOSE:
	Controls collection of information from all CALLS sections
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	www_help_get_calls, header, section, calls=calls
 INPUTS:
	style			array[1]; type: structure
						www_help_style structure
						style.automatic and style.html_top[1] are used
						Also passed to www_help_is_section and www_help_calls
						(which use style.anycase and style.commentchar)
	header			array; type: structure
						all the headers
	section			array; type: string
						list of valid section headings
	this_section		scalar; type: string
						entry from 'section' array for CALLS
						INCLUDE or EXTERNAL section.
 OUTPUTS:
	calls=calls		scalar; type: pointer to heap variable
						information from all CALLS sections
	header			if style.automatic is set the automatically determined
					list of called procedures is added to header.calls.
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	www_help_calls, www_help_get_info, www_help_is_section
 CALLED BY:
	www_help_make
 PROCEDURE:
	Looks for 'this_section' in each header, and stores the information in 'calls'.
	The content of the 'calls' structure is described in www_help_calls.
 MODIFICATION HISTORY:
	JAN-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	www_help_get_header
 PURPOSE:
	The input file is searched for headers. The file may contain more than one header.
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	www_help_get_header, source, header, origin, style, section, /add_corpses
 INPUTS:
	source			scalar; type: string
						fully qualified file name
	header			array; type: structure
						all the headers. New headers will be added to the list.
	origin			array[2]; type: string
						string array describing location of source code
						origin[0] : full name of the source file or text library
						origin[1] : the module name when processing a library
	style			scalar; type: string
						comment character
	section			array; type: string
						list of valid section headings
	/add_corpses
 OPTIONAL INPUT PARAMETERS:
	/add_corpses	if set then files containing no headers are added with a dummy header
					(this only makes sense if the cgi-script www_help.cgi is working to provide
					access to the source code).
 OUTPUTS:
	header		array; type: structure
					updated array of headers
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	GetFileSpec, InitVar, SetFileSpec, hide_env, www_help_add_header
	www_help_change_tabs, www_help_is_section, www_help_is_text
	www_help_verify_name
 CALLED BY:
	www_help_files
 SIDE EFFECTS:
	When processing a library module (origin[1] ne '')
	the source file 'source' is deleted after processing.
 RESTRICTIONS:
	Include files are detected by their extension .h or by the
	string _common in the name. This is weak.
 PROCEDURE:
 >	A header is defined as all lines between an opening line start_char 
	and a closing line stop_char

 >	The name field is filled by searching for the section string 'NAME:'.
	The procedure name follows this section heading.

	Unless style.anycase is set 'NAME:' must be in uppercase with no
	whitespace preceeding the colon, and the procedure name must be on the
	line following the line containing 'NAME:

	If style.anycase is set then 'NAME:' can be lower-, upper- or mixed case;
	whitespace preceding the colon is permitted, and the procedure name can
	be on the same line as 'NAME:'. Also one extra empty line after NAME: may
	be included.

	If no procedure name is found, then the file name is used instead.
 MODIFICATION HISTORY:
	JAN-2001, Paul Hick (UCSD/CASS)
	JUN-2001, Paul Hick (UCSD/CASS)
		added style.anycase keyword to handle SSW code Setting style.anycase
		handles several variations of the ways the procedure name is specified:
		- NAME: can be lower, upper or mixed case (default: uppercase only)
		- There can be whitespace between NAME and : (default: no whitespace)
		- The name of the procedure can be on the same line with NAME: (default: next line)
	MAY-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Moved call to www_help_change_tabs down one line (after removal of comment char
		from header line). This improves processing of headers with code in it.

 NAME:
	www_help_get_info
 PURPOSE:
	Tries to find all functions and procedures used in 'name'
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	line = www_help_get_info(name [, path, search_path, count=count])
 INPUTS:
	name		scalar; type: string
				name of IDL procedure or function
	path		scalar; type: string
				fully-qualified name of file containing 'name'
	search_path	scalar; type: string
				Only used when processing IDL code.
				Defines the IDL path used to resolve 'name'.
 OUTPUTS:
	line		array; type: string
				list of procedures and functions called by 'name'
				list is set to the null string if none are found
 OPTIONAL OUTPUT PARAMETERS:
	count=count	scalar; type: integer
				# functions/procedures called by 'name'
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	FILEPATH, GetFileSpec, SetFileSpec, UNIQ [1], UNIQ [2], UNIQ [3], who_am_i
 CALLED BY:
	www_help_get_calls
 SEE ALSO:
	www_help_info
 RESTRICTIONS:
	Needs shell used by www_help_shell (currently csh)
	A temporary file is created in $www_help, i.e. environment variable 'www_help'
	must be set to a directory with write acess. If 'www_help' is not set
	program execution stops (this is done in www_help_style).
 PROCEDURE:
	Convoluted.
	1. Write 'path' and 'name' into file $www_help/www_help.info
	2. Spawn shell script www_help_shell. This sets IDL_STARTUP to the null string,
	   then starts IDL main program www_help_info.pro.
	3. The IDL main program does four things:
	   a. reads 'path' and 'name' from $www_help/www_help.info
	   b. uses 'path' to set the IDL !path variable
	   c. uses the IDl procedures resolve_routine and routine_name to get the
	      list of routines and functions
	   d. writes the number of modules found and a comma separated list of 
	      module names back into $www_help/www_help.info
	4. After the spawned process completes the final $www_help/www_help.info
	   is read again to fill the return variables count and list.
 MODIFICATION HISTORY:
       FEB-2002, Paul Hick (UCSD/CASS)
       DEC-2003, Paul Hick (UCSD/CASS)
			Updated code that looks for the executably ftnchek.
			On Unix the 'which' command is used first. After that
			$SSW_SMEI_UCSD/gen/exe/<os> is checked. For Windows only the
			last location is checked.
	JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Fixed bug in processing output from ftnchek. To find the list of
		function called by a function/subroutine FUNC a line containing
		'FUNC calls:' was looked for. This would pick up any function ending
		with FUNC. Now the string 'FUNC calls:' is looked for at the beginning
		of a line output by ftnchek.

 NAME:
       www_help_info
 PURPOSE:
	IDL main program to retrieve list of procedures/function
	referenced by a given IDL procedure/function
 CATEGORY:
       www_help
 CALLING SEQUENCE:
       idl www_help_info
 INPUTS:
 OUTPUTS:
 CALLS:
	www_help_info_sub
 SEE ALSO:
	www_help_get_info
 RESTRICTIONS:
	No IDL functions or procedures should be called prior to the call
	to routine_info in in www_help_info_sub.
 PROCEDURE:
 > 	Program does several things:
		a. reads 'path' and 'name' from $www_help/www_help.info
		b. uses 'path' to set the IDL !path variable
		c. uses the IDl procedures resolve_routine and routine_name to get the
		   list of routines and functions
		d. writes the number of modules found and a comma separated list of
		   module names back into $www_help/www_help.info
		e. If something went wrong a line is written to $www_help/www_help.error
		   with a best guess at what went wrong.
 >     See www_help_get_info for more information
 >     All IDL messages are dumped to /dev/null
 >     Currently the main program is executed from a bash script www_help_bash
       after IDL_STARTUP is cleared. If there is a way to force IDL to ignore
       IDL_STARTUP at starup then then the bash script can be bypassed.
 MODIFICATION HISTORY:
       FEB-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	www_help_info_sub
 PURPOSE:
	Collect info from call to IDL procedure resolve_routine
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	www_help_info_sub, name, path, file_name, n, list, /flag, /skip
 INPUTS:
	name		scalar; type: string
					name of procedure of function
	path		scalar; type: string
					fully-qualified name of file containing 'name'
 OUTPUTS:
	n			scalar; type: integer
					# entries in 'list'
	list		array[n]; type: string
					list of names of procedures and functions called by
					'name'
 OPTIONAL OUTPUTS:
	flag=flag	scalar; type: string
					status message; null string is all is well
	skip=skip	scalar; type: string
					name of file with list of procedures to be skipped
					(mostly because they are so buggy IDL crashes when
					trying to compile them).
 INCLUDE:
	@compile_opt.pro			; On error, return to caller
 CALLED BY:
	www_help_info
 SEE ALSO:
	www_help_get_info
 PROCEDURE:
 > This procedure should not call any other function in order not
	to mess up the results from the resolve_routine call.
 MODIFICATION HISTORY:
	FEB-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
	JUN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Added strcompress to catch sillyness like tabs and multiple spaces
		in the procedure/function declaration.

 NAME:
	www_help_is_code
 PURPOSE:
	Checks wheter 'line' is an external or include declaration, or a
	comma-separated list of names.
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	is_code = www_help_is_code(style, line, name, front, back)
 INPUTS:
	style		array[1]; type: structure
					www_help_style structure
					Only used style.commentchar
	line		scalar; type: string
					text line from header
 OUTPUTS:
	is_code		scalar; type: integer
					0: not a line of code
					1; is a line of code
	name		scalar or array: type: string
					if is_code=1 then name will be a scalar containing
					the name of the include or extenal module
					if is_code=0 then name is an array containing the
					entries in a comma-separated list (as found in a CALLS
					of SEE ALSO section).
	front		scalar: type: string
	back		scalar: type: string
					if is_code is 1 then 'name' is the name of the
					file used in the include and external statements.
					'front' and 'back' returns the leading and trailing
					parts of 'line'.
					if is_code is 0 then neither will exist
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS:
	destroyvar
 CALLED BY:
	www_help_calls, www_help_names
 PROCEDURE:
	Trivial
 MODIFICATION HISTORY:
	FEB-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	www_help_is_section
 PURPOSE:
	Tests a header for the presence of a specific section header
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	FUNCTION www_help_is_section, style, section, lines
 INPUTS:
	style			array[1]; type: structure
						www_help_style structure
						Only uses style.anycase
	section			scalar; type: string
						section heading
	lines			array; type: string
						all lines from a documentation header
 OUTPUTS:
	Result			scalar; type: integer
						-1: if not start of section
						otherwise index into 'lines' where section starts
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLED BY:
	www_help_called_by, www_help_get_calls, www_help_get_header, www_help_is_text
	www_help_make
 PROCEDURE:
	If style.anycase is not set, then the header a case-sensitive search for lines
	containing the specified section heading anywhere in the line is done.
	If style.anycase is set, then the search is case insensitive; the section heading
	must be at the beginning of the line, and whitespace before the trailing colon is
	permitted.
 MODIFICATION HISTORY:
	JULY-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	www_help_is_text
 PURPOSE:
	Check wheter a line from a header is part of the
	documentation (i.e. does not contain a section header)
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	B = www_help_is_text(style, line, section)
 INPUTS:
	style		array[1]; type: structure
					www_help_style structure
					(passed to www_help_is_section)
	line		scalar; type: string
					text string from a documentation header
	section		array; type: string
					array with valid section headers
 OUTPUTS:
	B			scalar: type: byte
					0: line is not documentation (contains header)
					1: line is documentation (does not contain header)
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	www_help_is_section
 CALLED BY:
	www_help_called_by, www_help_calls, www_help_get_header, www_help_names
 PROCEDURE:
	Checks whether 'line' contains a section heading by checking
	'line' for the presence of one of the elements in array 'section'.
 MODIFICATION HISTORY:
	JUNE-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	www_help_make
 PURPOSE:
	Build a .HTML help system from source code headers
 CATEGORY:
 CALLING SEQUENCE:
	www_help_make, header, htm, title
 INPUTS:
	destination		scalar; type: string
						destination directory for the html files
	header			array; type: structure
						all the headers
	section			array; type: string
						list of valid section headings
	style			array[1]; type: structure
						defined in www_help
						used: style.html_name, style.html_type, style.title
	cgi_bin=cgi_bin		scalar; string; default: none
						directory where web server looks for cgi files.
						This is the directory where www_help.cgi should reside.
 OPTIONAL INPUT PARAMETERS:
	mask=mask		array; type: integer
					array with index numbers of 'header' to be processed
	swap_style=swap_style
					array[1]; type: structure
						if specified than a link is added to enable swapping
						to the help system for another group of source files.
	copyright=copyright
					scalar; type: text: dfault: none
					name of text file containing a copyright notice.
						The file name should be located in the destination directory, and
						should be given the name <prefix>_copyright.txt. The <prefix> will be
						used to set up a link to the copyright notice.
	email=email		array; type: string
						list of email addresses. If any of these addresses is found it
						is converted to an html link
	crosslinks=crosslinks
 OUTPUTS:
	(bunch of html files)
 INCLUDE:
	@compile_opt.pro				; On error, return to caller
	@www_help_version.pro			; Defines version
 CALLS: ***
	FILEPATH, InitVar, IsType, WWW_HELP_MAILTO, strposn, www_help_called_by
	www_help_calls_file, www_help_check, www_help_frames, www_help_get_calls
	www_help_is_section, www_help_names, www_help_ptr
 CALLED BY:
	www_help, www_help_tree
 PROCEDURE:
 >	The htm[0] is used as prefix for the name of all html files
 >	All html files have extension htm[1]
 >	All html files are created in the directory specified in htm[2]

 >	The following html files are created:
	(name = htm[0]; htm = htm[1]

	name_frames.htm		defines the frames for the help system
	name_alphabet.htm	a list of all letters providing links to the
						first header with a name starting with that letter
						(case-insensitive)
	name_list.htm		a list of all headers with names in alphabetical orders.
						Each name is a link to the corresponding header.
	name_a.htm, name_b.htm, name_c.htm, etc.
						contains the headers with name starting with the
						corresponding letters.

 > The current layout has three frames
	- one frame along the top containing name_alphabet.htm
	- one frame along the left containing name_list_htm.
		This frame is the target for links in the top frame.
	- one frame along the right containing the name_a.htm, etc. files
		This frame is the target for links in the left frame
 MODIFICATION HISTORY:
	JAN-2001, Paul Hick (UCSD/CASS)
	JAN-2002, Paul Hick (UCSD/CASS)
		Fixed bug in html file defining frames. The text frame would try to
		load the documentation for letter A even if the file doesn't exist.
		Now the file for the first letter that is present is loaded.
	MAR-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Added option to include copyright notice.

 NAME:
	www_help_master
 PURPOSE:
	Recreate the master help file for 'destination'
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	www_help_master, destination, style
 INPUTS:
	destination		scalar; type: string
						destination directory of html files
	style			array[1]; type: structure
						www_help_style structure
 OUTPUTS:
	(html file for master catalogue to destination directory)
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
	@www_help_version.pro	; Defines version
 CALLS: ***
	FILEPATH, IsType, WWW_HELP_MAILTO, www_help_crosslinks, www_help_frames
 CALLED BY:
	www_help, www_help_tree
 PROCEDURE:
	All catalogues in the destination directory (*_list.htm) files
	are combined into a single master catalogue. Hyperlinks to all
	of the individual catalogues are also provided.
 MODIFICATION HISTORY:
	FEB-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	www_help_names
 PURPOSE:
	Sets up links for CALLS, SEE ALSO, INCLUDE and EXTERNAL sections
	and writes them to an html file
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	on = www_help_names(iline, line, ithis, header, mask, section, content, style, letter, linkout)
 INPUTS:
	iline		scalar; type: integer
					# current line in header 'ithis'
	line		scalar; type: string
					string to be checked
	ithis		scalar; type: integer
					header index (index into header array)
	header		array; type: structure
					structure with header info
	mask
	section		array; type: string
					list of valid section headings
	this_section	scalar; type: string
					name of current section being processed
	content		array; type: string
					collect html lines
	style		array[1]; type: structure
					defined in www_help
					used: style.html_name, style.html_type
	letter		scalar; type: string
					single character. MUST be lowercase
	linkout		scalar; type: pointer to heap variable
					saves the CALLS information
 OUTPUTS:
	linkout		scalar; type: pointer to heap variable
					updated CALLS information
					(linkout is used only internally, and is put in the argument
					only to avoid having to use a common block.
 INCLUDE:
	@compile_opt.pro			; On error, return to caller
 CALLS: ***
	strposn, where_common, www_help_break, www_help_is_code, www_help_is_text
 CALLED BY:
	www_help_make
 PROCEDURE:
	Individual lines from the CALLS or SEE ALSO sections are fed to this procedure.
	The routine names in each line are converted to links and stored in 'linkout',
	if at least one matching emtry is found in 'header' or 'crosslinks'.

	First 'header' is checked. If no match is found then 'crosslinks' is checked.
	If multiple entries are found a number is added to the name of routine as
	it will appear on the screen.

	When a line is fed containing a section header, the information in 'linkout'
	is written to an html file.
 MODIFICATION HISTORY:
	JAN-2001, Paul Hick (UCSD/CASS)
	JAN-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu; added 'crosslinks' check

 NAME:
	www_help_ptr
 PURPOSE:
	Manages 'calls' structure
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	www_help_ptr, calls, name, ithis
	www_help_ptr, calls, /free
 INPUTS:
	calls		heap variable
 OPTIONAL INPUT PARAMETERS:
	name		list of header indices of procedures called by 'ithis'
	ithis		index of header begin processed
	/free		if set all heap variables are destroyed
 OUTPUTS:
	calls		updated heap variable (destroyed if /free is set)
 INCLUDE:
	@compile_opt.pro                ; On error, return to caller
 CALLS: ***
	boost
 CALLED BY:
	www_help_calls, www_help_make, www_help_tree
 PROCEDURE:
	The entries into 'calls' are structures defined as follows
	*calls = {www_help_called,
		name:name,			index of procedure header into 'header' array
		called_by:ptr_new(/allocate))}	headers that have 'name' in their CALLS section.
 MODIFICATION HISTORY:
       FEB-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Introduced another heap variable in the 'calls' structure. 'calls'
		is a heap variable containing an array of structures. Each
		structure element contains another heap variable. Cleaning up of
		all heap variable is now done by this procedure using keyword /free.

 NAME:
	www_help_rsi
 PURPOSE:
	Creates html help files for IDL lib directory
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	www_help_rsi
 INPUTS:
	(none)
 OPTIONAL INPUTS:
	destination=destination
				scalar; type: string; default: $SSW_SMEI/html/help/smei/
	cgi_bin=cgi_bin
				scalar; type: string; default: http://cass185.ucsd.edu/cgi-bin/
					location of cgi scripts
	remote_dir=remote_dir
				scalar; type: string
					if set then all *.html files from 'destination' are copied to 'ftp'
					The remote directory is specified in the form host:directory
					e.g.: cassfos02.ucsd.edu:/u8/WWW/solar/help/smei/
					The transfer is done by ftp; whether the ftp works or not is the users
					responsibility.
 OUTPUTS:
	(html files are created in 'destination')
 INCLUDE:
	@compile_opt.pro                ; On error, return to caller
 CALLS: ***
	CheckDir, FILEPATH, InitVar, IsType, do_file, www_help, www_help_style
 PROCEDURE:
	Subdirectory lib in !DIR is scanned recursively for
	*.pro files. The subdir 'obsolete' is excluded.
 MODIFICATION HISTORY:
	JAN-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	www_help_section
 PURPOSE:
	Get list of valid section headings
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	FUNCTION www_help_section, style, list=list
 INPUTS:
	style			array[1]; type: structure
						as defined by www_help_style
						Only field style.sect_type is used
 OPTIONAL INPUT PARAMETERS:
	list=list		scalar; type: string
						name of file containing list of valid headings. If the
						file is not found then a list of default headings is used
						(see PROCEDURE).
 OUTPUTS:
	Result			array; type: string
						array of valid section headings
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	FILEPATH, hide_env, who_am_i
 CALLED BY:
	www_help, www_help_tree
 SEE ALSO:
	www_help_style
 PROCEDURE:
	The list of valid section headings is determined using the following steps:

	1.	Pick a file to read. First try to find the file specified in 'list'
		If 'list' is not specfied or does not exist, pick one of the default
		files based on the structure field style.sect_style. Currently four
		lists with section headings are available in the same directory where
		the www_help code is located. They are selected by setting
		style.sect_style to one of the values::
			'pro'	: sections_pro.txt		for IDL code
			'for'	: sections_for.txt		for Fortran code
			'c'		: sections_c.txt		for C code
			'dpp'	: sections_cpp.txt		for C++ code
			'script': sections_script.txt	for scripts (bash, python, or any
						other code that uses '#' as comment character)
			'ssw'	: sections_www.txt		for IDL code (adapted for SSW)
		(the file names match the template 'sections_'+style.sect_style+'.txt')

	2.	If an error occurs trying to read the file selected in step 1 resort to
		to a set of default section headers (these are hardcoded in this procedure).
		The default is pretty much the same as used in standard IDL headers.
		Most noticeable is the omission of a CALLS and a SEE ALSO section, i.e.
		the resulting html files will NOT contain hyperlinks for any procedure
		names put in these sections.

	3.	When reading the file all lines containing a colon (':') are assumed to be
		sections headings. Even though this is not strictly necessary it is
		probably best to stick to uppercase for all section headings.
 MODIFICATION HISTORY:
	JAN-2001, Paul Hick (UCSD/CASS)
	DEC-2001, Paul Hick (UCSD/CASS)
		Changed the expected location of the template files with section headings
		from $pro to $SSW_SMEI.
	JAN-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Changed the expected location of the template files to the directory of the
		www_help package. The package does not depend any environment variables anymore

 NAME:
	www_help_style
 PURPOSE:
	Defines style structure for several languages
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	style = www_help_style([/idl, /ssw, ...])
 OPTIONAL INPUT PARAMETERS:
	/fortran		returns Fortran style structure
	/idlcode		returns IDL style structure
	/c_code			returns C style structure
	/cppcode		returns C++ style structure
	/script			returns script style structure
	/sswcode		returns SSW style structure (modified IDL style)

	No more than one of the above keywords must be selected to set a default style.
	If none is specified the /idlcode is assumed.
	The following keywords modify some of the fields in the style structure.

	tabsize=tabsize
					scalar; type: integer; default: 8
					modifies style.tabsize field

	html_name=html_name
					scalar; type: string; default
					modifies style.html_name

	html_top=html_top
					array[2]; type: string; default
					sets style.html_top

	title=title		scalar; type: string; default: value of style.html_name
					modifies style.title

	/anycase		sets style.anycase
					If anycase is not set than an internally defined default
					is used (for SSW it will still be on).

	/automatic		sets style.automatic
					only used if /idlcode or /sswcode is set
 OUTPUTS:
	style		array[1]; type: structure
					style structure used as input to www_help
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	InitVar
 CALLED BY:
	www_help, www_help_rsi, www_help_tree
 PROCEDURE:
	Defines and fills a named structure {www_help_style}

	commentchar : comment character (';')
				  used in www_help_get_header to distinguish code from comments

	sect_type	: used in www_help_section to locate a list of
				  valid section headings ('pro')

	tabsize		: maximum number of space characters corresponding to tab character
				  used in www_help_get_header to replace tabs with the appropriate
				  number of spaces. In www_help_make this number is also
				  added to the hyperlink for the file name as an argument to passed
				  to the cgi-script www_help.cgi.

	html_type	: extension used for html files ('.htm')
				  used in the same places as style.html_name for the same reasons:
				  www_help_make, www_help_names, www_help_check_marker
				  and www_help_called_by

	html_name	: primarily used as prefix for the names of html files ('pro').
				  It is used in www_help_make (which creates the html
				  files and www_help_names, www_help_check_marker and
				  www_help_called_by (which create hyperlinks to headers).

				  As a secondary use it sets the defaults for style.title
				  (converted to uppercase)

				  Also used for crosslinking with other help systems???

	html_top	: if a help system is created for software in a given directory tree
				  the name of the top directory can be specified here as a shorthand
				  replacement html_top[0] (e.g. 'SSW') and a fully-qualified
				  directory name html_top[1] (typically these will be the name and
				  value of an environment variable). In the html help files the name
				  of the top directory is replaced by style.html_top[0] (with a
				  dollar sign prefixed).

				  Note that for the cgi-script www_help.cgi to be able to reconstruct
				  the full file name the line
						$html_top[0]=html_top[1]
				  needs to be added to the auxilliary file www_help.lst

	title		: title for help pages
				  Written to html file in www_help_make. Used in www_help
				  for displaying message on screen.

	anycase		: if set then checking for sections is case insensitive. The keyword
				  also affects the way the name of a procedure is tracked down.
				  See www_help_get_header and sections_ssw.txt for more information.
				  Used by www_help_get_header and www_help_is_section.

	automatic	: can only be used for IDL and Fortran code.
				If set then the information in the CALLS section is ignored and instead
				www_help_get_info is used to determine which procedures and functions
				are referenced by a particular module.
				This option is only accepted if:
				- either /idlcode or /sswcode is set
				- html_top[1] is set to a (hopefully) valid directory
				- environment variable 'www_help' is set.
 MODIFICATION HISTORY:
	JAN-2001, Paul Hick (UCSD/CASS)
	JAN-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Added html_top keyword
	JAN-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
		Added calls_file keyword

 NAME:
	www_help_tree
 PURPOSE:
	Creates html help files for IDL software in a directory tree
	(defaults are set up to process the SSW tree on cass185.ucsd.edu)
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	www_help_tree, tree, destination, master
 INPUTS:
	destination		scalar; type: string
						destination directory of all html files
	tree			scalar; type: string; default: getenv('SSW')
						top directory
	master			scalar; type: string; default: 'SSW'
						name of the master catalogue
 OPTIONAL INPUT PARAMETERS:
	cgi_bin=cgi_bin		scalar; type: string; default: http://cass185.ucsd.edu/cgi-bin/
					directory where web server looks for cgi files.
					Typically has the form:
						server.domain.edu/cgi-bin/
					This is the directory where the python script
					www_help.cgi should be installed. If this keyword is
					specified the file name in the html files will be
				 	hyperlinks to the cgi script. If not specified these
					links are not created.

	email=email		array; type: string; default: pphick@ucsd.edu
			    		list of email addresses. If any of these addresses is found it
			    		is converted to an html link
 OUTPUTS:
	(html files)
 INCLUDE:
	@compile_opt.pro		; On error, return to caller
 CALLS: ***
	FILEPATH, FindAllSubDirs, InitVar, IsType, TimeOp, TimeString, TimeSystem, TimeUnit
	os_separator, strposn, www_help_files, www_help_make, www_help_master
	www_help_ptr, www_help_section, www_help_style
 CALLED BY:
	run_ssw, run_ssw_smei
 PROCEDURE:
	Directory tree is recursively searched for source code files *.pro.
	Separate catalogues are created for all subdirectories in tree
	with one master catalogue.
 MODIFICATION HISTORY:
	JAN-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	www_help_verify_name
 PURPOSE:
	Checks whether a string is a valid name for an IDL procedure
 CATEGORY:
	www_help
 CALLING SEQUENCE:
	PRO www_help_verify_name, name, source
 INPUTS:
	name		scalar; type: string
					name of procedure
	source		scalar; type: string
					name of source file containing code for 'name'
 OUTPUTS:
	name		scalar; type: string
					blank string if input name is invalid; otherwise unmodified
 INCLUDE:
	@compile_opt.pro			; On error, return to caller
 CALLS: ***
	where_common
 CALLED BY:
	www_help_get_header
 PROCEDURE:
	The purpose of this routine is to intercept any weird mistakes in IDL
	headers. Current checks are pretty kludgy, Needs work.

 >	Leading and trailing whitespace is trimmed.
 >	Extension .pro is trimmed
 >	Only letters, digits and a few other characters (underscore, space) are permitted
 MODIFICATION HISTORY:
	JULY-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu)

 NAME:
	www_help_version
 PURPOSE:
	Include file for www_help package containing current version number
 MODIFICATION HISTORY:
	OCT-2006, Paul Hick (UCSD/CASS; pphick@ucsd.edu)