[Previous]
[Next]
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:
FUNCTION wedge_bounding_box, p_box, $
center = center , $
wedge = wedge , $
degrees = degrees , $
dimension = dimension
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:
Result 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, stardistance, 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
[Previous]
[Next]
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, stardistance
PROCEDURE:
MODIFICATION HISTORY:
FEB-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Split off from qImage_cw_zwedge for use outside the widget.
[Previous]
[Next]
NAME:
WhatIs
PURPOSE:
Get info about variables
CALLING SEQUENCE:
PRO WhatIs, a,b,c,d,e,f,g,h, title=title
INPUTS:
a,b,c,d,e,f,g,h
any type of variable
OPTIONAL INPUTS:
title=title informational message to be printed first
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
IsType, WhatIs0
CALLED BY:
ColorEloTimeBox, GetColors [2], GetColors [3], PRO bold, PRO bolstrip
PRO test_magnify, PlotEarthSkymap [3], PlotEarthSkymap [4], Plot_Helios_Br
Plot_g_level1, Plot_velocity, RemoteView_PlotVertices, WhatIs0, aurora, compipsd, cv
cvgrd, cvgrd_skymap, dusan_earth, even_light, grdout, ipsv [1], ipsv [2], ipsv [3]
make_r2_density, miscfig, mpc_minor_planets, pkt_read, plot_traffic, plotcolumns
qvu_whatis, show_wso, smei_findobj, smei_frm_summary, smei_frm_where
smei_mkc3mask, smei_normal, smei_orient_test, smei_rmdups, smei_sky
smei_sky_testcase, smei_star_fitone, smei_zld_dumbbell, smei_zld_model
smei_zld_weekly, smei_zldsky, spokes, test_dumbbell, test_sky, test_td, testnic
testsmei, thomsonfig, tryg, trypleiades, ulysses_passage, unitvectors, view3d, vlist
vox_read, vu_extract, vu_read, vu_select, vu_thomson_antifish, vu_thomson_hammer
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)
DEC-2009, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added keyword /title
[Previous]
[Next]
NAME:
WhatIs0
PURPOSE:
(Internal use only)
CALLING SEQUENCE:
PRO WhatIs0, a, type, scalar, dims, amin, amax, cone, name, finiteratio, zeroratio
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
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
IsType, WhatIs
CALLED BY:
WhatIs
RESTRICTIONS:
PROCEDURE:
MODIFICATION HISTORY:
MAY-1995, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
where_common
PURPOSE:
Find common entries in a list as compared with a second reference list
CATEGORY:
gen/idl/toolbox
CALLING SEQUENCE:
FUNCTION where_common, list, reflist, $
inref = inref , $
absent = absent , $
count = count , $
contains= contains
INPUTS:
list array; type: any
reflist array; type: same as 'list'
OPTIONAL INPUT PARAMETERS:
/contains by default strictly identical entries are detected.
If /contains is set then a test for entries in 'reflist"
that contain substrings 'list' is done.
OUTPUTS:
Result 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
CALLS: ***
InitVar
CALLED BY:
FindAllFiles, FindPeaks, TimePosn_test, big_body, big_eph, big_eph_short, boost, clean
findfile_fix, flt_format, forecast, jpl_body, mpc_body, mpc_comets
mpc_minor_planets, mpc_packed_date, qLine_Sequence, sgp_body, smei_buf_getframe
smei_frm_base, smei_getfile, smei_property, smei_rmdups, smei_star_alias
smei_star_fit, smei_star_list, smei_star_show, smei_star_test, txt_block_read
usno_body, vu_insitu_persist, vu_insitu_raw, vu_losmap, 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)
MAY-2008, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added keywor /contains
[Previous]
[Next]
NAME:
where_overlap
PURPOSE:
Compares two set of numerical ranges and determines
where the two sets overlap. The set of overlapping
ranges is returned. Optionally, the input ranges
are returned with the overlaps removed.
CATEGORY:
CALLING SEQUENCE:
FUNCTION where_overlap, r1_,r2_, $
overlap = overlap_ , $
nn1 = nn1 , $
rr1 = rr1_ , $
nn2 = nn2 , $
rr2 = rr2_
INPUTS:
r1_,r2_ array[2,n] or array[2]
two sets of numerical ranges specified
as pairs of start and end points
OUTPUTS:
result scalar; integer
number of pairs in the set of overlapping ranges
OPTIONAL OUTPUT PARAMETERS:
overlap=overlap
array[2,overlap], or aray[2]
nn1=nn1 # pairs in 1st set after removal of overlaps
rr1=rr1 array[2,nn1], or aray[2]
1st set after removal of overlaps
nn2=nn2 # pairs in 2nd set after removal of overlaps
rr2=rr2 array[2,nn2], or aray[2]
2nd set after removal of overlaps
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
destroyvar, merge_ranges
CALLED BY:
ark_duty_cycle
PROCEDURE:
Both input ranges are first reduced in merge_ranges
MODIFICATION HISTORY:
APR-2013, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
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:
CheckDir, CvSky, RemoteView_Colors, RemoteView_rgbo, SyncArgs, ark_duty_cycle
cvsmei, do_file, fileset_sizes, flip_colors, forecast_html, forecast_info
ipv6_packets, jpl_init, jpl_test, mpc_body, mpc_comets, mpc_eph, mpc_eph_range
mpc_minor_planets, nso_fe_start, physics_constant, qImage_cw_Where, say, sgp4_eph
sgp4_tle, sgp_body, smei_base_testcase, smei_buf_read, smei_coriolis
smei_cv_catalogue, smei_filepath, smei_frm_base, smei_frm_darkfit
smei_frm_drive, smei_frm_flatfield, smei_frm_hbar, smei_frm_read, smei_frm_rebin
smei_mkdrives, smei_mkstdstar, smei_property, smei_roi_mask, smei_setup_roi
smei_sgp4_orbits, smei_sky_testcase, smei_star_list, smei_star_standard
smeidb_mounted, telescope_sizes, 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)
[Previous]
[Next]
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
CALLED BY:
show_wso
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, GetFileSpec, InitVar, IsType, READFITS, REVERSE, TimeGet, TimeSet
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)
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.
[Previous]
[Next]
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, GetFileSpec, InitVar, IsType, MKHDR, REVERSE, WRITEFITS
destroyvar, flt_string, gridfill
CALLED BY:
xhcs
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)
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
[Previous]
[Next]
NAME:
wvalid
PURPOSE:
Check whether a window index refers to an existing window
CATEGORY:
Environment
CALLING SEQUENCE:
FUNCTION wvalid, window_index
INPUTS:
index scalar; type: integer
OUTPUTS:
B scalar; type: byte
0 if window does not exist
1 if window exists
INCLUDE:
@compile_opt.pro ; On error, return to caller
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)
[Previous]
[Next]
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:
PRO www_help, files, header, $
paths = paths , $
destination = destination , $
style = style , $
swap_style = swap_style , $
list = list , $
email = email , $
cgi_bin = cgi_bin , $
update_master = update_master , $
tempdir = tempdir , $
copyright = copyright , $
_extra = _extra
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, www_help_smei, www_help_test
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)
Couple of bug fixes in www_help_files. Streamlined www_help_tree.
Now at V2.5
SEP-2007, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added code to write function/prodedure name, file name,
and CALLS, INCLUDE, SEE ALSO and EXTERNAL section into
a plain text file. Required modifications to www_help_make
and www_help_names.
[Previous]
[Next]
NAME:
www_help_add_header
PURPOSE:
Add header information to list of header
CATEGORY:
www_help
CALLING SEQUENCE:
FUNCTION 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:
result 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 : calls, $ ; Comma separated list of called procedure (the CALLS section)
nline : nline, $ ; # lines in header
lines : ptr_new(lines, /no_copy)} ; Header lines
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.
[Previous]
[Next]
NAME:
www_help_break
PURPOSE:
Break list of html links into lines with effective width of ~80 chars
CATEGORY:
www_help
CALLING SEQUENCE:
PRO www_help_break, vis_name, htm_name, content, header, this_section, checkdups=checkdups
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
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.
[Previous]
[Next]
NAME:
www_help_called_by
PURPOSE:
Add a CALLED BY, INCLUDE BY or EXTERNAL BY section to the headers.
CATEGORY:
www_help
CALLING SEQUENCE:
FUNCTION www_help_called_by, line, ithis, header, mask, section, content, style, letter, $
srce_section, dest_section, calls, force=force
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)
[Previous]
[Next]
NAME:
www_help_calls
PURPOSE:
Adds the content of 'line' to the information from all CALLS sections
CATEGORY:
www_help
CALLING SEQUENCE:
FUNCTION www_help_calls, style, line, ithis, header, section, this_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
[Previous]
[Next]
NAME:
www_help_calls_file
PURPOSE:
CATEGORY:
www_help
CALLING SEQUENCE:
PRO www_help_calls_file, style, header
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)
[Previous]
[Next]
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:
FUNCTION 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.
[Previous]
[Next]
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:
gen/idl
CALLING SEQUENCE:
PRO www_help_check, header, mask, style, 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_check_marker, www_help_mailto
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)
DEC-2006, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Encoded email address.
[Previous]
[Next]
NAME:
www_help_check_marker
PURPOSE:
Checks headers for special marker HREF=name=.
CATEGORY:
www_help
CALLING SEQUENCE:
FUNCTION www_help_check_marker, line, cref, style, subject, header, crosslinks
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.
[Previous]
[Next]
NAME:
www_help_clean
PURPOSE:
Replaces any occurrence of HTML reserved characters (<,>,&,")
with the appropriate HTML counterpart.
CATEGORY:
www_help
CALLING SEQUENCE:
PRO 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: & ---> &.
Since ampersands are special HTML characters this replacement must be done first.
> Left angle brackets: < ---> <
> Right angle brackets:> ---> >
> Double quotes " ---> "
MODIFICATION HISTORY:
JAN-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
www_help_crosslinks
PURPOSE:
Reads links of links to other www_help collections in the same
destination directory.
CATEGORY:
www_help
CALLING SEQUENCE:
PRO www_help_crosslinks, destination, style, crosslinks, list, files, $
incl_sets =incl_sets , excl_sets=excl_sets, keep_style=keep_style
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)
[Previous]
[Next]
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:
FUNCTION www_help_files, style, section, files, header, paths=paths, $
add_corpses=add_corpses, nosort=nosort, _extra=_extra
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).
[Previous]
[Next]
NAME:
www_help_frames
PURPOSE:
Defines the html frame layout of www_help
CATEGORY:
www_help
CALLING SEQUENCE:
FUNCTION 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)
[Previous]
[Next]
NAME:
www_help_get_calls
PURPOSE:
Controls collection of information from all CALLS sections
CATEGORY:
www_help
CALLING SEQUENCE:
PRO www_help_get_calls, style, header, section, this_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)
[Previous]
[Next]
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:
PRO www_help_get_header, source, header, origin, style, section, add_corpses=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.
[Previous]
[Next]
NAME:
www_help_get_info
PURPOSE:
Tries to find all functions and procedures used in 'name'
CATEGORY:
www_help
CALLING SEQUENCE:
FUNCTION 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, 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.
[Previous]
[Next]
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)
[Previous]
[Next]
NAME:
www_help_info_sub
PURPOSE:
Collect info from call to IDL procedure resolve_routine
CATEGORY:
www_help
CALLING SEQUENCE:
PRO www_help_info_sub, name, path, file_name, n, list, flag=flag, skip=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)
JUN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added strcompress to catch sillyness like tabs and multiple spaces
in the procedure/function declaration.
[Previous]
[Next]
NAME:
www_help_is_code
PURPOSE:
Checks whether 'line' is an external or include declaration, or a
comma-separated list of names.
CATEGORY:
www_help
CALLING SEQUENCE:
FUNCTION 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)
[Previous]
[Next]
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)
[Previous]
[Next]
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:
FUNCTION 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: ***
IsType, 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)
[Previous]
[Next]
NAME:
www_help_mailto
PURPOSE:
Encode emai address for insertion in web page
CATEGORY:
gen/idl
CALLING SEQUENCE:
FUNCTION www_help_mailto, email, href, titletitle, subject=subject
INPUTS:
email scalar; type: string; default: none
if no email address is specified then the
null string is returned
OPTIONAL INPUT PARAMETERS:
/href if set, return full HTML mailto string, i.e.
<a "mailto:email?subjecttext">title</a>
Only used if /href is set:
title=title scalar; type: string
text to be used in HTML mailto string
subject=subject scalar; type: string; default: none
text for email subject field
OUTPUTS:
mailto scalar; type: string encoded email address
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType
CALLED BY:
www_help_check, www_help_make, www_help_master
PROCEDURE:
Email address is replaced by sequence of HTML special chars (using
ascii codes).
MODIFICATION HISTORY:
DEC-2006, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
www_help_make
PURPOSE:
Build a .HTML help system from source code headers
CATEGORY:
gen/idl
CALLING SEQUENCE:
PRO www_help_make, destination, header, section, style, $
swap_style = swap_style , $
email = email , $
cgi_bin = cgi_bin , $
crosslinks = crosslinks , $
mask = mask , $
calls = calls , $
includes = includes , $
externals = externals , $
copyright = copyright
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, hide_env, 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_mailto, 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
does not exist.
Now the file for the first letter that is present is loaded.
MAR-2003, Paul Hick (UCSD/CASS)
Added option to include copyright notice.
SEP-2007, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added code to write function/prodedure name, file name, and CALLS
INCLUDE, SEE ALSO and EXTERNAL sections into a plain text file. File
names are for.txt, pro.txt, etc.
Added a link to cgi script www_help_dep to display all the module
names and files a specific module depends on.
[Previous]
[Next]
NAME:
www_help_master
PURPOSE:
Recreate the master help file for 'destination'
CATEGORY:
gen/idl
CALLING SEQUENCE:
PRO www_help_master, destination, style, copyright=copyright
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_crosslinks, www_help_frames, www_help_mailto
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)
[Previous]
[Next]
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:
FUNCTION www_help_names, iline, line, ithis, header, mask, $
section, this_section, content, style, letter, linkout, crosslinks, ju=ju
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: ***
IsType, 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 entry 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
[Previous]
[Next]
NAME:
www_help_ptr
PURPOSE:
Manages 'calls' structure
CATEGORY:
www_help
CALLING SEQUENCE:
PRO www_help_ptr, calls, ithis, name, free=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.
[Previous]
[Next]
NAME:
www_help_rsi
PURPOSE:
Creates html help files for IDL lib directory
CATEGORY:
www_help
CALLING SEQUENCE:
PRO www_help_rsi, destination=destination, cgi_bin=cgi_bin, remote_dir=remote_dir
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)
[Previous]
[Next]
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
[Previous]
[Next]
NAME:
www_help_smei
PURPOSE:
Creates html help files for fortran and idl software
CATEGORY:
www_help
CALLING SEQUENCE:
PRO www_help_smei, $
idlonly = idlonly , $
fortranonly = fortranonly , $
scriptonly = scriptonly , $
c_only = c_only , $
cpp_only = cpp_only , $
remote_dir = remote_dir , $
cgi_bin = cgi_bin , $
destination = destination , $
copyright = copyright
INPUTS:
(none)
OPTIONAL INPUTS:
destination=destination
scalar; type: string; default: $SSW_SMEI/html/help/smei/
Local destination directory of help files
cgi_bin=cgi_bin
scalar; type: string: default: http://ips.ucsd.edu/cgi-bin/
Location of cgi scripts
remote_dir=remote_dir
scalar; type: string
Remote destinations of html files.
in the form host:directory
e.g. cassfos02.ucsd.edu:/u8/WWW/sola/help/smei/
OUTPUTS:
(html files are created in 'destination')
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
FILEPATH, InitVar, IsType, do_file, www_help, www_help_style
CALLED BY:
run_help
PROCEDURE:
Directories $SSW_SMEI and $SSW_SMEI/for are scanned recursively for
source code files *.pro and *.f.
MODIFICATION HISTORY:
JAN-2001, Paul Hick (UCSD/CASS)
APR-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Changes tabsize for scripts to 4 (was default 8)
[Previous]
[Next]
NAME:
www_help_style
PURPOSE:
Defines style structure for several languages
CATEGORY:
www_help
CALLING SEQUENCE:
FUNCTION www_help_style, $
idlcode = idlcode , $
sswcode = sswcode , $
script = script , $
fortran = fortran , $
c_code = c_code , $
cppcode = cppcode , $
tabsize = tabsize , $
html_name = html_name , $
html_top = html_top , $
title = title , $
anycase = anycase , $
master = master , $
automatic = automatic , $
use_path = use_path , $
calls_file = calls_file
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_smei, www_help_test, 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)
Added html_top keyword
JAN-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added calls_file keyword
[Previous]
[Next]
NAME:
www_help_test
CALLING SEQUENCE:
PRO www_help_test, paths
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
FILEPATH, www_help, www_help_style
[Previous]
[Next]
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 ips.ucsd.edu)
CATEGORY:
www_help
CALLING SEQUENCE:
PRO www_help_tree, destination, tree, master, files, $
cgi_bin=cgi_bin, email=email, iselect=iselect, list=list, $
use_path=use_path, copyright=copyright, prefix=prefix, $
_extra=_extra
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, TimeGet, TimeOp, 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)
[Previous]
[Next]
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, dot, space) are permitted
MODIFICATION HISTORY:
JULY-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
JUNE-2012, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added dot to allowed chars in name
[Previous]
[Next]
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)
