]link.create (and others) have documentation shortcomings

[bernecky]

I am trying to use ]link.create on Ubuntu 20.10, with these Dyalog bits:

IDE:
  Version: 4.2.3437
  Platform: Linux x86_64
  Date: 2019-08-13 14:55:17 +0200
  Git commit: 691f47856e05a36f70847313b23e061a0cf95392
  Preferences:{
    "autoCloseBrackets":"0",
    "autoPW":"1",
    "autocompletionDelay":"250",
    "blockCursor":"1",
    "editWins":"{\"width\":1214,\"height\":708,\"x\":21,\"y\":787,\"ox\":0,\"oy\":0}",
    "editWinsRememberPos":"1",
    "floatSingle":"0",
    "floating":"1",
    "kbdLocale":"en_US",
    "lbarOrder":"← +-×*⍟⌹○!? |⌈⌊⊥⊤⊣⊢ =≠≤<>≥≡≢ ∨∧⍲⍱ ↑↓⊂⊃⊆⌷⍋⍒ ⍳⍸∊⍷∪∩~ ÷/\\⌿⍀ ,⍪⍴⌽⊖⍉ ¨⍨⍣.∘⍤@ ⍞⎕⍠⌸⌺⌶⍎⍕ ⋄⍝→⍵⍺∇& ¯⍬ ",
    "selectedExe":"/opt/mdyalog/17.1/64/unicode/mapl",
    "selectionHighlight":"1"
  }

Interpreter:
  Version: 18.0.39712
  Platform: Linux-64
  Edition: Unicode/64
  Date: Dec 11 2020 at 01:07:55

The ]link.create -?? docn has several problems for me:

1. The option values are listed, but there is no indication which of those, if any, are the default values. The default value should be readily visible in the help, (WITHOUT having to go to github, if it is on the air, to find out!), perhaps in bold face or a highly visible color such as puce (Just kidding...).

2. The create operation ignores ALL variables, but this is not evident (to me). The default action here, I believe, should be to include all variables, system variables, etc., so as to capture the entire app in a way that can be packaged and transported without further ado.

3. The advertised "-arrays=1" option does nothing, and does not produce an error or warning. HOWEVER, using "-arrays " does include all variables ( but no system variables). This should be fixed.

     )clear
clear ws
      outer←'outside'
      )ns junk
#.junk
      outer
outside
      )cs junk
#.junk
      )vars
      inner←'inwards'
      inner
inwards
      )cs 
#
      )vars
outer   
      outer
outside
      ]link.create # /tmp/crud -arrays
Link Warning: ⎕SE.Link.U.UCMD_Run: .NET or .NetCore not available - Link cannot watch directory
Linked: # → /tmp/crud
      ]link.status
 Namespace  Directory  Items 
 #          /tmp/crud      3 

[abrudz]

1. For multiple-choice values, the first value is the default. We should add a note about that.
2. I can see the value of that default, although often only non-variables are actually part of an application. Maybe a sensible middle ground would be to initiate a ns→dir link with all variables but ignore any subsequently created variables unless otherwise instructed. Regarding system variables, it would clutter every single directory. It is probably enough to include, on the top level, the ones differing from the defaults, and in subdirectories only include those differing from their parent's. At the very least, a warning is in order.
3. I believe that is a typo. Just -arrays without a value should include all.

[bernecky]

Thanks. I agree with all that.

Please highlight or bolden the default value, even though it is always first. That makes things easier for people scanning for stuff.

Your proposed treatment of system variables is good, especially on the "differing" fronts. Warnings are of little use, unless you provide specific information on what it doesn't like, and where. This is to avoid things like vague messages about some function, or perhaps functions, in the dfns workspace.

[abrudz]

We currently don't have the technology to highlight or bolden output text in the APL session.

[bernecky]

Highlighting: I meant in the docn, not in the "-??" stuff. Don't worry: some day, they will invent "the pencil", at which time these things will become possible.

[abrudz]

The ]link.create -?? docn has several problems for me: (…) The default value should be readily visible in the help, (WITHOUT having to go to github

I meant in the docn, not in the "-??" stuff.

I'm not sure what documentation you speak of. I would appreciate a bit of clarification here.

[bernecky]

Well, there is this page:

**https://github.com/Dyalog/link/blob/master/help/Link.Create.md**

Sadly, it is in github, so won't work in a web-free environment.

That page does, sort of, highlight what may be defaults, but I see no indication in any of the related pages that specifies that they are, indeed, defaults. This is why you want a tech writer to review anything written by a techie, particularly an author of the code, IMO.

The page also has things like:

caseCode (default off)

Whenever I see parentheses in what is ostensibly technical documentation, I get suspicious, particularly when it's my doing. Parentheses are a dead giveaway that what came before it is poorly designed. I suggest changing these things to a common form, such as:

caseCode nocaseCode with the default value in bold. This avoids the need for parenthetical apologies, and lends the document a uniformity that makes it all simpler and more consistent.

[abrudz]

I thought we included these help pages with the installation, but it appears that we don't. I suspect this is an oversight, and have made an internal enquiry on the matter. Thank you for bringing our attention to this.

The multi-choice defaults are bold, but I guess we could also move them up to be the first option.

You can add -caseCode or not. If you don't, that means "off". This is how user commands work. If you use the function interface, then you use caseCode←1 or caseCode←0. An example is given in the API help file: https://github.com/Dyalog/link/blob/master/help/API.md#option-namespaces

[bernecky]

I do not see any indication on the option-namespaces page that omission of an option means "off". The definition of option behavior should, IMO, be documented, not related as folklore.

[nicolas-dyalog]

-arrays and -sysvars have been added to Link v2.1.0, as modifiers to Link.Create and Link.Export

The documentation about unset options has been updated.

Apart from that, my understanding is that Bob is asking for the user command help to provide full documentation. I don't think the intention behind the -? UCMD modifiers is to provide full documentation. For example SALT has its own documentation too, and -? modifiers only provide partial summary.

[abrudz]

We are planning on having the currently online docs available as part of the installation too, and the user commands could then point at the local docs rather than the online ones.

[bernecky]

Having a pointed-to local copy of the docs sounds entirely fine to me.

Thanks for the extensions!