function helpview(path, varargin)
%HELPVIEW Displays an HTML file or collection in a platform-dependent
%help viewer. 
%
%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.
%
%  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
%       d:/v5/help/helpview.html#topicpath 
%
%  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 the help content.
%    Specify "CSHelpWindow" to use the context-sensitive help viewer.
%    Otherwise, the main "Help" window is used.
%
%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']);

%   Copyright 1984-2000 The MathWorks, Inc. 
%   $Revision: 1.17 $

wintype = '';
topic_id = '';

if nargin < 1
  error('Not enough input arguments.  For MATLAB help, type ''help'' or ''helpbrowser''.');
  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
  
  % If help_path starts with /mapfiles and docroot is empty, assume doc is
  % missing and show the standard error page in the help browser.
  if ((usejava('mwt') == 1) & (strncmp(help_path, [filesep 'mapfiles'], 9)) & isempty(docroot))
    hBrowser = javaMethod('getHelpBrowser','com.mathworks.ide.help.HelpBrowser');
    showHelpErrPage(hBrowser);
    return;
  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(sprintf('Specified path for topic collection or file does not exist:\n%s',help_path))
  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.

% 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

% Display the file
%
if isempty(topic_file)
  topic_file = title_file;
end
html_file = [coll_dir filesep topic_file anchor];


% Call the help viewer, unless Desktop is not enabled.
%
if (usejava('mwt') == 1)
  % The ICE browser fails to correctly interpret relative links using ".."
  % in certain URLs that mix slashes and backslashes.  As a workaround,
  % replace backslashes with slashes (following the "help" node).
  helpnodeidx = findstr(html_file, '\help\');
  if (~isempty(helpnodeidx))
    for i = (helpnodeidx(1)+1) : length(html_file)
      if (html_file(i) == '\')
        html_file(i) = '/';
      end
    end
  end
  % Use the appropriate viewer, based on window type.
  if (strcmp(wintype,'CSHelpWindow') & (~strcmp(topic_id,'')))
    % Use context-sensitive help window.
    % For now, only permit this if mapfile/topic_id is specified;
    % this is a temporary limitation until CSHelpViewer implements "displayPath" method.
    cshViewer = javaMethod('getTheViewer', 'com.mathworks.ide.help.CSHelpViewer');
    mapFile = javaObject('java.io.File', normalize_path(path));
    topicMap = javaObject('com.mathworks.ide.help.CSHelpTopicMap', mapFile);
    displayTopic(cshViewer, topicMap, topic_id);
  else
    % Otherwise, use the main Help window.
    hBrowser = javaMethod('getHelpBrowser','com.mathworks.ide.help.HelpBrowser');
    setCurrentLocation(hBrowser, html_file);
  end
else
  % use web browser to display the file
  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(sprintf('Specified path for topic map is invalid.\n%s',map_path))
  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. 
%
if strcmp(computer, 'PCWIN')
  normal_path = strrep(path, '/', '\');
else
  normal_path = strrep(path, '\', '/');
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



  



