[Archived, Locked] Suggestions on documentation improvements
Re: Suggestions on documentation improvements
yes, i expect if one is interested in finding out what a function does to go through the entire page. its a 2 min read tops. RGB will have been covered, so it absolutely is duplication.
Format() and "literal text"
The format() command states
Nowhere does it say how the TEXT is used or what purpose it serves. Additionally, the "text" is not shown in the syntax, which, I think should be something likeFormatStr
A format string composed of literal text and placeholders of the form {Index:Format}.
<text>{Index:Format}<text>
Re: Suggestions on documentation improvements
Neither 'AutoReload' and 'Shift+Tab' are docmented. 'Shift+tab' is the reverse action of {Tab}
Win 10 Professional 64bit 21H2 16Gb Ram AHK current as of 2021-12-26 .
Re: Suggestions on documentation improvements
And what is AutoReload? Never heard of it.. so does my AHK version, it seems. (I am guessing the syntax here.)
And Shift+tab is a standard MS Windows shortcut - what is the connection to AHK? Are there special problems with remapping this which should be mentioned, like with Alt-Tab?
Please elaborate!
Re: Suggestions on documentation improvements
gregster, there are no problems. Everything is working fine.gregster wrote: ↑08 Feb 2019, 15:09And what is AutoReload? Never heard of it.. so does my AHK version, it seems. (I am guessing the syntax here.)
And Shift+tab is a standard MS Windows shortcut - what is the connection to AHK? Are there special problems with remapping this which should be mentioned, like with Alt-Tab?
Please elaborate!
ahk7 provided the code snipped of Reload as shown below. I wanted to read up about it.
Code: Select all
#SingleInstance force
#NoEnv
#Warn
#InstallKeybdHook
SetWorkingDir, D:\ahk-functions-library
SetTimer, AutoReload, 100000
#Include D:\ahk-functions-library\en-proof.ahk
~LWin::vk07
Win 10 Professional 64bit 21H2 16Gb Ram AHK current as of 2021-12-26 .
Re: Suggestions on documentation improvements
Okay, I am just trying to understand what's going on with this AutoReload thing you mentioned, but this is clearly a user-defined function like we have uncounted numbers of in this forum.
While we have examples in the docs and in rare cases hints to useful user-defined functions outside of the docs, it is impossible to say if this would make sense to include without actually knowing the source code which is obviously #included here via another ahk-file that we don't see (this means, this snippet itself cannot be run without additional code that we don't know so far). For all we know, this could be simply a timer to a function or label with a Reload command in it.
Edit: Looking at this thread, my impression is that en-proof.ahk is your own library file and that you came up yourself with this AutoReload-Timer - and not ahk7.

