[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

17 Aug 2018, 16:44

EDITING PAGES
- @Ragnar: Good points, I think we need a prominent place where information about AutoHotkey and GitHub is contained. I had no idea of any of that, despite following this thread for a fair while.
- It might seem minor, but out of respect I wanted to let you choose which hyphen Unicode character, and whether to use spacing or not, html formatting etc. Furthermore, there may be style guide precedent based on other pages.

RELATED TOPICS
- Because it's easier to search for 'Related T' than wade through 'related' multiple times, I would suggest that all 'Related' section headers become 'Related Topics'.
- (For the record, these 2 pages use 'Related Topics', every other page uses 'Related' as the section header.)
Remapping Keys (Keyboard, Mouse and Joystick) | AutoHotkey
https://autohotkey.com/docs/misc/Remap.htm
Remapping a Joystick to Keyboard or Mouse | AutoHotkey
https://autohotkey.com/docs/misc/RemapJoystick.htm
- (Despite appearing only twice, I thought that 'Related Topics' was common, partly because other pages use the phrase 'related topic(s)' occasionally. So I kept trying to search for 'Related T' with no luck.)

- Many pages lack a 'Related Topics' section, including these two, which I think should link to each other. Cheers.
Basic Object - Methods & Properties | AutoHotkey
https://autohotkey.com/docs/objects/Object.htm
Objects - Definition & Usage | AutoHotkey
https://autohotkey.com/docs/Objects.htm

VERSION NUMBER MISSING
- [ObjRawSet][v1.1.21+]
Basic Object - Methods & Properties | AutoHotkey
https://autohotkey.com/docs/objects/Object.htm
- [ComObject/ComObjEnwrap/ComObjUnwrap/ComObjMissing/ComObjParameter][v1.0.90+?]
ComObjActive() - Syntax & Usage | AutoHotkey
https://autohotkey.com/docs/commands/ComObjActive.htm
- [Array][v1.0.97+?] and [Object][v1.0.90+?]
Basic Object - Methods & Properties | AutoHotkey
https://autohotkey.com/docs/objects/Object.htm
- [A_IsUnicode][v1.0.90+?]
Variables and Expressions - Definition & Usage | AutoHotkey
https://autohotkey.com/docs/Variables.htm

- I've created a list of AHK v1.1 new features, with the version number for each item.
list of every command/function/variable from across all versions - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 42#p131642

FUNCTION INDEX MISSING
- OnError.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
lexikos
Posts: 9554
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

18 Aug 2018, 21:39

[ComObject/ComObjEnwrap/ComObjUnwrap/ComObjMissing/ComObjParameter][v1.0.90+?]
It's in the heading at the top of the page. Everything on that page is v1.0.90+. Also, in case you missed the memo, all of those are names for the same function (ComObjActive).
- [A_IsUnicode][v1.0.90+?]
While technically the variable didn't always exist, I'm fairly certain it was added at the same time as Unicode support. The documented empty value for ANSI builds effectively applies to every version of AutoHotkey ever; e.g. the expression A_IsUnicode ? 2 : 1 returns 1 on every ANSI version of AutoHotkey since expressions were added to the language. So in other words, to say that the variable "requires" AHK_L revision 42 (or v1.0.90) or later is inaccurate and unnecessary.

However, v1.1.06 changed A_IsUnicode and A_IsCompiled to be defined, built-in and read-only regardless of which executable is in use, whereas on previous versions they were undefined (and not reserved words) when empty. I will clarify this myself.
- [Array][v1.0.97+?] and [Object][v1.0.90+?]
Basic Object - Methods & Properties | AutoHotkey
Support for objects was added in AHK_L revision 31 (or v1.0.90). Object() was available from this point. Array() was added in v1.0.97, along with the JSON-based syntax.

For the "usage" section, which is intended as a simple introduction of the syntax, noting the exact version where each part of the syntax became available would be an unnecessary distraction. The syntax has been around for over 7 years, and the documentation has gone through multiple rewrites since then. In my opinion, the only important distinction in this case is between versions that support objects and versions that don't (i.e. the original AutoHotkey, which supports older systems than v1.1).

Instead, I will add v1.1.21+ to the "simple arrays" and "associative arrays" section, since it is required for the method calls shown in those sections.
Guest

Re: Suggestions on documentation improvements

19 Aug 2018, 11:26

"This example is equivalent to the one above, except " does not make sense I think as there is no example above and if you click the "one above" you jump down on the page
https://autohotkey.com/docs/commands/On ... ionExample
User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

20 Aug 2018, 06:36

jeeswg wrote:It might seem minor, but out of respect I wanted to let you choose which hyphen Unicode character, and whether to use spacing or not, html formatting etc.
In this case it doesn't matter - the main thing is that it looks even.
jeeswg wrote:Because it's easier to search for 'Related T' than wade through 'related' multiple times, I would suggest that all 'Related' section headers become 'Related Topics'.
I am not a fan of this suggestion. Alternatively, in a non-mobile environment, you can press the End key to scroll down to the bottom of the page where the "Related" section is most often located.
Guest wrote:"This example is equivalent to the one above, except " does not make sense ...
Thanks for the info. This will be fixed.

As always, changes and fixes to the documentation can be found on GitHub, as well as new issues can be submitted in a clearer and better manageable way.
pneumatic
Posts: 338
Joined: 05 Dec 2016, 01:51

Re: Suggestions on documentation improvements

25 Aug 2018, 21:51

https://autohotkey.com/docs/Variables.htm wrote:a variable can be used to hold a false value simply by making it blank or assigning 0 to it
Let's test it...

Code: Select all

var := ""
if (var = false) 
  msgbox nope, this line won't occur because false is explicitly defined as a var containing 0
https://autohotkey.com/docs/Variables.htm wrote:The words true and false are built-in variables containing 1 and 0.
User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

26 Aug 2018, 02:35

Your test example is wrong. The second line should be if !var or if not var. See Concepts and Conventions: Boolean Values and Variables: Boolean Values.
pneumatic
Posts: 338
Joined: 05 Dec 2016, 01:51

Re: Suggestions on documentation improvements

26 Aug 2018, 05:34

The documentation says my var holds "a false value", so when comparing it to another false value (the word false) why shouldn't we expect the result to be true?
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

26 Aug 2018, 06:01

because the = operator does not compare whether the values both belong to the group true or the group false.
It compares if the values are exactly the same. And "" is not 0 though both are false. If you want to check if both are false or true:

Code: Select all

if (!(condition1) == !(condition2))
Recommends AHK Studio
pneumatic
Posts: 338
Joined: 05 Dec 2016, 01:51

Re: Suggestions on documentation improvements

26 Aug 2018, 07:49

nnnik wrote:It compares if the values are exactly the same. And "" is not 0.
In practice you are right; ahk is comparing "" and 0.

But the documentation implies that the comparison is not necessarily between "" and 0, because:

1. blank var "holds a false value".

2. the word false holds the value 0.

So the comparison could be between "a false value" and 0.

And according to doc, 0 is a false value, so expression could be true.
Helgef
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: Suggestions on documentation improvements

26 Aug 2018, 08:37

@ pneumatic, consider,
all other results are considered true
The words true and false are built-in variables containing 1 and 0
So do you also conclude that 37 == 1 should be true? I don't think so, for the same reasons which nnnik and Ragnar pointed out.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

26 Aug 2018, 09:24

There's a difference between:
- a variable has a value considered false (0 or a blank string)
if !var
or:
if (var = 0) || (var = "")
- a variable has a value equal to the variable False (0)
if (var = False)
or:
if (var = 0)
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
TomL
Posts: 16
Joined: 12 Jan 2016, 21:02

DetectHiddenWindows and the Process, Exist command

26 Aug 2018, 15:02

The "Process, Exist, .." command will return the PID of a process with no visible window if the "DetectHiddenWindows, On" command has been issued. This is not documented in the DetectHiddenWindows entry or the Process entry in the help file. In addition, the current DetectHiddenWindows help text implies that it only applies to "windowing commands".
If the DetectHiddenWindows setting is officially supported for the Process command then I suggest updating both help file entries to reference it.
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

26 Aug 2018, 15:06

1. blank var "holds a false value".
2. the word false holds the value 0.
3. An empty string or the number 0 are considered false.
4. A blank variable holds an empty string.
5. Using the comparison operator compares if values are the same - it is case insensitive when comparing strings.
-> When using the comparison operator on an empty variable and the variable false you will not get true as result.

This is indeed going around several corners - but if we were to mention every little detail like this we would run into problems.
Recommends AHK Studio
pneumatic
Posts: 338
Joined: 05 Dec 2016, 01:51

Re: Suggestions on documentation improvements

26 Aug 2018, 18:44

Helgef wrote: So do you also conclude that 37 == 1 should be true?
Obviously not :lol:

So 1 and 0/"" aren't pointers to some underlying representation or boolean data structure of truth and falsity - they are themselves literal representations of truth and falsity.

So comparisons between truth and falsity will only ever be between 1 and 0/"". Nothing more.

I suppose all instructions boil down to 1 and 0 at the hardware level, so there is no lower level way to represent truth and falsity anyway.

And if 0 and "" are both represented by a 0 at the hardware level, then more reason to allow both values for false.

The reason for my confusion was because I took the phrase "the var holds a false value" to mean the var points to some underlying boolean data structure of truth/falsity which can be compared with the = operator, when all that is ever being compared is 1 and 0/"".

If you believe others are likely to make the same mistake I did, may I suggest rephrasing
a variable can be used to hold a false value simply by making it blank or assigning 0 to it
as
a variable will evaluate to false simply by making it blank or assigning 0 to it
Because my brain thought "holds a false value" means that it points to some underlying boolean true/false data structure.

When really all it points to is 0/"".
lexikos
Posts: 9554
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

26 Aug 2018, 22:10

I think there's an obvious difference between "a false value" (implying that more than one value fits that criteria) and "the value (of) false".

By contrast, "evaluate to false" (if unclear that it is used within the context of boolean evaluation) does not have this implication. Depending on whether "false" is referring to the variable or boolean category, it could very well mean that "the value will be zero".
TomL wrote:The "Process, Exist, .." command will return the PID of a process with no visible window if the "DetectHiddenWindows, On" command has been issued.
Process operates on or returns the PID of a process regardless of whether it has visible windows, or any windows at all. DetectHiddenWindows has nothing to do with the Process command.
TomL
Posts: 16
Joined: 12 Jan 2016, 21:02

DetectHiddenWindows and the Process, Exist command

28 Aug 2018, 07:45

Thanks Lexikos for the quick reply. After some more debugging, it was a WinGet call further down in the script that needed the "DetectHiddenWindows, On".
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

15 Sep 2018, 17:48

- @Ragnar: Not that I'm too concerned, but FYI, on IE, it appears that scrolling doesn't work until you click the window.
- The new images look great.
- The work on the function parameter names has been great also, thanks very much.
- (I've had it with AHK itself also, I think that no-one noticed what I said and then suddenly it's implemented!)

- @lexikos: Thanks very much for the version number additions and the info.
- The changelog states ComObjType as new in v1.0.91 (Dec 2010) (and I accept that as the version number), but confusingly, it also mentions it at an earlier date, in Rev 53 (Aug 2010). Thanks.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
lexikos
Posts: 9554
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

15 Sep 2018, 18:45

v1.0.91 says "Added: ComObjType(co) and ComObjValue(co)." ComObjValue was new, but it seems only the single-parameter mode of ComObjType was added in v1.0.91. Before that it had only the "Name" and "IID" modes.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

18 Sep 2018, 06:30

- Thanks lexikos.
- Re. OR in AHK v2:
Variables and Expressions - Definition & Usage | AutoHotkey v2
https://lexikos.github.io/v2/docs/Variables.htm#or
Should it be:
In an expression where at least one operand resolves to True, the *FIRST* operand that resolved to True is returned.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 7 guests