[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Syntax for GLOBAL, LOCAL and STATIC

20 Nov 2019, 11:28

The documentation for GLOBAL, LOCAL and STATIC commands (statements?) is not very clear.

1. There is no EXPLICIT syntax shown for these statements

From reading the documentation, I do not know

a. Can I have more than one GLOBAL/LOCAL/STATIC statement in a function?
b. Can such statements define more than one variable?

I can INFER the answer to B because an example shows:
SetDefaults(){
global ; This word may be omitted if the first line of this function will be something like "local MyVar".
MyGlobal := 33 ; Assigns 33 to a global variable, first creating the variable if necessary.
local x, y:=0, z ; Local variables must be declared in this mode, otherwise they would be assumed global.
}
However, I should not have to make INFERENCES about how things work.

2. I don't understand why STATIC, LOCAL and GLOBAL are not given the status of COMMANDS (and, thus, are not given their own syntax boxes).
Helgef
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: Suggestions on documentation improvements

20 Nov 2019, 12:04

@joefiesta,
Can such statements define more than one variable?
:arrow: More about locals and globals.
statements?
concepts wrote: Statement
A statement is simply the smallest standalone element of the language that expresses some action to be carried out. In AutoHotkey, statements include commands, assignments, function calls and other expressions. However, directives, labels (including hotkeys and hotstrings), and declarations without assignments are not statements; they are processed when the program first starts up, before the script executes.
Can I have more than one GLOBAL/LOCAL/STATIC statement in a function?
I'm not sure what you are asking.

It is better to ask for help first (in the help forum), then you can make a suggestion on how to change the docs if needed.

Cheers.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

20 Nov 2019, 12:13

@Helgef:

If I can't figure something out by reading the doc, then the doc needs changing, I am stupid or the doc is too complicated for me to understand. The latter two are not the case here.

You pointed out my question: Can I have more than one GLOBAL/LOCAL/STATIC statement in a function? Let me reword it:

the doc does not EXPLICITLY tell me which of the following 3 ways to declare multiple globals are valid:

a. Global abc def
b. Global abc, def
c. Global abc
Global def

edit: I would also like to point out that b is not intuitive. That is because of this statement at "variables and expressions":

Comma (multi-statement) [v1.0.46+]. Commas may be used to write multiple sub-expressions on a single line. This is most commonly used to group together multiple assignments or function calls

Reading that makes me believe the syntax (for b) should be: global abc, global def
Helgef
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: Suggestions on documentation improvements

20 Nov 2019, 12:46

The docs explicitly mentions that Global abc, def is valid, if you would follow the link I provided.
global variables wrote:To refer to an existing global variable inside a function (or create a new one), declare the variable as global prior to using it
Which obviously means that

Code: Select all

Global abc
Global def
is valid too.
If I can't figure something out by reading the doc, then the doc needs changing
No, when you can't figure something out, the first thing to do is not to ask for help in this thread, use the help forum as everyone else.

Cheers.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

20 Nov 2019, 13:12

I think the problem thus boils down to this. The GENERAL information about all 3 variable types should be discussed BEFORE the specifics of each variable type. the way it is now written, once I get to the end of reading the section on GLOBAL VARIABLES I get to LOCAL VARIABLES and assume that is the end of information about GLOBAL VARIABLES.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

1.1.32.00 - What is a CLOAKED window?

25 Nov 2019, 12:40

What is a cloaked window?

References to cloaked windows were added without defining cloaked windows.
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: 1.1.32.00 - What is a CLOAKED window?

25 Nov 2019, 16:48

joefiesta wrote:
25 Nov 2019, 12:40
What is a cloaked window?

References to cloaked windows were added without defining cloaked windows.
see here:
https://www.autohotkey.com/boards/viewtopic.php?p=296293#p296293

john_c
Posts: 493
Joined: 05 May 2017, 13:19

Re: Suggestions on documentation improvements

27 Nov 2019, 04:16

If I recall correctly, it was possible to use both [] and {} for both simple and associative arrays.

Code: Select all

; Worked
SimpleArr      := ["Foo", "Bar", "Baz"]
AssociativeArr := {"Aaa": "Foo", "Bbb": "Bar", "Ccc": "Baz"}

; Worked too. But I'm not sure.
SimpleArr      := {"Foo", "Bar", "Baz"}
AssociativeArr := ["Aaa": "Foo", "Bbb": "Bar", "Ccc": "Baz"]
Now the only first version work. (I use 1.1.31.00)

In case this observation is true, it should be reflected in the docs, because the current information looks outdated:
In AutoHotkey v1.x, simple arrays and associative arrays are the same thing. However, treating [] as a simple linear array helps to keep its role clear, and improves the chance of your script working with a future version of AutoHotkey, which might differentiate between simple arrays and associative arrays.

(from https://autohotkey.com/docs/Objects.htm#Usage_Associative_Arrays)
Also, the word "linear" to my opinion, is excessive and confusing. It was discussed here: https://www.autohotkey.com/boards/viewtopic.php?f=76&t=47338
gregster
Posts: 8916
Joined: 30 Sep 2013, 06:48

Re: Suggestions on documentation improvements

27 Nov 2019, 23:57

john_c wrote:
27 Nov 2019, 04:16
If I recall correctly, it was possible to use both [] and {} for both simple and associative arrays.

Code: Select all

; Worked too. But I'm not sure.
SimpleArr      := {"Foo", "Bar", "Baz"}
AssociativeArr := ["Aaa": "Foo", "Bbb": "Bar", "Ccc": "Baz"]
Afaik, your second syntax version was never valid.

What you probably remember and what you can still do, is create an empty object/array with { }/[ ] and then use both either way, for a simple or an associative array. Hence, this works:

Code: Select all

arr := []
arr["hello"] := "world"
msgbox % arr["hello"]

obj := {}
obj.push("hello world")
msgbox % obj[1]
john_c
Posts: 493
Joined: 05 May 2017, 13:19

Re: Suggestions on documentation improvements

28 Nov 2019, 01:56

gregster, yes, you are correct. I downloaded the April version and tested it. There are no changes here.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

28 Nov 2019, 10:44

While working on this:
GitHub: contributing to the AutoHotkey documentation - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=81&t=70225

I noticed some inconsistent character entities on this page:
Using Numpad as Mouse - Script Example | AutoHotkey
https://www.autohotkey.com/docs/scripts/NumpadMouse.htm

Code: Select all

176	00B0	°	DEGREE SIGN
186	00BA	º	MASCULINE ORDINAL INDICATOR
Diagnosis: replace º with °.

Also, this is great already, but perhaps users will have more ideas for it:
v2 docs contribution questions - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=37&t=49735&p=221055#p221055

Thanks.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
neogna2
Posts: 586
Joined: 15 Sep 2016, 15:44

Re: Suggestions on documentation improvements

28 Nov 2019, 14:01

Two convenience requests for AutoHotkey.chm (the AutoHotkey Help file).
1. Toolbar button that gets the URL to the web version of the current help file page and opens it in the default browser.
2. Toolbar button that copies that URL to clipboard.

The script below copies the URL to clipboard. But a Toolbar button is nicer to have.

Code: Select all

;Get URL to web version of active AutoHotkey .chm helpfile page

#Include Acc.ahk 

; Sample string extracted using Acc
; mk:@MSITStore:C:\Program%20Files\AutoHotkey\AutoHotkey.chm::/docs/commands/RegExMatch.htm
; Sample web version URL
; https://www.autohotkey.com/docs/commands/RegExMatch.htm

HelpWin   := "ahk_class HH Parent ahk_exe hh.exe"
WinActivate, % HelpWin
If !WinActive(HelpWin)
  ExitApp
AccPath   := "4.1.4.1.4.1"
AccString := Acc_Get("Name","4.1.4.1.4.1",0, HelpWin)
Stub      := RegExReplace(AccString, "^.+chm::/(.+\.htm)$", "$1") 
Url       := "https://www.autohotkey.com/" Stub
Clipboard := Url
tooltip, %url%
sleep 800
tooltip
ExitApp
Edit: a quick kludgy edit is to change this line in the helpfile source
https://github.com/Lexikos/AutoHotkey_L-Docs/blob/master/docs/static/content.js#L944
from

Code: Select all

    $chm.find('li.print').on('click', function() { window.parent.document.getElementById('frame').contentWindow.document.execCommand('print', false, null); });
to

Code: Select all

    $chm.find('li.print').on('click', function() { window.open("https://www.autohotkey.com/" + location.href.match(/chm::.(.*htm)/)[1] ); });
to make the "Print" icon button instead open the web version of the help page.
john_c
Posts: 493
Joined: 05 May 2017, 13:19

Re: Suggestions on documentation improvements

29 Nov 2019, 01:41

Code: Select all

; https://www.autohotkey.com/docs/commands/For.htm
For Key, Value in Expression

; https://www.autohotkey.com/docs/misc/Arrays.htm
For Index, Element in Array
It could be better to use Value (not Element) for both pages. There is a separate thread: https://www.autohotkey.com/boards/viewtopic.php?f=81&t=69832
User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

30 Nov 2019, 04:18

neogna2 wrote: Two convenience requests for AutoHotkey.chm (the AutoHotkey Help file).
1. Toolbar button that gets the URL to the web version of the current help file page and opens it in the default browser.
2. Toolbar button that copies that URL to clipboard.
The first request seems reasonable. I will add such a button. However, I think that this button is enough because it will offer several possibilities to retrieve the link, e.g. by right-clicking the button, selecting properties and copying the link there (which of course is not as convenient as with more modern browsers where you can select "Copy link address").
neogna2
Posts: 586
Joined: 15 Sep 2016, 15:44

Re: Suggestions on documentation improvements

30 Nov 2019, 10:22

Ragnar wrote:
30 Nov 2019, 04:18
The first request seems reasonable. I will add such a button. However, I think that this button is enough because it will offer several possibilities to retrieve the link, e.g. by right-clicking the button, selecting properties and copying the link there (which of course is not as convenient as with more modern browsers where you can select "Copy link address").
Thank you. Regarding the second request: The new button could handle that too through a middle click action. Quick javascript/jquery sample code below, using the 'Print' icon again. The on mouse over tooltip for the new button could say "Click to open in browser.`n (Middle click to clipboard.)" Users who want to clipboard the URL then have a one click method without an extra button cluttering the UI.

Code: Select all

    //click middle mouse button on 'Print' icon to copy URL to web version to clipboard
    // https://stackoverflow.com/a/2725963
    // https://stackoverflow.com/a/42416105
    $chm.find('li.print').mousedown(function(e) { if (e.which == 2) { 
        var tempInput = document.createElement("input");
        tempInput.style = "position: absolute; left: -1000px; top: -1000px";
        tempInput.value = "https://www.autohotkey.com/" + location.href.match(/chm::.(.*htm)/)[1];
        document.body.appendChild(tempInput);
        tempInput.select();
        document.execCommand("copy");
        document.body.removeChild(tempInput);
        }
      });
neogna2
Posts: 586
Joined: 15 Sep 2016, 15:44

Re: Suggestions on documentation improvements

01 Dec 2019, 12:26

In general I wish that defaults where made more visible in the docs in a consistent way and when possible placed near the top, close to the yellow syntax boxes. E.g. a standardized phrase or color for marking what the default is and/or for text that describe defaults. Some of the docs pages use "(default)" which is short and easy to spot and find with search. But some other docs pages don't.

One example: https://www.autohotkey.com/docs/commands/Sort.htm does not explicitly say what the default sort order is.

This sentence

- Arranges a variable's contents in alphabetical, numerical, or random order (optionally removing duplicates).

could be changed to inform about the default

- Arranges a variable's contents in alphabetical (default), numerical, or random order (optionally removing duplicates).

or to make the default stand out even more
- Arranges a variable's contents in alphabetical (default), numerical, or random order (optionally removing duplicates).
- Arranges a variable's contents in alphabetical, numerical, or random order (optionally removing duplicates).
- Arranges a variable's contents in alphabetical (default), numerical, or random order (optionally removing duplicates).

edit: defaults can also be clarified by making the first example in the Example section always use defaults and clearly describe what the output of that use is.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

01 Dec 2019, 13:59

@neogna2 : Copying URL to clipboard is easy with Firefox:

Ctrl + L (selects location bar) Note: Also done with Alt+D and F6. why 3 ways? I wish I knew.
Ctrl + C (copies location (URL))

Other browsers? Should be as easy, but I have no idea.
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

02 Dec 2019, 00:24

a106 wrote:
  • Changed DllCall to throw if a numeric-type parameter is non-numeric. In particular, if the * or P suffix is used for output parameters, the output variable is required to be initialized. This improves robustness and compatibility with #Warn.
this bit(or some more easily digestible variation thereof) needs to somehow make its way to the v2 dllcall page. emphasis mine
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

07 Dec 2019, 10:20

StrPutGet page:
https://www.autohotkey.com/docs/commands/StrPutGet.htm wrote: Scripts which are required to be compatible with AutoHotkey Basic can still use StrPut and StrGet provided that the appropriate script files are installed in a function library. These scripts can be found at the archived AutoHotkey Forum.
however, there are no download links in that old forum thread, only a pasted function by Rseding. however, Lexikos mentions in the thread that he had fixed some bugs, and so we don't know if the paste by Rseding is the latest or not.

this link here shows a slightly different version, so i don't know which is the one with the bug fixes:
https://autohotkey.com/board/topic/96362-need-help-updating-a-function-from-ahk-basic-to-ahk-l/

joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Exitapp and ErrorLevel re. RUN vs RUNWAIT

15 Dec 2019, 10:55

EXITAPP doc states (about it's EXITCODE parameter):
This code is accessible to any program that spawned the script, such as another script (via RunWait) or a batch (.bat) file.
This is not 100% correct. (Or, if you disagree: this could use some further clarification.)

I am talking about the word ANY. The exitcode that is returned is NOT accessible to another script that spawned a script or program using the Autohotkey RUN command.

Thus, the doc should read something like:
This code is accessible to any program that spawned the script, such as another script (via RunWait) or a batch (.bat) file, with the exception of having been spawned by the Autohotkey RUN command.

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 6 guests