在Matlab的命令窗口中获取旧式帮助 [英] Get old-style help in Matlab's command window

问题描述

问题的简短版本

在最近的Matlab版本中（我在Windows上看到了R2014b和R2015a），当你输入帮助foo 您将获得该功能及其签名的简要说明。例如，输入帮助bsxfun 生成这样的东西（只有更好的格式）：

该MATLAB函数将函数句柄 fun 指定的逐个元素二进制操作应用于数组 A 和 B ，启用单例扩展。

  C = bsxfun（fun， A，B）
  

参考页面bsxfun

另请参见 arrayfun ， repmat

其他用途 bsxfun
distcomp / bsxfun

这当然只是实际文档的摘要。要获得完整文档，您需要键入 doc foo 。这将打开HTML帮助浏览器，这需要相当长的时间（至少在一些电脑上）。

有没有办法在命令中获得完整的帮助窗口（因此避免了帮助浏览器），因为以前是旧的Matlab版本？

长版问题

为了更详细的研究，我将定义旧的Matlab版本，那些没有HTML帮助的版本，和新版本。我还需要给每种类型的帮助一个名字，以便参考他们：

• FP （Full，Plain）：以纯文本形式完整的帮助，如Matlab命令窗口（旧样式）所示。




• SH （总结，HTML）：以HTML格式汇总的帮助，如Matlab命令窗口所示。




• FH 完整的，HTML）：在帮助浏览器中显示的HTML形式的完整帮助。

众所周知FP帮助的文本包含在定义函数的文件的第一个注释行中。在新的Matlab版本中，函数也可能具有关联的HTML文件。此文件包含HTML标签中的SH帮助，以及FH帮助HTML代码。

可能的行为是：

• 在旧的Matlab版本中，帮助foo 生成FP帮助。


• 在新的Matlab版本中， help foo 如果 foo 具有关联的HTML帮助文件，则产生SH帮助，如果没有，则帮助FP。


• 在新的Matlab版本中， doc foo 产生FH帮助，如果 foo 具有关联的HTML帮助文件。如果没有，FP帮助将显示在帮助浏览器中（无格式）。

所以问题更恰当地表达为：如果 foo 具有关联的HTML帮助文件，那么如何在新的Matlab版本中显示FP帮助。这个问题是有意义的，因为

• 大多数Matlab函数都有一个关联的HTML帮助文件。


• Matlab函数，甚至内置函数（没有m代码），并且包含FP帮助的m文件。

另外的动机是，在某些情况下，FP文档包含FH文档中未显示的功能（请参见此处 ）

解决方案

原始答案（Matlab版本R2014b，R2015a）

尽管文档没有告诉，这些Matlab版本中的帮助函数支持零个，一个或两个输出参数。您可以检查这个键入打开帮助并查看功能签名：

  function [out，docTopic] = help（varargin）
  

本质上，帮助内部工作如下：

1. 它创建一个名为进程的对象通过调用类构造函数为$ helpUtils.helpProcess ，
   
   

     process = helpUtils.helpProcess（nargout，nargin，varargin）; 
     

   其中 nargout ，和 varargin 是调用帮助的那些。

   / li>


2. 它运行方法 process.getHelpText ，它调用未记录的内置函数 helpfunc ，从而设置属性 process.helpStr 。该属性包含命令窗口中显示的帮助字符串。




事实证明，至少在Windows ，取决于 nargout 的值（它被传递给构造函数 helpUtils.helpProcess ）生成的帮助字符串将为FP或SH 。也就是说，如果 nargout> 0 则为FP，如果 nargout == 0 则为SH。您可以直接在命令窗口中键入以下代码（从 help.m 中修改）来检查此问题：

  process = helpUtils.helpProcess（1，1，{'bsxfun'}）; 
 process.getHelpText 
 process.helpStr 
  

这将产生FP帮助。另一方面，将实际调用中的第一个 1 （对应于 nargout ）更改为 0 ，

  process = helpUtils.helpProcess（0，1，{'bsxfun' }）; 
 process.getHelpText 
 process.helpStr 
  

将产生SH帮助。 p>



我不知道为什么会这样，那就是它比这更深层次的工作。我所知道的是， getHelp 方法调用了无证件的 helpfunc ，这至少涉及生成FP帮助。 / p>



所以，获得FP帮助您需要调用帮助与一个或两个输出参数。例如

  str = help（'foo'）
  

将FP帮助文本分配给变量 str 并显示。或者您可以使用

  disp（help（'foo'））
  pre> 
 
 
这也具有使用（隐式）输出参数调用 help 的作用。
 
 
 
 要从标准命令 help foo  中获取此行为，您可以定义一个帮助功能覆盖Matlab的帮助 ，并将其放在Matlab文档文件夹中。该文件夹通常首先出现在路径中（或者您可以通过编辑 startup.m 确保它），因此具有优先权。新功能将基本上使用一个输出参数调用Matlab的帮助，然后显示生成的（FP）帮助文本。为了调用覆盖功能，有必要暂时更改为其文件夹：
  function help（varargin）
如果isempty（varargin）
 varargin = {'help'}; ％//`help`应该等同于`help help` 
 end 
 d = pwd; ％//记录当前文件夹
 cd（fullfile（matlabroot，'toolbox'，'matlab'，'helptools'））％//文件夹其中
％//标准`help`函数是
 disp（help（varargin {1}））; 
 cd（d）％//恢复文件夹
  
所以现在，最后，$ $ c> help foo 生成旧式（FP）帮助。
 
 
 
为Matlab版本R2015b编辑
 
 
 
在Matlab R2015b中，行为似乎已经改变了。键入帮助foo 不再产生SH帮助。这也不是FP。实际上它比这更好：它产生FH帮助，但是在命令窗口中，而不是在浏览器中。或者，等同地，它产生FP帮助，但链接和更好的格式化。
 
 
 
所以没有必要调整了！
 
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:


FP (Full, Plain): full help in the form of plain text, shown in Matlab command window (old style).
SH (Summarized, HTML): summarized help in the form of HTML, shown in Matlab command window.
FH (Full, HTML): full help in the form of HTML, shown in the help browser.


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:


In old Matlab versions, help foo produced FP help.
In new Matlab versions, help foo produces SH help if foo has an associated HTML help file, and FP help if it doesn't.
In new Matlab versions, doc foo produces FH help if foo has an associated HTML help file. If it doesn't, FP help is shown in the help browser (without format).


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


Most Matlab functions do have an associated HTML help file.
Most Matlab functions, even built-in functions (that have no m-code), have and m-file containing FP help.


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).
解决方案
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:

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.
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!

                        
这篇关于在Matlab的命令窗口中获取旧式帮助的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！