40
$\begingroup$

Since Mathematica 9, a number of issues concerning the ::usage and templates were raised.

In 9.0, there was a bug first reported here and better diagnosed here, where error messages were generated by simply moving the insertion point somewhere in the argument of a function for which a ::usage was defined. This was fixed in 9.0.1

Starting in version 9.0 and observed through 10.4.1, it was reported here that functions with formatted ::usage needed ?Function to be called twice in order for messages to be rendered properly. A bandaid solution was given here.

Certain inflexibility about the text in the templates was raised here and again here, and inconsistencies reported here (also see here).

The consensus I gather from the discussion in the comments above is that ::usage and templates are implemented in Mathematica in a very kludgy way. This can be a source of major frustration for package developers.

So the question I raise is which of the issues have been addressed in v10 and v11? Are there plans for a major overhaul of the ::usage system?

Improve this question
$\endgroup$
5
  • 2
    $\begingroup$ In version 10.0.0 the formatted ::usage problem seems to be fixed, or at least I could not reproduce it. The completion template problems appear to remain. $\endgroup$
    – Mr.Wizard
    Commented Sep 2, 2014 at 10:25
  • 10
    $\begingroup$ @Mr.Wizard, I reproduced the formatting problem in version 10 using this code. Since it's been a problem since at least version 6, and there's a one-line fix, you'd think they'd have fixed it already. $\endgroup$
    – Simon Rochester
    Commented Sep 3, 2014 at 0:03
  • $\begingroup$ @SimonRochester does the formatting problem persist in v10.3? $\endgroup$
    – QuantumDot
    Commented Dec 13, 2015 at 22:28
  • 1
    $\begingroup$ The "need to call it twice" issue seems to persist in 10.3. $\endgroup$
    – Simon Rochester
    Commented Dec 14, 2015 at 21:37
  • 2
    $\begingroup$ Unfortunately, the "need to call it twice" issue seems to persist in 10.4 as well. $\endgroup$
    – MarcoB
    Commented Mar 6, 2016 at 4:59

1 Answer 1

Reset to default
8
$\begingroup$

1) The complete failure of Make Template with formatted usages is fixed in our next release. I can't promise you it will look 100% beautiful in all cases, but the number of templates will match the number in the usage message and you'll at least recognize it as something related to what you put in there. I'm sorry it's taken so long to be addressed--it really has been on our radar for some time--but the fix required a certain amount of cleanup that was not easy to do.

2) About the need to call information twice, we didn't fix it because it was never reported as a bug. There were a few internal reports, but nothing external. We can't fix what we don't know about. While we do monitor stack exchange, there is no substitute for actual bug reports send to support. This has the greatest chance of being routed to the right developer, and the more people how report it, the more resources might be spent on fixing the issue. I'll respond with more details on the appropriate question, but this issue is also fixed for the next release.

3) It's true that we don't provide the same capabability for developer templates as our own. For many reasons, our internal tooling has been constantly evolving since V9 came out. Deploying it to external developers, when we are not confident it is robust and stable, just hasn't been feasible. Hopefully we will get there, but we're certainly not in a position to promise on any particular schedule. In the mean time, we've dealt with two significant issues in our upcoming release. If there are more point fixes we can make to the current system, send in reports!

Improve this answer
$\endgroup$
2
  • 2
    $\begingroup$ It's nice to finally get an answer to this. Thanks! I recall placing three bounties worth 50, 100 and 200 on this question. $\endgroup$
    – QuantumDot
    Commented Jul 9, 2017 at 4:30
  • $\begingroup$ I will put forward a bug report but I would like to know whether I am not just doing something wrong. For me, "11.3.0 for Linux x86 (64-bit)", I never get the templates to work consistently. It seems that sometimes the usage message creates a template I can call with ctrl-shift-k but most of the time it does not. Should the usage always be defined before giving any function definitions. Changing just the names of the functions (in the usage definition) to something that already has a definition (downvalue) will make the same usage messaged that worked before fail for the new symbol. $\endgroup$
    – Kvothe
    Commented Nov 8, 2018 at 10:40

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.