MATLAB Spoken Here

Improved Help from the MATLAB Editor and Command Window 25

Posted by Jared MacDonald,

In the new R2007b version of MATLAB, we’ve improved an existing feature called Help on Selection. Have you ever forgotten the arguments to a function as you’re typing in the Command Window?

Help on Selection - sitting at the prompt

I bet you have. In R2007b, you can just press F1:

Help on Selection - showing help popup

Whether you’re in the Command Window or Editor, you’ll get relevant help in a lightweight, quick format.

We’ve tried to make the feature friendly to keyboard-o-philes and mouse-o-phobes (like me), allowing you to keep your hands on the keyboard. You can press F1 to get help, use the arrow keys to scroll, then press Escape to close it out and return to coding. Better yet, don’t press Escape; instead, press F1 to leave help open and toggle back and forth between it and your text. In fact, this is the way I like to use it:

help_on_selection3.png

I’ve expanded the help window and left it open, and I can press F1 to iterate rapidly through the help pages of various functions in my file. Of course, if you are using the mouse, you can still right-click and choose “Help on Selection” from the Editor or Command Window.

Finally, note that you can go to the same page in the full-fledged Help Browser if you need to do further exploring:

help_on_selection4.png

If you get your hands on R2007b, give it a try and let us know what you think.

25 CommentsOldest to Newest

Of some reason or other the pictures (e.g. help_on_selection1.png) of this blog don’t display in my browser. I cannot figure out to make them display. The pictures in he previous topics of this blog (Inside the MATLAB Desktop) display well.

I’m curious since R2007b hasn’t yet reached me.

/ per

Hi Per – that’s odd. They appear OK to me, and I’ve tried a couple browser and machine combinations. What’s your browser/machine?

Jared

I’ve tried it on a couple of browsers too and all do not show the pics.

Tested on firefox: mac and windows, Safari on Mac, and IE on windows.

Ach. My boneheaded mistake. Shouldn’t trust viewing an external website from inside the network.

Images should be visible now. Thanks for the heads up, folks. Let me know.

Hi Jared

Now I see the images.

This is exactly what I need since I more often than not fail to remember three details for ten seconds.

