# Strange ::usage behavior in v9

Note: This is fixed in 9.0.1.

Something has gone wrong with usage in Mathematica 9. Would someone tell me how to fix it?

I define a function pR with a usage such that there is a line break (see below)

pR::usage = "pR[s,m0,m1] is a function that looks like

pR(s,m0,m1)=s+m0+m1.";
pR[s_, m0_, m1_] := s + m0 + m1


And then, I subsequently call the defined function the next cell (without running it),

pR[a,b,c]


Then, when I move with the cursor somewhere within the arguments of the pR function, and move it left and right with the arrow keys, I get a bunch of StringMatchQ::strese errors which makes no sense to me.

But if I remove the line-break,

pR::usage = "pR[s,m0,m1] is a function that looks like
pR(s,m0,m1)=s+m0+m1.";
pR[s_, m0_, m1_] := s + m0 + m1


and try calling the function and placing my I-beam in the argument, I don't get these strange errors. Can anyone help?

-
Have you tried using a \n character instead of this visual line break? –  Sjoerd C. de Vries Jan 27 '13 at 7:45
I confirm this bug (version 9.0.0 for Windows). It seems that simple movement of the insertion point in version 9 results in evaluations in the kernel! Very weird and looks as bad design... –  Alexey Popkov Jan 27 '13 at 9:47
Yes, I've noticed this same kind of effect in V9, but I never suspected it came from usage messages! The entire usage message design in Mathematica is out of date and a kludge. It should go something like this: Usage[functionname]={{template, usage}..} where usage could be any expression and there could be multiple templates and usages for different forms and command completion for the arguments. Che. UMLF (Usage Message Lberation Front) –  David Park Jan 27 '13 at 13:30
Confirmed on v9 on OS X 10.8.2 as well –  rm -rf Jan 27 '13 at 14:50
@jarod I converted your answer to a comment (because it is a comment). I know that at this point you don't have the "privilege" to post comments but once you do please remember to use it. –  Mr.Wizard Jan 30 '13 at 9:46

Answer: Fixed in 9.0.1. 9.0.1 is a free upgrade for registered 9.0.0 users, and is available for download from the Wolfram User Portal.

Explanation as to why/how it was busted. This is not something I would typically post at all. Not because I'm afraid to show how the sausage is made (for those who have the stomach), but more because it seems off-topic and not particularly useful. But a request was made in the comments and voted up multiple times, so here goes.

In version 9, we significantly revised the code completion and function template insertion features. One of the bits of code which is related to this work is code which scans the usage messages looking for possible templates to be used in the function template menu. A version of this code was also used in v8, but in v8, it was asked to do a simpler job -- just pick off one usable template (the first one it can find) from the usage message and then insert that function template. Whereas, in version 9, we now present a menu of templates, so it's now harvesting as many function templates as it can find, which happen to be delimited by newlines.

So this code was revised accordingly in v9. But it was not sufficiently bullet-proofed against arbitrary usage messages, nor well-tested against user-created packages. We did ship a version of this code in the beta test program, but it was in a later beta test. No reports came back from testers but, at that point, I think that it was maybe only 4 weeks before we shipped the final 9.0.0 release.

In the end, I think there were two real problems. One was the flawed usage-message-scanning code. The other is that the code was invoked much too often. The cruel irony is that function templates for user-defined functions didn't even work (also fixed in 9.0.1), despite the fact that the code was frequently invoked. I recently looked at this again in 9.0.1, and I was disappointed to see that we still hadn't cracked 100% the usage message scanning problem to my satisfaction (and reported the issue internally), but it is at least a significant improvement to the 9.0.0 behavior.

-
I don't know whether to expect that people will like this kind of answer or not. Maybe this answer was a mistake, or maybe it will be controversial. And I'm sensitive to doing anything which might be interpreted as karma-whoring. But egged on by rm in the comments above (the comments after the question), I decided to put it out there and see what happens. If you thought it was a waste of bytes, or an annoying list of excuses, or whatever, please say so. –  John Fultz Feb 3 '13 at 23:56
"And I'm sensitive to doing anything which might be interpreted as karma-whoring." You've got a long way to go... the bar is set high :D Seriously though, thanks a lot for the explanation! The main reason I suggested this was because personally, I find it fine (or "meh") to see a plain "fixed bug" status with no explanation on something like, say, Skype which I merely use as a tool and couldn't care less as to what went wrong. (continued...) –  rm -rf Feb 4 '13 at 0:18
However, for Mathematica, I (and most of us here) have invested time and effort in both, the software and language, and actually do care to know what went wrong. Sometimes the explanation flies over my head, but a lot of times, I learn something from it (and even when I don't immediately understand, I can always come back to it). I think little nuggets like this (even if not incredibly exciting) go a long way in making these questions be more than a poor-man's bug tracker. Thanks again! :) –  rm -rf Feb 4 '13 at 0:18

Unformatting the usage message cell and changing \n\n to \n\\[IndentingNewLine] will cure it.

-