JMP Scripting Index feedback and discussion

[#1]

Disclaimer:

This will be a fairly lengthy post and took a fair bit time to write. It will also be a bit unstructured as I added more things when they came to my mind while writing it. These are all my own (strong) opinions based on my few years (4) of JMP usage. I have also a list of issues with JMP's Online Help page, but I try to avoid most of that feedback here.

JMP Scripting Index is great (and necessary) help when writing JMP Scripts. I even use it as general search for JMP features. I will divide this post to couple of different sections and might make Wish List item(s) based on the discussion here.

Scripting Index, JMP Help, Scripting Guide and JSL Syntax Reference

Which documentation should I rely on? All of these provide different/same information in different/same format. Also sometimes they have conflicting information (see Items() below for example). I would like JSL Syntax Reference and Scripting Index to have the same information. For example currently Scripting Index is lacking arguments and return information and you have to decrypt them from description.

Also the experience of using JMP Help online version's search is quite bad. Only reliable way to use it I have found, is to either first find the function/feature from Scripting Index and hope you have working Help button or in some cases Google Search with "jmp help search term" but this isn't too reliable. Searching the information from .pdf versions of Scripting Guide and JSL Syntax Reference is usually faster than just relying on online help pages search. If I for example try to find Remove From function by using JMP Help's search, it won't even be on the list.

Also I haven't really used JMP17's Search feature, but I think it isn't made for JSL purposes as it is context related.

Links for some of the documentation:

Scripting Guide (online), Scripting Guide (pdf) 

JSL Syntax Reference (online), JSL Syntax Reference (pdf) 

Scripting Index format

Is it really necessary to read "Description" to understand all the parameters and what is returned? Could they be added as their own bolded parts in similar manner as Version Added in JMP17?

Below is exceptional Paint example with Returns added (with missing words "a list"), in best case also Arguments should be there (and maybe even throws).

JMP parameter list description/format

Is there anything like this for JSL Parameter List (Visual Basic) as in is JSL parameter list syntax explained anywhere? When I started scripting I was fairly confused by some of these (also I would like to use same format when I write my own Custom Functions). For example what do |, <>, =, and so on mean? My guesses: | -> or, <> -> optional parameter, = -> default value.

How does user know what should be written out in the function call? How does user know default parameter values WITHOUT reading description every time. Below are some quick examples I know of:

Contains():

pos = Contains(x, item, <start=1>)

Parameter naming is definitely not the best here (x?) but otherwise it is quite ok. Default value for start is defined here but how does user know if start should be written out or not? Can it be skipped because it is written using = instead of () (which would make it a function?)?

Items():

wl = Items(<[first last]>, s, <delim>, <Include Boundary Delimiters(0|1)>);

Default value for delim? Should Include Boundary Delimiters be written out or not? What does it default to? What does [first last] mean? It is not explained in the documentation (which documentation I should use...?) Items(string, <delimiter>, <Include Boundary Delimiters(Boolean)>) it is even missing from Syntax Reference but found from Scripting Index. 

Is it being removed in future version of JMP (so I don't want to use it) because it is missing from documentation? Was it added recently so some documentation is just out of date (so I can use but, I just have no idea what it does without trying it out).

Hex():

h = Hex(value, <"integer">|<encoding="utf-8">|<Base(number)>,<Pad To(number>));

Default values? Why I don't have to write out encoding, but I have to write out Base and Pad To(at least based on Scripting Index example). Can I see this from brackets () after the parameter?

And there are many many more similar examples in Scripting Index.

Scripting documentation issue reporting

How should I report possible issues within Scripting Index (and other documentation)? Creating Wish List items or sending support tickets is out of question for this. I don't want to spam hundreds of messages to either place just to get some typo's fixed.

Quick example by using Remove From(), for starters the descriptions are different in Scripting Index and JSL Syntax Reference and JSL Syntax provides more information what the function does but lacks examples. Also the function descriptions are different in Scripting Index vs JSL Syntax Reference... and the functions should behave differently based on this?

Remove From( x, <i>, <n=1> ) vs Remove From(source, position, <n>),

First is saying that i and n are optional, but for some reason i has no default value (it seems to be -1).

Second one says that second argument is mandatory and n is optional with no default value.

Scripting Index (Remove From isn't supposed to return anything based on this?)

Online Syntax Reference has wrong information on Returns (it does return the removed items and modifies source in place).

[#2]

Hi @jthi,

thank you for this post.

I hope this can trigger a discussion which will lead to a much better Scripting Index - there is so much potential to make it awesome.

I like your rhetorical questions:
- Should Include Boundary Delimiters be written out or not? 

- if start should be written out or not? 

Seems that all of us had to find out "alone" - by trial and error - to understand the underlying logic.
... and with a lot of help by you and @txnelson 

I agree: 

It's really a pain for the users that the arguments and optional arguments are written in this block text instead of listing them one by one - e.g. first the most used ones and then after clicking on "get more" a list of all options.

Another thing that I want to repeat here:
It's great to have this Index - but sometimes it feels like:

If you don't know the correct function name, I cannot give you the correct info.

Especially as JSL has dozens of slightly different "idioms":

set(), get(),  get values(), set property(), get items()

n items(), nrows(), n row()

append(), insert()

What could help: more entries under  "see also" - to guide users which got already close to the function they searched for:

get clipboard ➞ set clipboard

N Args ➞ Head

Some while ago, I posted a "container" wish to collect such missing links such that they can be added in a future release:
Scripting Index and online Help: "see also" 

In the meantime, the list gets longer and longer.

I also added some screenshots of wrong or missing descriptions ...

I guess that many others also found such bugs/missing info - so please feel free to contribute ...

[#3]

At the end we should get something like this:
 https://reference.wolfram.com/language/ref/Plot3D.html 

A documentation with the spirit of:
Let's show the user everything that is possible with our program.
Not a single, tiny detail should be left un-explained.

• examples with different levels of complexity
  starting with basic examples like 

  Names Default To Here( 1 );
  ex = Expr( a + Sqrt( a ) );
  Substitute Into( ex, Expr( a ), Expr( b ) );
  Name Expr( ex );

  then explaining many possible applications (if possible: so many that even sub-categories are necessary
  and always ending at neat examples with examples which make you think:
  Woah, it's amazing that this is possible!
  
  
• all options should be nicely listed (see: details and options)
  and the most important options should be presented with an individual example how they can be used (see: examples/options)

• very important:
  If there are things which the user has to know, there should be an additional block 
  
  

  with links to important posts from the community:
  Col Functions and Row States 
  Should you Loop through a data table or use Recode, or use Get Rows Where to change values in a data... 
  How do I use the Col Maximum Formula with a "where" condition 

• and most important:
  "see also" lists at least 10 related functions
  such that it gets unlikely that the user searched a function that is missing in the list

[#4]

A general question concerning the usage of the Scripting Index:

Let's say:  I want to get some info about Outline Box from the Scripting Index.

When I search for Outline Box, the first step is that Outline Box shows up (2x) under Item Name matches in the list on the right:

When I click on the top entry, I see a short description of the Outline Box Constructor and a example how to generate one
(and there is a danger that I get trapped here).
But more important: I notice that the Outline Box entry in the left list gets visible and marked grey (actually it was already marked grey before, but hidden further down in the scroll box).

Now I can click on Outline Box in the list on the left

and finally I just have to empty the search field and end up with

A nice overview of all details concerning the OutlineBox object,

first the constructor and then all all messages that can be sent to the object.
And for each message, one can see a nice example how it can be used *)

Is this the intended way to get here - there is also a faster way, right?

[#5]

*) Jmp 18 ?
(including a detailed description of the arguments for the constructor and properties of the object)

[#6]

Hi All,

  I agree with everything that has been brought up by @jthi and @hogi . Currently on JMP Pro 16.1.0, but transitioning to Pro 17.0 soon.

  Although I find the Scripting Index to be an invaluable tool for my scripting and analytics needs, I also find it to be very lacking. I own the JMP 14 Scripting Guide (hardcopy book), which I have also used extensively, but I still find lacking as well. Granted, it probably isn't feasible to have the entirety of the Guides contained within the Scripting Index, but certainly both can be updated to reflect the most recent version of JMP. I feel like both are somehow stuck in previous versions of JMP.

  And yes, when performing an online search through a search engine, one must specify very precisely what they're after and include keywords like "JMP Help...", and even then it's not always successful in finding the relevant JMP Help webpage.

  One of the things that I find to be lacking in both cases is the limited set of examples and explanation of syntax usage for successfully running the code. When I am able to find the right commands that I need for a particular project in JSL, I find that the examples don't adequately capture the various different ways the command can be used/called/executed -- I often find myself pushing the envelope with the commands and examples and having to turn to the community discussion boards for help (don't get me wrong, the community pages are critical and extremely helpful and much appreciated), it just seems that with some situations, it should be possible to quickly find the answer via the Index or Guide, but it's not and the community help is needed.

  Having been a long-time Mathematica user, I completely agree with what @hogi is referring to. The help pages in Mathematica are well-developed, contain basic examples, scoping, applications, options, properties and relations, and more, like the See Also related topics. I particularly like the Neat Examples that Mathematica includes as they tend to have examples that show how to do something different.

  I find that a lot of the time when people are looking for expanding the capabilities of a routine, they are looking to do exactly that, something different  that doesn't fall under the "standard" examples. I'd love to see the Scripting Index and Scripting Guides tackle these issues. I also think it would be a great benefit to have more consistency in syntax across JSL.

DS

[#7]

@jthi , @hogi , @SDF1 great discussion.  Wanted to let you know that we  are tracking it and have linked it to the wish list request here: 

Comprehensive scripting index 

Keep other good ideas coming!  Thanks.  

[#8]

I do really like the idea of aggregating all the information contained in various help sources in one place, and for JSL stuff the scripting guide is slick.  That doesn't mean making that one place a book, rather it could include links (least preferred), popups, or collapsed outline boxes containing more information.  As others have said, I also find myself needing to look in multiple documents to understand how to use a function and then look other places to find relevant examples.

[#9]

This is more or less related to Scripting documentation, but new JMP version release notes are lacking proper examples.

I hadn't really checked the scripting notes yet for JMP17, but noticed some possibly nice new features

1. You can now store JSL symbols on project and window display boxes (Allow class methods as display box callbacks?)
2. Display Boxes can now directly call methods on the class from which they were created. This enables scripts for interface controls like buttons and sliders to access data on the class (Display Box Data Storage?)
3. Three new JSL built-in functions: With Window Handler(), Set Global Window Handler(), and Clear Global Window Handler()
4. You can now script the font picker, most file picker dialogs, and simple host alerts (such as Yes/No and Yes/No/Cancel)
5. New Window() now supports the creation of the following window types: Modal Dialog, Dialog, and Launcher.
   1. Why aren't Report, Journal and Script mentioned as those are also possible values for Type()?

Too bad I couldn't really find good examples for these or any explanation what these do. Scripting Index does have some but Scripting Guide and JSL Syntax seem to have nothing. 

With Window Handler (no Topic Help available and not found from JSL Syntax Reference):

Syntax for New Window seems to have changed (new << Type("")  and script/displaybox part has changed)

JMP17:

y = New Window( title, < <<Type("Report" | "Dialog" | "Modal Dialog" | "Journal" | "Launcher" | "Script")>, < << Return Result>, < << On Open(expr)>, < << On Close(expr)>, < <<On Validate(expr)>, < <<Show Menu(0 | 1)>, < <<Show Toolbars(0 | 1)>, < <<Suppress AutoHide(0 | 1)>, < <<Window View("Visible" | "Invisible")>, < <<Size(h, v)>, displayBox | script)

JMP16:

New Window( title, < < <<Modal>, < <<Return Result>, < <<On Open( expr )>, < <<On Close( expr )>, < <On Validate( expr )> >, <Show Menu( 0|1 )>, <Show Toolbars( 0|1 )>, <Suppress AutoHide( 0|1 )>, < <<Script, "script" | <<Script("script")>, < <<Journal>, displayBox )

but online JSL Syntax Reference is still using << Modal and not <<Type("Modal Dialog") . 

Will << Type("Modal Dialog") replace <<Modal at some point? What is the purpose of those new flags and when should they be used: < <<Type("Report" | "Dialog" | "Modal Dialog" | "Journal" | "Launcher" | "Script")>? "Report" is default behaviour, "Modal Dialog" seems to be same as <<Modal, "Dialog" seems to hide toolbar and menu, "Launcher" no idea (same as Dialog?), "Script" creates script window, "Journal" makes the window Journal.

Also it would be nice to have Change Log in Scripting Index (or somewhere else) as it is fairly common to jump around different versions of JMP (especially when answering questions in JMP Community where some people are still using very old versions of JMP).

[#10]

I just found an easteregg in the Scripting Index: Lineup Box

It provides a 1col  "grid" as a (very special but neat : ) example for Line Up Box :

Fortunately, the "official" Version of Line Up Box (notice the additional space) provides a more general example:

The only thing ...
When the user Alt double-clicks a LineupBox/Line up Box/Line Up Box in JSL Editor, JMP opens the easteregg - without link to the official entry ...