function helpview(path, varargin)
%HELPVIEW Displays an HTML file or collection in a platform-dependent
%help viewer. 
%
%  On Windows, HELPVIEW invokes the Microsoft HTML Help Viewer, if it
%  is installed; otherwise, it invokes the web command.
%  
%  On Unix, HELPVIEW invokes web.
%
%  Note: helpview works only on Unix and Windows systems.
%
%SYNTAX:
%
%  helpview (coll_path)
%  helpview (coll_path, win_type)
%  helpview (topic_path)
%  helpview (topic_path, win_type)
%  helpview (map_path, topic_id)
%  helpview (map_path, topic_id, win_type)
%
%
%ARGUMENTS:
%
%  coll_path
%    Path of a collection of html files. The last
%    name in the path is the name of the collection.
%    helpview assumes that the collection exists as
%    a directory of html files on Unix systems and
%    both as a directory of html files and as a
%    compressed help (.chm) file on Windows sytems.
%    For example, if the caller specifes the following 
%    collection path on Windows:
%    
%       d:/v5/help/ml_graph
%
%    helpview assumes that the the host filesystem 
%    contains the following directory
%     
%       d:/v5/help/ml_graph/
%
%    and the following compressed help file
%
%       d:/v5/help/ml_graph.chm
%
%    helpview further assumes that a collection directory
%    contains an html fileof the same name (e.g., 
%    /v5/help/ml_graph/ml_graph.html). This file is known
%    as the title file. If the host system has the Microsoft 
%    HTML Help viewer, helpview invokes the viewer on the .chm 
%    version of the collection. Otherwise, it invokes the MATLAB
%    web command on the collection's title page file.
%
%  topic_path
%    Path of an html file. The path must end in .htm(l) or 
%    .htm(l) and an HTML anchor reference, for example, 
%
%       /v5/help/helpview.html#topicpath
% 
%    on Unix, or
% 
%       d:/v5/help/helpview.html#topicpath 
%
%    on Windows.
%
%    The topic_path can be of the form 
%
%       coll_path/topic_file
%
%    where coll_path is the path of a collection
%    and topic_file is the name of an html file
%    in the collection. If the Microsoft HTML
%    help viewer is available, helpview uses the
%    viewer to display the version of the topic file
%    stored in the compressed collection. This allows
%    the caller to specify a window type (defined
%    by the collection) in which to display the
%    topic (see win_type parameter below).
%
%  map_path
%    Path of a map file (see below) that maps 
%    topic ids to the paths of topic files. The path must
%    end in the extension .map, for example,
%
%      d:/v5/help/ml_graph.map
%
%  topic_id
%    An arbitrary string that identifies a topic. HELPVIEW uses
%    the map file specified by path to map topic_id to
%    the path of the HTML file that documents the topic.
%
%  win_type
%    Type of window in which to display a compressed collection
%    or a topic from a compressed collection. The .chm file
%    must define the window identified by win_type. For example,
%    suppose that the ml_graph .chm file defines a window type named
%    PlainWindow. Then,
%
%      helpview([DOCROOT 'techdoc/ml_graph/axis.html'], 'PlainWindow');
%
%    would display axis.html in a PlainWindow.
%
%    Note: helpview ignores this parameter if HTML Help is unavailable.
%
%TOPIC MAP FILE
%
%  The map file is an ascii text file that is 
%  essentially a two-column list.  Each line is
%  of the form:
%
%    TOPIC_ID PATHNAME
%
%  The TOPIC_ID is an arbitrary string identifying
%  a "chunk" of online help contained in an HTML
%  file.  Typically, the technical writer and the 
%  developer will agree what these identifiers should be, 
%  and the developer will use them in calls to helpview.  
%
%  PATHNAME is a coll_path or topic_path relative to
%  the directory containing the map file.
%  
%  For example, suppose the following map file
%
%    % ml_graph.map
%    COLORPICKDLG  ml_graph/ch02aa31.html
%    PRINTDLG      ml_graph/ch02aa35.html
%    LINESTYLEDLG  ml_graph/ch02aa31.html#ModLines
%
%  is in the directory DOCROOT\techdoc, where DOCROOT
%  is the root directory of the MATLAB help system. Then,
%  the following call
%
%    helpview([DOCROOT '/techdoc/ml_graph.map'], 'PRINTDLG');
% 
%  is equivalent to
%
%    helpview([DOCROOT '/techdoc/ml_graph/ch02aa35.html']);
%
%  NOTE:
%
%  You can cause helpview to always use the default web browser
%  on your system by setting the value of the environment variable
%  matlab_use_htmlhelp_viewer to no. For example, on Windows 95,
%  enter
%
%    set matlab_use_htmlhelp_viewer=no    
%
%  in your autoexec.bat file.

%   Copyright (c) 1984-98 by The MathWorks, Inc.
%   $Revision: 1.6 $

is_pc = strcmp(computer, 'PCWIN');
wintype = '';

if nargin < 1
  error('helpview requires at least one argument.');
  return;
end

if ~ ischar(path) | strcmp(path, '')
  error('First argument must be a non-null path');
  return;
end

% Ensure that path uses correct separator
% for platform.
help_path = normalize_path(path);


