hs=ehelp(fnam,tag,del)

% EHELP
%	- extracts a section marked by two unique tags from an ASCII file
%	- typically used as a SUBROUTINE within a function
%	  to extract extended help
%	- can be used as a command line tool if the author provides the
%	  HTAG information within the classic help section
%
% SYNTAX
%		HS = ehelp(FNAM,HTAG)
%		HS = ehelp(FNAM,HTAG,DEL)
%
% FNAM	:	file name to be parsed for marked section(s)
% HTAG	:	a unique string id set at the beginning and end of a
%		section within the file FNAM
%		- note if HTAG is found only once, an error is generated
%		       if HTAG is found more than twice, the section
%		       between the last two tags is returned
% DEL	:	an optional delimiter, which will be removed from the
%		output
%		- note typically used to remove <%> markers from the
%		       beginning of a line
%
% HS	:	returns the section in FNAM between the two HTAGs
%
% EXAMPLES
%	typical use as a SUBROUTINE
%	- a programmer adds extended help sections at the end of
%	  a function <afun.m>, eg, __H1__ and __H2__, and provide
%	  input options for the user to look at them
%	- the code of EHELP is copy/pasted into <afun.m> and becomes
%	  a subroutine
%	- function call at the command line, eg,
%		afun -h1
%	- code portion in <afun.m>, eg,
%		% ...processing...
%		if <condition to look for extended help>
%			switch varargin{1}
%			case '-h1'
%				hs=ehelp(mfilename,'__H1__','%+');
%			case '-h2'
%				hs=ehelp(mfilename,'__H2__','%');
%			end
%				disp(hs);
%		end
%
%	command line demo with ehelp itself
%		type ehelp.m	% to see that we have two tags _S1_
%	- keep the beginning-of-line markers
%		hs=ehelp('ehelp.m','_S1_');
%		disp(hs);
%	- or remove them
%		hs=ehelp('ehelp.m','_S1_','%$');
%		disp(hs)

% created:
%	us	12-Jan-1996
% modified:
%	us	03-Feb-2006 14:02:42

%--------------------------------------------------------------------------------
% ONLY COPY CODE BELOW
%--------------------------------------------------------------------------------
function	hs=ehelp(fnam,tag,del)

		hs=[];
	if	nargin < 2
		return;
	end
	if	nargin < 3
		del=[];
	end

		[fp,msg]=fopen(which(fnam),'rt');
	if	fp > 0
		hs=fread(fp,inf,'*char').';
		fclose(fp);
		ib=strfind(hs,tag);
	if	isempty(ib)	||...
		numel(ib)<2
		hs=[];
		disp(sprintf('EHELP> %s: help section <%s> not found twice',fnam,tag));
	else
		hs=hs(ib(end-1)+length(tag)+1:ib(end)-1);
	if	~isempty(del)
		hs=strrep(hs,del,'');
	end
	end
	else
		disp(sprintf('EHELP> %s: %s',fnam,msg));
	end
		return;
%--------------------------------------------------------------------------------
% ONLY COPY CODE ABOVE
%--------------------------------------------------------------------------------

%	TEST SECTION
%$_S1_
%$this
%$is an EHELP
%$section
%$_S1_