Closed bernecky closed 3 years ago
-arrays
without a value should include all.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.
We currently don't have the technology to highlight or bolden output text in the APL session.
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.
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.
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.
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
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.
-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.
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.
Having a pointed-to local copy of the docs sounds entirely fine to me.
Thanks for the extensions!
I am trying to use ]link.create on Ubuntu 20.10, with these Dyalog bits:
The ]link.create -?? docn has several problems for me:
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...).
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.
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.