Code covered by the BSD License  

Highlights from
Enhanced help--improve your workflow

image thumbnail

Enhanced help--improve your workflow

by

 

31 Aug 2006 (Updated )

Simple enhancement to help listings: adds hyperlinks to open files for editing.

help(varargin)
function [varargout] = help(varargin)
%  HELP Display help text in Command Window.
%     HELP, by itself, lists all primary help topics. Each primary topic
%     corresponds to a directory name on the MATLABPATH.
%
%     HELP / lists a description of all operators and special characters.
%
%     HELP FUN displays a description of and syntax for the function FUN.
%     When FUN is in multiple directories on the MATLAB path, HELP displays
%     information about the first FUN found on the path and lists
%     PATHNAME/FUN for other (overloaded) FUNs.
%
%     HELP PATHNAME/FUN displays help for the function FUN in the PATHNAME
%     directory. Use this syntax to get help for overloaded functions.
%
%     HELP DIR displays a brief description of each function in the MATLAB
%     directory DIR. DIR can be a relative partial pathname (see HELP
%     PARTIALPATH). When there is also a function called DIR, help for both
%     the directory and the function are provided.
%
%     HELP CLASSNAME.METHODNAME displays help for the method METHODNAME of
%     the fully qualified class CLASSNAME. To determine CLASSNAME for
%     METHODNAME, use CLASS(OBJ), where METHODNAME is of the same class as
%     the object OBJ.
%
%     HELP CLASSNAME displays help for the fully qualified class CLASSNAME.
%
%     T = HELP('TOPIC') returns the help text for TOPIC as a string, with
%     each line separated by /n. TOPIC is any allowable argument for HELP.
%
%     REMARKS:
%     1. Use MORE ON before running HELP to pause HELP output after a
%     screenful of text displays.
%     2. In the help syntax, function names are capitalized to make them
%     stand out. In practice, always type function names in lowercase. For
%     Java functions that are shown with mixed case (for example,
%     javaObject) type the mixed case as shown.
%     3. Use DOC FUN to display help about the function in the Help
%     browser, which might provide additional information, such as graphics
%     and examples.
%     4. Use DOC HELP for information about creating help for your own
%     M-files.
%     5. Use HELPBROWSER to access online documentation in the Help
%     browser. Use the Help browser Index or Search tabs to find more
%     information about TOPIC or other terms.
%
%     EXAMPLES:
%     help close - displays help for the CLOSE function.
%     help database/close - displays help for the CLOSE function in the
%     Database Toolbox.
%     help database - lists all functions in the Database Toolbox and 
%     displays help for the DATABASE function.
%     help general - lists all functions in the directory MATLAB/GENERAL.
%     help embedded.fi - displays help for the EMBEDDED.FI class in the
%     Fixed-Point Toolbox.
%     help embedded.fi.lsb displays help for the LSB method of the
%     EMBEDDED.FI class in the Fixed-Point Toolbox.
%     t = help('close') - gets help for the function CLOSE and stores it as
%     a string in t.
%
%     See also DOC, DOCSEARCH, HELPBROWSER, HELPWIN, LOOKFOR, MATLABPATH,
%     MORE, PARTIALPATH, WHICH, WHOS, CLASS.
%
%   *Version modified by JRI (john_iversen@post.harvard.edu) 9/1/2006*
%

% ******************************************************************************
%   9/1/06  JRI small change made to enable my changed makehelphyper, which adds
%               hyperlinks to edit files to help output, to correctly link to 
%               class methods
%
%   John Iversen (john_iversen@post.harvard.edu)
%
%   INSTALLATION
%       Place this modified help.m and the accompanying modified makehelphyper.m
%       anywhere in your working directory tree that is earlier on the search
%       path than the matlab toolbox. YOU DO NOT NEED TO MODIFY THE MATLAB
%       TOOLBOX IN THE ORIGINAL DISTRIBUTION. Instead, you place these updated
%       files so that matlab finds them first, before the stock versions.
%   
%       verify that it is finding this version by doing >> which help
%
%       see my makehelphyper.m for a few more details on this.
%
%      [my modifications are clearly indicated in the code. Search for 'JRI']
%
%       This is a modified version of the file supplied with matlab (R14SP1)
%       Original file is found in MATLAB701/toolbox/matlab/helptools/help.m
%
% ******************************************************************************

%   Copyright 1984-2004 The MathWorks, Inc.
%   $Revision: 1.1.6.12 $  $Date: 2004/08/16 01:48:50 $
%   Built-in function.

if nargin==0
    topic = '';
else
    topic = varargin{1};
end

