CODEWITHSUNDEEP
matlab
Luis Mendo
Luis Mendo

Reputation: 112699

Get old-style help in Matlab's command window

Short version of question

In recent versions of Matlab (I have seen it in R2014b and R2015a on Windows), when you type help foo you get a brief description of the function and its signatures. For example, typing help bsxfun produces something like this (only with better format):

This MATLAB function applies the element-by-element binary operation specified by the function handle fun to arrays A and B, with singleton expansion enabled.

C = bsxfun(fun,A,B)

Reference page for bsxfun

See also arrayfun, repmat

Other uses of bsxfun distcomp/bsxfun

This is of course only a summary of the actual documentation. To get the full documentation you need to type doc foo. This opens the HTML help browser, which takes quite some time (at least on some computers).

Is there a way to get the full help in the command window (thus avoiding the help browser), as it used to be in older Matlab versions?

Long version of question

To look into this in more detail, I'll define "old" Matlab versions as those that don't have HTML help, and "new" versions as those that do. I also need to give each type of help a name, in order to refer to them:

As is well known, the text for FP help is contained in the first comment lines in the file defining the function. In new Matlab versions, functions may also have an associated HTML file. This file contains SH help in an HTML tag, and FH help in HTML code.

Possible behaviour is:

So the problem is more properly phrased as: how to show FP help in new Matlab versions when foo has an associated HTML help file. The question is meaningful because

An additional motivation is that in some cases the FP documentation contains features that don't appear in the FH documentation (see for example here).

Upvotes: 5

Views: 368

Answers (2)

Luis Mendo
Luis Mendo

Reputation: 112699

Original answer (Matlab versions R2014b, R2015a)

Although the documentation doesn't tell, the help function in these Matlab versions supports zero, one or two output arguments. You can check this typing open help and looking at the function signature:

function [out, docTopic] = help(varargin)

In essence, help works internally as follows:

  1. It creates an object called process, of class helpUtils.helpProcess, by calling the class constructor as:

    process = helpUtils.helpProcess(nargout, nargin, varargin);

    where nargout, argin and varargin are those with which help was called.

  2. It runs the method process.getHelpText, which calls the undocumented, built-in function helpfunc, and as a result sets the property process.helpStr. This property contains the help string which is shown in the command window.

As it turns out, at least on Windows, depending on the value of nargout (which gets passed to the constructor helpUtils.helpProcess) the resulting help string will be FP or SH. Namely, it will be FP if nargout>0, and SH if nargout==0. You can check this by typing the following code (adapted from help.m) directly in the command window:

process = helpUtils.helpProcess(1, 1, {'bsxfun'});
process.getHelpText
process.helpStr

This will produce FP help. On the other hand, changing the first 1 (which corresponds to nargout in the actual call) into a 0,

process = helpUtils.helpProcess(0, 1, {'bsxfun'});
process.getHelpText
process.helpStr

will produce SH help.

I don't know why this is so, that is, how it works on a deeper level than this. All I know is that the getHelp method calls the undocumented helpfunc, which is at least involved in producing FP help.

So, to get FP help you need to call help with one or two output arguments. For example,

str = help('foo')

assigns the FP help text to variable str and displays it. Or you can use

disp(help('foo'))

which also has the effect of calling help with an (implicit) output argument.

To have this behaviour from the standard command help foo, you could define a help function to override Matlab's help, and place it in your Matlab document folder. This folder normally appears first in the path (or you can make sure it does by editing startup.m), and thus has precedence. The new function will essentially call Matlab's help with one output argument, and then display the resulting (FP) help text. In order to call the overriden function it is necessary to temporarily change to its folder:

function help(varargin)
if isempty(varargin)
    varargin = {'help'}; %// `help` should be equivalent to `help help`
end
d = pwd; %// take note of current folder
cd(fullfile(matlabroot, 'toolbox', 'matlab', 'helptools')) %// folder where the
    %// standard `help` function is
disp(help(varargin{1}));
cd(d) %// restore folder

So now, finally, help foo produces the old-style (FP) help.

Edit for Matlab version R2015b

In Matlab R2015b the behaviour seems to have changed for the better. Typing help foo no longer produces SH help. It's not exactly FP either. In fact it's better than that: it produces FH help but in the command Window, not in the browser. Or, equivalently, it produces FP help but with links and better formattting.

So no need to tweak anymore!

Edit for Matlab version R2018a

Matlab R2018a again gives SH help. The solution provided in this answer works (that is, produces FP help).

So back to tweaking!

Upvotes: 7

Patrik Forssén
Patrik Forssén

Reputation: 41

A better way is to include the full path to the function when using the help command, then old style full help is displayed and the links also work, e.g. try:

help surf
help(fullfile(matlabroot, 'toolbox', 'matlab', 'graph3d', 'surf.m'))

I’ve just submitted an override help function based on this to MATLAB FEX:Full Command Line Help

Upvotes: 4

Related Questions