;+
; 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 href=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:
;	who_am_i, hide_env
; 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
;-

IF n_elements(list) NE 0 THEN file = (file_search(list[0]))[0] ELSE file = ''

IF file EQ '' THEN	$
	file = filepath(root=who_am_i(/directory), 'sections_'+style.sect_type+'.txt')

on_ioerror, DONE

openr, /get_lun, iu, file

sect = ''
temp = ''
WHILE NOT eof(iu) DO BEGIN
	readf, iu, temp
	IF strpos(temp,':') NE -1 THEN sect = [sect, strtrim(strmid(temp,1),2)]
ENDWHILE

message, /info, 'headings from: '+hide_env(file)

DONE:

on_ioerror, NULL

IF n_elements(iu) NE 0 THEN free_lun, iu

IF n_elements(sect) GT 1 THEN	$
	sect = sect[1:*]			$
ELSE BEGIN
	message, /info, 'using default IDL section headings'
	sect = ['NAME:','PURPOSE:','CATEGORY:','CALLING SEQUENCE:','INPUTS:',			$
			'OPTIONAL INPUT PARAMETERS:','OUTPUTS:','OPTIONAL OUTPUT PARAMETERS:',	$
			'COMMON BLOCKS:','SIDE EFFECTS:','RESTRICTIONS:','PROCEDURE:','MODIFICATION HISTORY:']
ENDELSE

;for i=0L,n_elements(sect)-1 do print, sect[i]

RETURN, sect  &  END