;+
; 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 href=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:
;	www_help_break, www_help_is_section, www_help_is_text
; 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)
;-

InitVar, force, /key

; If the 'calls' heap doesn't exist, return on=1B
; (fake that CALLED BY was written)

on = 1-ptr_valid(calls)

IF NOT on THEN BEGIN

	called_names = (*calls).name
	iunit = (where(called_names EQ mask[ithis]))[0]

	; If 'mask[ithis]' was not called by anybody, return on=1 (fake that
	; CALLED BY was written)

	on = iunit EQ -1

	IF NOT on THEN BEGIN

		; There is a CALLED BY section for 'mask[ithis]'. Look for a place to
		; put it. If keyword /force is set we skip this step.

		on = force
		IF NOT on THEN BEGIN

			; Pick up headers after 'srce_section' in 'section'
			; (srce_section must be present or the 'calls' heap wouldn't exist).

			tmp = www_help_is_section(style, srce_section, section)

			IF tmp EQ -1 THEN message, 'oops'	; Safety belt

			; If srce_section is the last section in the list, then we can't decide
			; on whether to write dest_section or not. Return on=0B (a call with
			; the /force keyword set has to be used to write dest_section at the
			; end of the header).

			on = tmp LT n_elements(section)-1

			; If there are sections following 'srce_section' check whether any of
			; these are present in 'line'. If yes then write the 'dest_section'
			; section. If not then this is not the place to put it, so return on=0B.

			IF on THEN on = 1-www_help_is_text(style, line, section[tmp+1:*])
		ENDIF

		IF on THEN BEGIN						; Write dest_section
			content = [content, ' '+dest_section]
			tmp = *(*calls)[iunit].called_by
			www_help_break, header[tmp].link, header[tmp].flink, content, header[mask[ithis]], dest_section
		ENDIF

	ENDIF

ENDIF

RETURN, on  &  END