Re: Suggestions on documentation improvements
ahk7 suggested using AutoReload in this thread https://www.autohotkey.com/boards/viewtopic.php?f=76&t=60167. The purpose of the AutoReload was to refresh the code because after about an hour the keyboard goes bananas in Firefox (and only in Firefox). So, I wanted to find and pinpoint the problem before contacting Firefox support. So, Windows may not be a problem but interference from Firefox shortcuts may be. AutoReload is an accepted action in AutoHotkey.
Win 10 Professional 64bit 21H2 16Gb Ram AHK current as of 2021-12-26 .
Re: Suggestions on documentation improvements
ineuw wrote: ↑08 Feb 2019, 22:40ahk7 suggested using AutoReload in this thread https://www.autohotkey.com/boards/viewtopic.php?f=76&t=60167. The purpose of the AutoReload was to refresh the code because after about an hour the keyboard goes bananas in Firefox (and only in Firefox). So, I wanted to find and pinpoint the problem before contacting Firefox support. So, Windows may not be a problem but interference from Firefox shortcuts may be. AutoReload is an accepted action in AutoHotkey.
No, really, if you look at the code box in the first post (your post) of the thread, it is you that came up with it, as a label for SetTimer - ahk7 just slightly re-arranged your original code (I guess, it is possible that you got it yourself from a third party).
And no, AutoReload is really not a generally "accepted action in Autohotkey" - it is just an arbitrary label, a user-defined name - and we cannot know what it is doing in this case because we don't see what's in its actual subroutine. The only person who could know, is you. This label name could well have been "dafnakqwem" instead. Perhaps you should read the linked thread again - and about the use of labels, in general.
I suggest we continue this discussion in the Ask for Help forum, if this remains unclear.
(It is not my intention to annoy you, but I really have the impression that you got some general misconceptions about the use and syntax of AutoHotkey.)
Re: Suggestions on documentation improvements
gregster, you are absolutely right. Please accept my apologies about arguing, and my thanks for the time you invested in replying it to me.
Reload is a label for the loop, reloading the scripts at 10 second intervals. I found it as the last entry, and it was created awhile ago, possibly with instructions from ahk7. I will disable it for now because the reason why it was added is no longer valid. Thanks again .
Reload is a label for the loop, reloading the scripts at 10 second intervals. I found it as the last entry, and it was created awhile ago, possibly with instructions from ahk7. I will disable it for now because the reason why it was added is no longer valid. Thanks again .
Code: Select all
AutoReload:
Reload
Return
Win 10 Professional 64bit 21H2 16Gb Ram AHK current as of 2021-12-26 .
Re: Suggestions on documentation improvements
4 issues.
GUICONTROLGET
- GuiControlGet: '(Blank)' subcommand. This can support the 'Text' (Static) control, but 'Text' is not listed.
- (I'm not sure of what the exact behaviour is, for GuiControlGet applied to a 'Text' control, because it isn't listed.)
[EDIT:]
- I would remove 'All control types are self-explanatory except the following:'.
- And state these explicitly as a group: Text/Button/Link/DateTime/MonthCal/GroupBox/Custom.
- Separating any where necessary e.g. Custom.
- (It's confusing, your eyes keep looking up and down for a control type that may or may not be there.)
IF OBJECT
- if: 'if var', where var is an object, always returns true. The 'if (expression)' page does not state this.
- Mentioned here:
Raw TRUE/FALSE test on an object - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=60963
- [EDIT:] A link could be added to this page (or the information copied):
Objects - Definition & Usage | AutoHotkey
https://autohotkey.com/docs/Objects.htm#Usage_Remarks
TERNARY OPERATOR
- Ternary operator: it could be stated explicitly that you must specify all 3 parts: '(a) ? (b) : (c)', i.e. '(a) ? (b)' does not work.
- This trips a lot of people up because the 4-liner 'if (a) LF (b) LF else LF (c)' is possible, however, the 2-liner 'if (a) LF (b)' is also possible.
Variables and Expressions - Definition & Usage | AutoHotkey
https://autohotkey.com/docs/Variables.htm#ternary
- It could simply be mentioned that 'ternary' means 3, so 3 arguments are required. Furthermore, if the terms unary/binary/ternary operator were mentioned/explained together, this might add more clarity. [EDIT:] E.g.:
Oracle Unary and Binary Operators - w3resource
https://www.w3resource.com/oracle/operators/index.php
DLLCALL AND POINTERS
- DllCall: clarification of what happens when you specify 'Ptr,0' and 'PtrP,0'/'IntP,0'/'UIntP,0' etc.
- Mentioned here:
DllCall: IntP/UIntP, Int64P/UInt64P, PtrP/UPtrP - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=39906&p=261091#p261091
- [EDIT:] 'Ptr,0', is the memory at address 0 write-protected, or is a crash possible?
- [EDIT:] 'PtrP,0', does this write to the variable called '0', does it write to and then discard a temporary variable? What happens?
GUICONTROLGET
- GuiControlGet: '(Blank)' subcommand. This can support the 'Text' (Static) control, but 'Text' is not listed.
- (I'm not sure of what the exact behaviour is, for GuiControlGet applied to a 'Text' control, because it isn't listed.)
[EDIT:]
- I would remove 'All control types are self-explanatory except the following:'.
- And state these explicitly as a group: Text/Button/Link/DateTime/MonthCal/GroupBox/Custom.
- Separating any where necessary e.g. Custom.
- (It's confusing, your eyes keep looking up and down for a control type that may or may not be there.)
IF OBJECT
- if: 'if var', where var is an object, always returns true. The 'if (expression)' page does not state this.
- Mentioned here:
Raw TRUE/FALSE test on an object - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=60963
- [EDIT:] A link could be added to this page (or the information copied):
Objects - Definition & Usage | AutoHotkey
https://autohotkey.com/docs/Objects.htm#Usage_Remarks
TERNARY OPERATOR
- Ternary operator: it could be stated explicitly that you must specify all 3 parts: '(a) ? (b) : (c)', i.e. '(a) ? (b)' does not work.
- This trips a lot of people up because the 4-liner 'if (a) LF (b) LF else LF (c)' is possible, however, the 2-liner 'if (a) LF (b)' is also possible.
Variables and Expressions - Definition & Usage | AutoHotkey
https://autohotkey.com/docs/Variables.htm#ternary
- It could simply be mentioned that 'ternary' means 3, so 3 arguments are required. Furthermore, if the terms unary/binary/ternary operator were mentioned/explained together, this might add more clarity. [EDIT:] E.g.:
Oracle Unary and Binary Operators - w3resource
https://www.w3resource.com/oracle/operators/index.php
DLLCALL AND POINTERS
- DllCall: clarification of what happens when you specify 'Ptr,0' and 'PtrP,0'/'IntP,0'/'UIntP,0' etc.
- Mentioned here:
DllCall: IntP/UIntP, Int64P/UInt64P, PtrP/UPtrP - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=39906&p=261091#p261091
- [EDIT:] 'Ptr,0', is the memory at address 0 write-protected, or is a crash possible?
- [EDIT:] 'PtrP,0', does this write to the variable called '0', does it write to and then discard a temporary variable? What happens?
Last edited by jeeswg on 27 Feb 2019, 11:48, edited 4 times in total.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
Re: Suggestions on documentation improvements
I guess it retrieve the control's content.Leave SubCommand blank to retrieve the control's contents. All control types are self-explanatory except the following:
- if: 'if var', where var is an object, always returns true. The 'if (expression)' page does not state this.
- Mentioned here:
Raw TRUE/FALSE test on an object - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=60963
If the if-statement's expression evaluates to true (which is any result other than an empty string or the number 0),
all operators require all operands and symbols.- Ternary operator: it could be stated explicitly that you must specify all 3 ...
it is clearly documented that the address of the argument is passed, I cannot see how it can be clarified.- DllCall: clarification of what happens when you specify 'Ptr,0' and 'PtrP,0'/'IntP,0'/'UIntP,0' etc.
- Mentioned here:
DllCall: IntP/UIntP, Int64P/UInt64P, PtrP/UPtrP - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=39906&p=261091#p261091
Re: Suggestions on documentation improvements
@Helgef: Thanks for your comments. But everything I said still stands, and I've expanded points in the spoiler.
Spoiler
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
what does the "=" operator do?
at https://autohotkey.com/docs/Variables.htm#Operators is shown the "=" operator.
What the = operator does IS NOT DEFINED. I think one of the MOST CONFUSING things about AHK is the difference between = and :=. I've been plagued with the issue for years.
It states the following:
What the = operator does IS NOT DEFINED. I think one of the MOST CONFUSING things about AHK is the difference between = and :=. I've been plagued with the issue for years.
It states the following:
Equal (=), case-sensitive-equal (==), and not-equal (<> or !=). The operators != and <> are identical in function. The == operator behaves identically to = except when either of the inputs is not a number, in which case == is always case sensitive and = is always case insensitive (the method of insensitivity depends on StringCaseSense). By contrast, <> and != obey StringCaseSense.
Note: A quoted literal string such as "55" is always considered non-numeric in this context.
Deprecated: The <> operator is not recommended for use in new scripts. Use the != operator instead.
Re: Suggestions on documentation improvements
@ joefiesta, you link to operators in expressions, the legacy assignment = isn't listed there because it cannot be be used in an expression. Legacy assignment is mentioned on the same page though, just a bit up. It has its own page here . A link to this page might be appropriate in connection to the other assignment operators, eg :=.
IF and expressions
At the doc for "If (expression)" is stated
However, the doc at "variables and expressions" includes this:
Is "If ItemCount" an expression? I can't figure that out because the doc seemingly contradicts itself. According to the first quote, it is NOT an expression because "ItemCount" is not preceded by a left parenthesis.
Sounds pretty straightforward. What follows "if " is not considered an expression unless preceded by a "(".An if-statement that contains an expression is differentiated from a traditional-if such as If FoundColor <> Blue by making the character after the word "if" an open-parenthesis.
However, the doc at "variables and expressions" includes this:
Here, the implication from "When an expression is required" is that in the example thereafter, "if ItemCount", ItemCount is an expression.Boolean values: When an expression is required to evaluate to true or false (such as an IF-statement), a blank or zero result is considered false and all other results are considered true. For example, the statement if ItemCount would be false only if ItemCount is blank or 0. Similarly, the expression if not ItemCount would yield the opposite result.
Is "If ItemCount" an expression? I can't figure that out because the doc seemingly contradicts itself. According to the first quote, it is NOT an expression because "ItemCount" is not preceded by a left parenthesis.
Re: Suggestions on documentation improvements
Well, the first parameter of If is always seen as a variable name - specifically without the use of %s. Hence, the first parameter must be an expression, otherwise we could not use the contents of this variable.
(For the second parameter of a comparison, it is a whole different story.)
Traditional If tells us about the first parameter:
I think if you start to talk about expressions in the traditional If docs, it would confuse people even more. In case of the use of operators, the traditional comparison is simply not an expression. But If ItemCount has no second parameter. That's why there are no problems with the question if expression or not - because the first parameter is clearly a variable name, like always with If, no matter what style. Also, parentheses don't hurt, they don't make a difference here: if (itemcount) is the same as if itemcount - simply because there is no comparison and no second parameter... and it is already an expression.
(For the second parameter of a comparison, it is a whole different story.)
Traditional If tells us about the first parameter:
Edit:Var
The variable name.
I think if you start to talk about expressions in the traditional If docs, it would confuse people even more. In case of the use of operators, the traditional comparison is simply not an expression. But If ItemCount has no second parameter. That's why there are no problems with the question if expression or not - because the first parameter is clearly a variable name, like always with If, no matter what style. Also, parentheses don't hurt, they don't make a difference here: if (itemcount) is the same as if itemcount - simply because there is no comparison and no second parameter... and it is already an expression.
Re: Suggestions on documentation improvements
Something was unclear, that means you should ask for help, so when it is not unclear anymore, you can make an actual suggestion. In general, this thread is mostly ask for help and no suggestions. If you ask a question, it is the wrong thread.- GuiControlGet: It may be more subtle than that, I was exploring backporting AHK v2 GUIs, and something important was unclear.
Would you expect obj == "" to be true?- I had thought that since an object returns an empty string,
re. ?:. The problem is that there isn't a load time error, people omit : because they have seen others doing it, guessing it is valid, and they didn't read the docs. So changing the docs doesn't help.
Cheers.
Re: Suggestions on documentation improvements
- The point about GuiControlGet + (Blank) + Text controls was to double-check its behaviour before updating the documentation. I can't remember if its behaviour was simple or complex. E.g. Submit/AltSubmit, and AHK v2 distinguishes between Text and Value.
- Many(/most?) people would expect obj == "" to be true, yes. I tested and it reported false, which arguably breaks the principle of least astonishment. I can think of arguments for both sides, I'd recommend starting a new thread if you want to pursue it further.
- (You do surprise me sometimes with what you think is 'normal', or what you think other people will expect as 'normal' e.g. force-local and 'can be expression' v. 'force an expression'. You're quite the lateral thinker. In fact, the fact that you asked the question implies that you anticipated some room for doubt in others.)
- Btw what about if {}? What's your expectation for that?
- And obj obj == "" gives true, while obj == "" gives false. There are parallels with IsObject(obj) and IsObject(obj obj),
- Btw in AHK Basic you did not have if obj or obj == "", so this behaviour needs to be defined somewhere, prominently, in the documentation.
- Yes, I think there should be a load-time error re. ternary operators in AHK v1. Changing the docs would help people who (a) read the docs, (b) are linked to the docs. I've added it to my Wish List 2.0. Cheers.
- Many(/most?) people would expect obj == "" to be true, yes. I tested and it reported false, which arguably breaks the principle of least astonishment. I can think of arguments for both sides, I'd recommend starting a new thread if you want to pursue it further.
- (You do surprise me sometimes with what you think is 'normal', or what you think other people will expect as 'normal' e.g. force-local and 'can be expression' v. 'force an expression'. You're quite the lateral thinker. In fact, the fact that you asked the question implies that you anticipated some room for doubt in others.)
- Btw what about if {}? What's your expectation for that?
- And obj obj == "" gives true, while obj == "" gives false. There are parallels with IsObject(obj) and IsObject(obj obj),
- Btw in AHK Basic you did not have if obj or obj == "", so this behaviour needs to be defined somewhere, prominently, in the documentation.
- Yes, I think there should be a load-time error re. ternary operators in AHK v1. Changing the docs would help people who (a) read the docs, (b) are linked to the docs. I've added it to my Wish List 2.0. Cheers.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
Re: Suggestions on documentation improvements
I made a ridiculous example to help you realise that your comment,Many(/most?) people would expect obj == "" to be true, yes.
was nonsensical . I will try again, do you expect obj.key to be equivalent to "".key? And no, I do not think anyone would expect obj == "" to be true.- I had thought that since an object returns an empty string,
It does, and It isthis behaviour needs to be defined somewhere, prominently, in the documentation.

Cheers.
Return to “Suggestions on Documentation Improvements”
Who is online
Users browsing this forum: No registered users and 4 guests