if nargout == 0
    if ~usejava('jvm')
        helpStr = getHelpText(varargin{:});
        displayHelpText(helpStr);
        % If there is no text, that means there's no help.  We need to call the
        % builtin so it actually prints out the proper message.
        if isempty(helpStr)
            builtin('helpfunc', varargin{:});
        end
    else
        % Get the help text
        helpStr = getHelpText(varargin{:});

        % If there is no text, that means there's no help.  We need to call the
        % builtin so it actually prints out the proper message.
        if isempty(helpStr)
            builtin('helpfunc', varargin{:});

            if usejava('desktop')
                disp(sprintf('Use the Help browser Search tab to <a href="matlab:docsearch %s">search the documentation</a>, or\ntype "<a href="matlab:help help">help help</a>" for help command options, such as help for methods.\n', topic));
            else
                disp(sprintf('Use the Help browser Search tab to search the documentation, or\ntype "help help" for help command options, such as help for methods.\n'));
            end
            return;
        end

        % display the help.  We want hyperlinks if the desktop is on, since
        % the command window knows how to display them.
        displayHelp(helpStr, topic, usejava('desktop'));
    end
else
    helpStr = getHelpText(varargin{:});
    moreInfo = '';
    if usejava('jvm') && ~isempty(refPageUrl(topic))
        moreInfo = sprintf('\n    Reference page in Help browser\n    doc %s\n', topic);
    end
    [varargout{1:nargout}] = [helpStr moreInfo];
end

function displayHelp(helpStr, topic, wantHyperlinks)

[pathname temp_topic ext] = fileparts(topic);
% Is this a directory (regular or OOPS) with a Contents.m?
if exist(which(topic))~=2 && (exist(fullfile(topic,'Contents.m'))==2 || exist(fullfile(pathname, ['@' temp_topic], 'Contents.m'))==2)
    pathname = topic;
    topic = 'Contents.m';
else
    % This must be a file.  Get the fileparts of the full pathname.
    [pathname topic ext] = fileparts(which(topic));
end

% ******************************************************************************
%   9/1/06  JRI part of fix enabling makehelphyper to correctly link to class
%           methods
JRI_linkableTopic = topic; %default, same as topic
% ******************************************************************************

if ~isempty(pathname)
    % For MATLAB classes... check if there's a path to a class
    [path_to_class classname unused] = fileparts(pathname);
    if find(classname == '@') == 1
        pathname = path_to_class;
        classname = classname(2:end);
        if ~isempty(ismember(methods(classname), topic))
            % ******************************************************************************
            %   9/1/06  JRI help.m did not pass the actual class name to makehelphyper,
            %           making it impossible to link to the correct file to edit.
            %           create a 'linkable' file name (as opposed to the reference page topic)
            %           to send to makehelphyper.
            JRI_linkableTopic = [classname '/' topic]; %for class method, add class name
            % ******************************************************************************
            % If this is a member of a class, we need to find the prefix
            % for the reference page link below.
            [unused prefix unused] = fileparts(path_to_class);
            topic = [prefix '/' topic];
        end
    end
end