% Does path specify a topic map file?
e = length(help_path);
b = e - 3;
if (b > 0) & strcmp(help_path(b:e), '.map')
  
  % Get the id of the topic to be mapped.
  if (length(varargin) < 1)
    error('Topic id required to find topic path from map file.');
    return;
  else
    topic_id = varargin{1};
  end
  
  % Look up topic or collection path in the map file.
  help_path = map_topic(help_path, topic_id);
  
  % Get windows type argument, if specified.
  if (length(varargin) == 2)
    wintype = varargin{2};
    if ~ ischar(wintype)
      error('Third parameter must specify a window type.');
    end
  end
else  % First arg is path of a collection or a topic.
  % Is there also a wintype argument?
  if (length(varargin) == 1)
    wintype = varargin{1};
        if ~ ischar(wintype)
      error('Second parameter must specify a window type.');
    end
  end  
end

% Strip off HTML anchor if present.
[help_path anchor] = parse_anchored_path(help_path);

if ~ (exist(help_path) == 2 | exist(help_path) == 7)
  error('Specified path for topic collection or file does not exist.')
  return;
end
 

% Now we have a normalized path and an optional wintype argument.
% The path points to a collection, a file in a collection, or
% a file. The collection is a directory of files and/or a
% compressed (.chm) file.

% Parse the path.
[coll_dir topic_file ext vers] = fileparts(help_path);

% Does help_path point to a topic file?
if ext
  if ~ findstr(ext, 'htm')
    error('Name of topic file must end in .htm or html.')
    return;
  end
  topic_file = [topic_file ext];
  title_file = '';
else % Points to a directory, i.e., a collection.
  coll_dir = help_path;
  title_file = [topic_file '.html'];
  topic_file = '';
  % Does collection's title topic exist?
  if (exist([coll_dir filesep title_file]) ~= 2)
    error('Cannot find title topic in collection directory.');
    return
  end
end

% Does a compressed version of collection exist?
coll_chm = [coll_dir '.chm'];
if (exist(coll_chm) ~= 2)
  coll_chm = [];
end

% If the host is Windows and HTML Help is installed,
% use HTML Help to display files.
if (is_pc & HTMLHelpAvailable)
  % If a compressed version of a collection exists,
  % display the compressed version of the collection
  % or topic.
  if coll_chm
    hhelp(coll_chm, [topic_file anchor], wintype);
  else  % Compressed version does not exist.
    if isempty(topic_file)
      topic_file = title_file;
    end
    hhelp([coll_dir filesep topic_file anchor],'', 'plain');
  end
else 
  if isempty(topic_file)
    topic_file = title_file;
  end
  display_file([coll_dir filesep topic_file anchor]);
end

function display_file(html_file)
  % Display html_file in the default browser for
  % the user's system.

  % Construct URL
  if (strncmp(computer,'MAC',3))
    html_file = ['file:///' strrep(html_file,filesep,'/')];
  end

  % Load the correct HTML file into the browser.
  stat = web(html_file);
  if (stat==2)
    error(['Could not launch Web browser. Please make sure that'  sprintf('\n') ...
        'you have enough free memory to launch the browser.']);
  elseif (stat)
    error(['Could not load HTML file into Web browser. Please make sure that'  sprintf('\n') ...
        'you have a Web browser properly installed on your system.']);
  end


function topic_path = map_topic(map_path, topic_id)
% Look up the path of a topic in a topic map file.

rel_path = [];

if (exist(map_path) ~= 2)
  error('Specified path for topic map is invalid.')
  return;
end

[tid, tpath] = textread(map_path, '%s %s','commentstyle','matlab');

n = length(tid);
for i = 1:n
  if (strcmp(tid(i), topic_id))
    rel_path = tpath{i};
    break;
  end
end

map_path = fileparts(map_path);
topic_path = normalize_path([map_path filesep rel_path]);

function normal_path = normalize_path(path)
% Ensures that path uses the correct separator
% for the current platform. 
%
% Note: that this works only for Windows and
% Unix platforms.
%
% This will have to be updated to support VMS.
%
if strcmp(computer, 'PCWIN')
  normal_path = strrep(path, '/', '\');
else
  normal_path = strrep(path, '\', '/');
end

function boolean = actxregp(progid)
  % Returns true if the specified ActiveX control
  % is registered on the user's system.
  %
  % This is a standin for a c function that will
  % implement the specified functionality.
  boolean = 1
  
  
function boolean = HTMLHelpAvailable()

  % Escape hatch.
  eh = lower(getenv('matlab_use_htmlhelp_viewer'));
  if (~ isempty(eh) & strcmp(eh, 'no'))
     boolean = 0;
     return;
  end
  
  try
    v = winqueryreg('HKEY_LOCAL_MACHINE', ...
	'SOFTWARE\Microsoft\Internet Explorer', 'Version');
    if (~ isempty(v) & str2double(v(1)) >= 4)
      boolean = 1;
    else
      boolean = 0;
    end
  catch 
    boolean = 0;
  end
    
function [path, anchor] = parse_anchored_path(apath)
  % Parses a path that references an HTML anchor.
  n = findstr(apath, '#');
  if n > 3
    path = apath(1:(n-1));
    anchor = apath(n:length(apath));
  else
    path = apath;
    anchor = '';
  end

    
  
% End of helpview.m



  



