@compile_opt.pro			; On error, return to caller

;+
; NAME:
;	sections_ssw
; PURPOSE:
;	Template file with section headings used to process SSW with href=www_help=.
; CATEGORY:
; CALLING SEQUENCE:
; INPUTS:
; OPTIONAL INPUT PARAMETERS:
; OPT. INPUTS:
; KEYWORD ARGUMENTS:
; KEYWORDS:
; OUTPUTS:
; OPTIONAL OUTPUT PARAMETERS:
; OPT. OUTPUTS:
; INCLUDE:
; EXTERNAL:
; CALLS:
; SEE ALSO:
;	www_help, www_help_smei, www_help_ssw
; OPTIONAL KEYWORD INPUT:
;	Needed for 'nospike' (must be after CALLS)
; INPUTSSSSS:
;	Needed for GOES_DATA, GOES_PLOT (where CALLS preceeds this section)
; OTHER RELATED ROUTINES:
;	Needed for PD (where CALLS preceeds this section)
; COMMON BLOCKS:
; COMMON:
; SIDE EFFECTS:
; RESTRICTIONS:
; EXAMPLE:
; EXAMPLES:
; NOTE:
; PROCEDURE:
;	Documentation tactics.
;
;	The strict way
;	==============
;
;	Stick to section headings in this file exactly as specified, i.e.
;	uppercase and including a trailing colon. Don't invent new ones.
;
;	Put the procedure name on the line following the 'NAME' section heading.
;	The procedure should be one word (no whitespace). Ideally put only
;	one procedure/function per file, and let the file name, the actual
;	procedure/function name (as used in the 'pro' or 'function' 
;	declaration) and the name put in the 'NAME' section be the same.
;
;
;	The not so strict way
;	=====================
;
;	www_help has a keyword /anycase which allows for a more relaxed way
;	of documenting code. The following is allowed.
;
;	- Mixed or lower case section headings
;	- ROUTINE, or FILE, or PROGRAM, instead of NAME
;	- Routine name on same line as section heading NAME
;	- Whitespace between section heading and colon.
;	- One empty line in between the section heading and the procedure name
;	- Trailing brackets '()' (these are stripped off).
;	- Extra words following the procedure name separated by white space
;	  (exact treatment of this is determined in href=www_help_verify_name=;
;	  several things have been tried, none of them really satisfactory:
;	  only use first word, up to first white space; accept the whole multi-word
;	  name).
;
;	Using section headings not on the list is OK (even in the strict way)
;	as long as they don't follow the 'CALLS' or 'SEE ALSO' section (see
;	the discussion below).
;
;
;	The 'CALLS' and 'CALLED BY' sections
;
;	Ideally the CALLS section contains a comma-separated list of
;	all functions and procedures referenced by the procedure or
;	function. The information from all CALLS sections is inverted to
;	set up the CALLED BY section. I.e. if the html documentation for
;	a procdure has a 'CALLED BY' section it contains hyperlinks to all
;	procedures that admit to calling it by putting in their 'CALLS' section.
;
;	If keyword /automatic is set an attempt is made to get the CALLS
;	for each file from IDL itself using the IDL resolve_routine and
;	function_info procedures. A CALLS section put manually in the file is
;	used only if this automatic detection fails. This automatic detection
;	has its limitations:
;
;	- it does not work for IDL main programs (like the IDL_STARTUP file)
;		(the CALLS section must be added manually)
;	- it does not detect 'external' functions, executed through
;		e.g. the IDL call_external procedure (these should be put
;		in the EXTERNAL section).
;	- it does not detect *__define function executed implicitly
;		through automatic structure creation (probably these are best
;		put in the EXTERNAL section too).
;
;
;	The 'EXTERNAL' sections
;
;	Like the CALLS list the EXTERNAL section contains one or more
;	lines with a comma-separated list of procdure names. These will be turned
;	into hyperlinks to the html documentation for the corresponding procedure
;	(if the documentation exists). In addition the EXTERNAL information is
;	inverted to give an EXTERNAL BY list.
;
;	The INCLUDE section
;
;	This contains lines of the form
;		@include_file_name.pro
;	The word 'include_file_name' is turned into a hyperlink. In addition the
;	INCLUDE information is inverted to give an INCLUDED BY list.
;
;	The 'SEE ALSO' sections
;
;	Like the CALLS list the SEE ALSO section contains one or more
;	lines with a comma-separated list of procdure names. These will be turned
;	into hyperlinks to the html documentation for the corresponding procedure
;	(if the documentation exists). This list in not inverted.
;
;
;	Creating hyperlinks
;
;	Hyperlinks in 'CALLS', 'SEE ALSO', 'INCLUDE' and 'EXTERNAL' sections are
;	only created if a matching header is found. This match is made against the
;	procedure name found in the NAME section (i.e. NOT the file name, and NOT the
;	actual name as used in the IDL 'pro' or 'function' declaration). The hyperlinks
;	turn out best if all three are identical (i.e. one procedure per file, with the
;	actual name, the file name and the name in the header the same).
;
;	Processing of these four sections goes as follows. Once the relevant section
;	heading has been found, subsequent lines are processed into hyperlinks until
;	another valid section header is found. This is why these sections SHOULD NOT
;	BE FOLLOWED BY A SECTION HEADING NOT ON THE LIST OF VALID HEADINGS.
;
;
;	Detecting section headings.
;
;	Section headings are searched for using the IDL strpos statement, i.e.
;	if 'section' is the string array with recognized section headings and
;	'line' a string scalar with a line from the documentation header, then
;
;			pos = strpos(line, section[i])
;
;	If pos ne -1 then 'line' contains section heading 'i'. For SSW this is
;	not good enough. Section headings like 'MODIFICATION HISTORY' or
;	'VERSION HISTORY' (both of which are used in SSW) will be recognized as
;	a 'HISTORY' section heading, which probably is correct.
;	On the other hand 'EXAMPLE CALLS' is recognized as the start of a
;	'CALLS' section. This is probably wrong. The detection heading is
;	tweaked for SSW in href=www_help_is_section= (style.anycase = 1).
;
;	Some procedures have the author name in the NAME field.
;	This is not trapped. Probably the procedure ends up in the html file
;	with the name of the author.
;
;	Quite a few procedures in SSW have the NAME field without a trailing
;	colon. This is not trapped. The trailing colon MUST BE INCLUDED to be
;	recognized as a section heading. Usually these procedures end up
;	in the html documentation using the filename as procedure name
;	(which usually is correct).
;
;	Occasionally a section heading (including a trailing colon) ends
;	up in the documentation itself (i.e. not intended to be the start
;	of a new section. This messes thing up quite nicely.
;
; MODIFICATION HISTORY:
; VERSION HISTORY:
; HISTORY:
;	OCT-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
;-