if ~isempty(topic) && ~isempty(refPageUrl(topic))
    % Show the reference page if it exists.  If the topic contains at least
    % one slash, it means they're looking under a product, and since the
    % doc command only supports one level, we'll use the string before the
    % first slash as the product directory, and the string after the last
    % slash as the topic page.  The rest will be ignored.
    k = find(topic == '/' | topic == '\');
    if ~isempty(k)
        topic_dir = topic(1:k-1); % get the topic directory
        topic_page = topic(k(end)+1:end); % get the topic page
        if isempty(topic_dir)
            topic = topic_page;
        else
            topic = [topic_dir '/' topic_page];
        end
    end
    
    if wantHyperlinks
        moreInfo = sprintf('\n    Reference page in Help browser\n       <a href="matlab:doc %s">doc %s</a>\n', topic, topic);
    else
        moreInfo = sprintf('\n    Reference page in Help browser\n       doc %s\n', topic);
    end
    helpStr = [helpStr moreInfo];
end

if wantHyperlinks
    % Make "see also", "overloaded methods", etc. hyperlinks.
    % ******************************************************************************
    %   9/1/06  JRI pass correct, linkable, file name to makehelphyper
    %%%helpStr = makehelphyper('help', pathname, topic, helpStr); % ORIGINAL
    helpStr = makehelphyper('help', pathname, JRI_linkableTopic, helpStr);
    % ******************************************************************************
end

displayHelpText(helpStr);
disp(sprintf('\n'));

function displayHelpText(helpStr)

if isequal(get(0,'More'),'on')
    try
        % Workaround for the fact that more doesn't work well with disp...
        % Get the newlines
        a = regexp(helpStr, '\n');
        if ~isempty(a)
            substart = 1;
            for n=1:length(a)
                subend = a(n)-1;
                if subend<substart
                    % This is a blank line
                    disp(' ');
                else
                    b = helpStr(substart:subend);
                    disp(b);
                end
                substart=subend+2;
            end
            % display the last line (if after the last carriage return)
            b = helpStr(subend+2:length(helpStr));
            if (~isempty(b))
                disp(b);
            end
        else
            disp(helpStr);
        end
    catch
    end
else
    disp(helpStr);
end


function helpText = getHelpText(varargin)

helpText = '';
dotind = [];
if nargin > 0
    topic = varargin{1};
    % Check to see if it's a request for classnames or methods.
    dotind = find(topic == '.');
    if ~isempty(dotind)
        slashind = find(topic == '/');
        packageinfo = what(['@' topic(1:dotind(1)-1)]);
        if ~isempty(packageinfo)
            packagename = packageinfo(1).path;
            atIdx = find(packagename=='@');
            pkh = findpackage(packagename(atIdx(end)+1:end));
            if ~isempty(pkh)
                if strcmp(pkh.Documented, 'on')
                    if length(dotind) > 1
                        classname = topic(dotind(1)+1:dotind(2)-1);
                        classname = localFindDefiningClass(pkh, classname, topic(dotind(2)+1:end));
                        pathname = fullfile(packagename, ['@' classname]);
                        pathname = fullfile(pathname, [topic(dotind(2)+1:end) '.m']);
                    elseif length(slashind) == 1
                        classname = topic(dotind(1)+1:slashind(1)-1);
                        classname = localFindDefiningClass(pkh, classname, topic(slashind(1)+1:end));
                        pathname = fullfile(packagename, ['@' classname]);
                        pathname = fullfile(pathname, [topic(slashind(1)+1:end) '.m']);
                    else
                        classname = topic(dotind(end)+1:end);
                        pathname = fullfile(packagename, ['@' classname], [classname '.m']);
                    end
                    varargin{1} = pathname;
                    helpText = builtin('helpfunc', varargin{:});
                    return;
                end
            else
                % this must be an oops class.  use '/' as the separator so 
                % the builtin help function can find it.
                topic(dotind) = '/';
                varargin{1} = topic;
                helpText = builtin('helpfunc', varargin{:});
                return;
            end
        end
    end
end

if isempty(helpText)
    % Call helpfunc in the caller's workspace.
    helpText = builtin('evalin', 'caller', 'builtin(''helpfunc'', varargin{:})');
end

% Uncomment when this is fast enough...
% if isempty(helpText) && isempty(dotind)
%     % Look for help in methods.
%     helpText = getMethodHelp(varargin{:});
% end


function methodHelp = getMethodHelp(varargin)

methodHelp = '';
if nargin > 0
    topic = varargin{1};
    currentpath=path;
    pathlist=eval(['{''' strrep(currentpath,pathsep,''';''') '''}']);

    allpathinfo = what(pathlist{:});
    overloaded_methods_exist = false;

    for i=1:length(allpathinfo)
        for j=1:length(allpathinfo(i).classes)
            filename = [allpathinfo(i).path filesep '@' allpathinfo(i).classes{j}];
            lsoutput = ls([filename filesep '@*']);
            if ~isempty(lsoutput)
                a = strcat({[filename filesep]}, lsoutput);
                for k=1:length(a)
                    filename = [a{k} filesep topic '.m'];
                    if exist(filename) == 2
                        atind = find(filename == '@');
                        slashind = find(filename == filesep);
                        packagename = filename(atind(1)+1:atind(2)-2);
                        pkh = findpackage(packagename);
                        if ~isempty(pkh) && strcmp(pkh.Documented, 'on')
                            classname = filename(atind(2)+1:slashind(end)-1);
                            methodname = filename(slashind(end)+1:end-2);
                            fullMethodname = sprintf('%s.%s.%s', packagename, classname, methodname);
                            if ~isempty(methodHelp)
                                if ~overloaded_methods_exist
                                    methodHelp = sprintf('%s\n    Overloaded methods (methods with the same name in other classes)\n', methodHelp);
                                end
                                methodHelp = sprintf('%s       help %s\n',methodHelp,fullMethodname);
                                overloaded_methods_exist = true;
                            else
                                helpStr = [methodHelp builtin('helpfunc', filename)];
                                if ~isempty(helpStr)
                                    banner = sprintf('\n --- help for %s ---\n\n', fullMethodname);
                                    methodHelp = [methodHelp banner helpStr];
                                end
                            end
                        end
                    end
                end
            end
        end
    end
end


function url = refPageUrl(topic)

url = '';
if usejava('jvm')
    if isempty(strfind(topic,'Contents.m'))  % don't bother with Contents.m files
        url = com.mathworks.mlwidgets.help.HelpInfo.getReferencePageUrl([topic '.html']);
    end
end

function classname = localFindDefiningClass(pkh, classname, methodname)
ch = findclass(pkh, classname);
while ~isempty(ch)
    m = ch(1).methods;
    if ~isempty(m) && ~isempty(m.find('Name', methodname))
        classname = ch.Name;
        break;
    end
    ch = ch.Superclasses;
end

Contact us