Option specifications in documentation is vague/missing/misleading

[bernecky]

In the ]link "documentation", the way that options are specified is not clearly specified, for either ]link or for ⎕se.Link. E.g., I am trying to get rid of the very annoying Link Warning in Ubuntu:

    )clear
    ⎕SE.Link.Create'#' 'Source/Root'
Link Warning: ⎕SE.Link.Create: .NET or .NetCore not available - watch defaults 
      to 'ns'
Linked: # → /home/apex/apexgit/Source/Root
      )clear
clear ws
      ⎕SE.Link.Create'#' 'Source/Root' '-source=ns'
LENGTH ERROR: Right argument must be a vector of correct length
      ⎕SE.Link.Create'#' 'Source/Root' '-source=ns'
      ∧
      )clear
clear ws
      ⎕SE.Link.Create'#' 'Source/Root -source=ns'
Link Warning: ⎕SE.Link.Create: .NET or .NetCore not available - watch defaults 
      to 'ns'
Linked: # → /home/apex/apexgit/Source/Root -source=ns
      )clear
clear ws
      ⎕SE.Link.Create'#' 'Source/Root -source=ns watch=ns'
Link Warning: ⎕SE.Link.Create: .NET or .NetCore not available - watch defaults 
      to 'ns'
Linked: # → /home/apex/apexgit/Source/Root -source=ns watch=ns

      )clear
clear ws
      ⎕SE.Link.Create'#' 'Source/Root -source=ns watch=ns'
Link Warning: ⎕SE.Link.Create: .NET or .NetCore not available - watch defaults 
      to 'ns'
Linked: # → /home/apex/apexgit/Source/Root -source=ns watch=ns

[abrudz]

I think the syntax is quite clearly described here.

[bernecky]

Let's see if I have this straight: you want to specify a text option, so instead of letting me do something functional, like:

'-source=ns" ⎕se... or '-source=ns -watch=ns' ⎕se...

I have to create a namespace, populate it with variables, pass the namespace as an argument to ⎕se, then trash the namespace when I am done. How utterly inconvenient, subtle, non-obvious, user-hostile, and other bad words.

Furthermore, if you just fixed the bug in the linux version of ]link, it would just work - no warning needed - and I might not care.

[aplteam]

There is a difference between the user commands and the API.

• For the user commands you may specify flags and options
• For the API you must create a namespace and populate it with variables according to your needs

I think that this is just fine.

[mkromberg]

I have updated the introduction to the API, which you can now find at https://dyalog.github.io/link/3.0/API/, to show how you can use ⎕JSON to create option namespaces, while we wait for support for array notation in the interpreter.