Is it possible to “minimize” the window and keep it on top? I cannot always afford to have it open. Did you ever use PostIt Notes? (http://www.3m.com/us/office/postit/) Is it possible to open more than one instance? Is it quick to copy and paste from it?

Can the user add (and remove) content? I don’t always remember how to call my own functions. Especially not after having changed the syntax.

/ per

I like the idea of a light-weight help pop-up; I’ll be using it a lot.

A related question about light-weight help. In another context, help is very heavy-weight.

If I am helping a student or someone else and want to email them a link to a page, say “doc lu”, I can’t do it without opening up a web browser, and navigating http://www.mathworks.com for the “lu” command. But then the link isn’t fully shown in the address bar (Firefox in windows at least), so it can’t be cut-and-pasted into an email or newsgroup posting. It’s a very long process to find an http: link to this same page that can be so easily brought up with one key (F1) via the new and cool light-weight help.

Yes, I know I could say “type doc lu in MATLAB”, but a student might not have MATLAB in front of them when they read my email.

When I do find the link, say via a Google search of “matlab lu” I get a very heavy-weight link:

http://www.mathworks.com/access/helpdesk/help/techdoc/index.html?/access/helpdesk/help/techdoc/ref/lu.html&http://www.google.com/search?q=matlab+lu&sourceid=navclient-ff&ie=UTF-8&rls=GGGL,GGGL:2006-27,GGGL:en

which of course is exceedingly ugly (some of which is from Google). Of course, I could use:

http://www.mathworks.com/access/helpdesk/help/techdoc/ref/lu.html

(which is nowhere obvious) but that redirects immediately to this ugly lengthy link:

http://www.mathworks.com/access/helpdesk/help/techdoc/index.html?/access/helpdesk/help/techdoc/ref/lu.html

Could each page on “doc” or the same page in the online helpdesk include a “Link to this page” link? And/or could there be a function in MATLAB that does

s = webdoc(‘lu’)

which returns

s = ‘http://www.mathworks.com/access/helpdesk/help/techdoc/ref/lu.html’

Per,

Thanks for the good suggestions. There is currently no way to minimize it, nor is there a way to open multiple instances. I have the luxury of dual monitors, so I can leave it open and off to the side; if I had less real estate I might try to get into the habit of opening and closing it more frequently.

I look forward to your trying it out and letting me know what you think.

As for adding and removing content, yes, the popup will pick up your help content, assuming you follow the standard help formatting conventions:

http://www.mathworks.com/access/helpdesk/help/techdoc/index.html?/access/helpdesk/help/techdoc/ref/help.html

Jared

Hello Jared,

I think this is a nice feature!

However I was thinking about an even more lightweight help, you might call it microweight.

In environments as Visual Studio the tooltips are used to show the arguments of functions or to show the fields of a structure or the methods of a class. The latter two are already implemented. For more info see http://en.wikipedia.org/wiki/IntelliSense

How do you think about it?

kind regards, Han

P.S. the implementation of auto-completion might be improved by showing automatically after a marker character (i.e. period), and not by pressing the tab-key

Han, this is a great idea and something about which, given its near ubiquity in IDEs, we’ve thought a good deal. There are some challenges. Take MESH or SURF, for example: showing a popup that listed “varargin” as the arguments wouldn’t be particularly helpful. I’d be interested to hear your thoughts about what you’d like to see, however.

As for the idea about having the completion show up automatically – I like it! We’ll take it into consideration.

I like the idea of being able to access this feature from the keyboard (I don’t use the mouse much – I’m a vi hack). However, using the “Escape to close” is a bit problematic. I hit it twice accidentally … the first Escape closed the micro-help window, the 2nd Escape erase my entire line. Oops.

Is there any way to Escape this behavior, to change the key that closes the window? Or is there no Escape from Escape?

“You cannot Esc; you are control-F (ASCII 6).”

“I am not a number; I am a free man!”

Tim, before I get to your question, more importantly, I am a huge fan of The Prisoner. It’s great to see a reference. We watched the whole series in school when I was 13 or so. The memories remain vivid. Remember the episode involving the computer that could predict everything, which Number 6 blows up by asking it, “Why?” Good stuff.

OK, so, your question. There is no disabling Escape to close. What would you like to see as the alternative? If you could disable it, would there be a keystroke to close it? Perhaps you are suggesting it should be a keystroke that’s less destructive at the Command Window.

Thanks for trying it out.

Jared

Yes, I think an alternate keystroke would be great. Something in the File -> Preferences… -> Help dialog perhaps. Escape and F1 are very close to each other; it’s very easy to hit one key instead of the other, and two accidental Escapes clears your line (there’s a pun buried there too – Ernest Goes to Jail maybe – but I’ll stop ;-).

Another comment: if I’m in the middle of “plot”, for example:

plot (x, sin(x),

and am trying to remember the color codes, the mini-help at this point just gives me the top-level “About MATLAB” page. Would it be possible to parse the input line to determine the current open parenthesis , so that “doc plot” would come up?

I also see that operator help doesn’t come up. If you type A\ then hit F1, it would be nice to see “doc mldivide” instead of the “About MATLAB” page. Or if someone can’t remember if they need A.’ or A’, etc. In some cases it’s unclear what the behavior should be (is A. the beginning of A.member, A.*, or something else?).

Jared,

I just checked out how Visual Studio displays help for variable arguments.

They show a list of possible calls of the function. I was however not able to find a screenshot of this.

You could check the solution printfCS.sln as supplied with VS2005.

kind regards, Han

Tim, I like suggestion #1 about looking for the function you’re in. Right now the rule is essentially: look to the left, and look beyond parentheses, if there are any. The rule could be expanded fairly easily. I suppose the meta-rule is: “Avoid the About MATLAB page” whenever it’s remotely possible to guess at something more specific about which the user would like help.

Showing operator help would be clever as well. I hadn’t thought about that. I’ll record these ideas as enhancement requests.

Reply to Steve’s comment: the “View -> Page location” menu option is new to MATLAB 7.4, which is why I missed it.

Jared: yes, the “Avoid About” meta-rule would be great – thanks for adding that to the enhancement wish-list.

The rule should try to find the topmost unfinished function argument list or operator/expression, if possible. Maybe that’s too much to parse.

Thus

why F1
why( F1

would both pull up “doc why”, as they do now.

why(42 F1

right now pulls up the “About MATLAB” page, but since the open function is “why” it should pull up “doc why”. Maybe it should pull up http://www.hitchhikersmovie.com/ but that’s another story ;-).

why([42 ; F1

should not pull up “help why”, since the unfinished expression is the “[ ;” concatentation. It should pull up “doc vertcat” or “doc paren”. I’m not sure which it should do… maybe “doc vertcat”. Pick whichever makes for a simpler rule, I guess.

For the plot example:

plot (x, sin(x) F1

would pull up “doc plot” since sin(x) is a finished expression. But

plot (x, sin(x F1

would bring up “doc sin” as it does now.

As a fun aside, why(42) returns:
“To satisfy the tall and good not excessively terrified mathematician.”

Thanks,
Tim (a 6’2″ applied mathematician … I’ll let you fillin the rest…)

Correction. The rule should either find the unfinished operator, or the *bottom-most* unfinished function, not the top-most. So

plot (sin ( F1

returns “doc sin” as expected, not “doc plot”.

Tim, how about you just write the code for me?

I agree with the bottom-most rule. But how would you propose distinguishing between

sin(foo F1

where “foo” is a mere variable, and generates no useful help, and

sin(tan F1

where “tan” does indeed generate useful help? I guess the rule there is, if there’s no help on it, move on down the line to the next item until you do find something with associated help. (So in the example above, if you press F1 at “sin(foo”, you get help on “sin”. If you have complete garbage, “foo(baz”, well, you probably don’t get anything.)

Jared, I’m already tied up with backslash… :-)

Good point about foo vs. tan. I hadn’t thought of that. I’m not sure what the best solution is. Your solution seems reasonable.

Not sure if this thread is still active since it has been 3.5 years since the last post…

I was wondering if there was a way to manually call the Help on Selection feature for a given function. Similar to how I can call doc(function) it would be nice if I could pop up the Help on Selection instead. My goal would be to have a GUI button execute this in a callback.

@Paul,

This is not possible. The only exposed API’s is to use help to show the file help in the Command Window, or doc to show the documentation in the Help Browser.

This is the most idiotic, annoying and unnecessary feature in Matlab to date. It serves absolutely no purpose at all except to break your concentration. Moreover, it is impossible to disable. Yes, I’ve tried all the standard things but to no avail. Finally, I deleted the whole Help folder manually which seems to have killed it.

These postings are the author's and don't necessarily represent the opinions of MathWorks.