[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
2_05
Posts: 31
Joined: 09 May 2018, 10:28

Re: Suggestions on documentation improvements

19 Sep 2018, 00:30

I have struggled with WinWait to wait for WinText to change in a window, so the text in the window was "Text A' when the window came into existence, but later changes to "Text B". I verified this with Window Spy. My script only detected if a window with that WinText comes into existence during the wait, or existed before the wait. It did not detect an existing window not matching the criteria before running the command, that suddenly matches the criteria during the wait after the window has changed its WinText.

It is not clear from the topic on WinWait if windows that changes its title or text while the command is in waiting state are also detected. It may be derived indirectly from the sentence "If a matching window comes into existence", but this sentence alone is not conclusive. I think this deserves a separate remark. Also applies to WinWaitActive.
If an existing window changes its title and text while the command is in waiting state, the command [will/will not] detect the change.
Edit: Modified since I'm not sure if the problem is only with my application or it general behavior.
Last edited by 2_05 on 19 Sep 2018, 02:32, edited 3 times in total.
2_05
Posts: 31
Joined: 09 May 2018, 10:28

Re: Suggestions on documentation improvements

19 Sep 2018, 01:03

The documentation on #Include refers to an old topic on joining scripts.

I don't see how the referred topic solves the problem of not being able to merge two isolated scripts together. To me, isolated means not containing #includes to each other. From what I understand the Join script only merges #includes into a script that would work exactly the same when unjoined.

And since all links to the join script in the referred topic are dead, I suggest that the reference is removed.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

CSV

28 Sep 2018, 08:51

I find the AHK documentation for CSV, found at LOOP PARSE, to be lacking.

1. I don't consider a double quote a PRIMARY delimiter. That is, the delimiter that defines each subfield. One might call it a SECONDARY delimiter. That it is removed when used as a secondary delimiter is not entirely clear to me when I read the doc.

2. A DOUBLE QUOTE also serves as an ESCAPE character in CSV syntax. That those double quotes are also removed is also not entirely clear.

3. There is, at least accordingly to wikipedia, no industry standard as to how CSV handling is implemented/defined. That, I feel, makes all the better argument for AHK refining it's definition of CSV processing.

4. The example (not actually an example) at LOOP PARSE
"first field",SecondField,"the word ""special"" is quoted literally",,"last field, has literal comma"
tries to clarify this. I feel it does only a fair job of that at best.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

07 Oct 2018, 09:41

Perhaps the documentation could be clearer re. RegEx, re. . and newlines:
RegEx help needed - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 05#p242505

This page isn't showing. (I might be too early.)
https://lexikos.github.io/v2/docs/comma ... lassNN.htm

This page isn't on the main index. (I might be too early again.)
SysGetIPAddresses - Syntax & Usage | AutoHotkey v2
https://lexikos.github.io/v2/docs/comma ... resses.htm
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: 9553
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

07 Oct 2018, 19:29

Looks like I missed adding ControlGetClassNN.htm in commit 9d505530. I'll add it.

I replaced A_IPAddress with SysGetIPAddresses but probably didn't think to add it to commands/index.htm since A_IPAddress isn't a command.

As for other suggestions for improvements, I'll leave it to any volunteer.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

08 Oct 2018, 10:15

I have a script that opens the relevant link when a command/function is selected, I noticed that case matters. I don't know if a redirect is possible, no problem if not. Anyhow, it would be good to correct the case for this htm, thanks.
Before:
https://lexikos.github.io/v2/docs/comma ... ckMode.htm
After:
https://lexikos.github.io/v2/docs/comma ... ckMode.htm
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
pneumatic
Posts: 338
Joined: 05 Dec 2016, 01:51

Re: Suggestions on documentation improvements

09 Oct 2018, 06:00

https://autohotkey.com/docs/commands/Run.htm#RunAs wrote:If UAC is disabled, *RunAs will launch the process without elevating it.
I just thought this might benefit from mentioning that setting UAC to its lowest setting, i.e "never notify", doesn't actually (necessarily?) disable UAC and the process is still being elevated by RunAs on my Win7 and 10 systems.

Image

Because a lot of people actually do think that the lowest setting is equivalent to "turning UAC off", and even this Microsoft article explicitly says that "UAC is disabled" when the slider is set to never notify.

I believe it's only when logged in as a standard user and UAC is set to "never notify" or lower via group policy settings that it will silently fail to elevate, and then you are left with a program that is running but broken (imo the worst possible scenario!) or have to use /restart so you can pass a parameter to tell the next instance whether the previous one failed to get elevated.

There's more detail here, but honestly I don't understand most of it :lol:
User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

09 Oct 2018, 07:37

jeeswg wrote:I have a script that opens the relevant link when a command/function is selected, I noticed that case matters. I don't know if a redirect is possible, no problem if not. Anyhow, it would be good to correct the case for this htm, thanks.
Before:
https://lexikos.github.io/v2/docs/comma ... ckMode.htm
After:
https://lexikos.github.io/v2/docs/comma ... ckMode.htm
Note that you can do the following which leads to the same page (also works with the v1 docs):

https://lexikos.github.io/v2/docs/searc ... ckmode&m=2 (for searching via search tab)

or

https://lexikos.github.io/v2/docs/searc ... ckmode&m=1 or just https://lexikos.github.io/v2/docs/searc ... pslockmode (for searching via index tab, which is broken atm, but will be fixed)
lexikos
Posts: 9553
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

09 Oct 2018, 19:08

pneumatic wrote:I just thought this might benefit from mentioning that setting UAC to its lowest setting, i.e "never notify", doesn't actually (necessarily?) disable UAC and the process is still being elevated by RunAs on my Win7 and 10 systems.
On all of the Windows 7 systems that I have set to "never notify", it has fully disabled UAC (after a reboot). On Windows 8 and later it does not disable UAC.
pneumatic
Posts: 338
Joined: 05 Dec 2016, 01:51

Re: Suggestions on documentation improvements

10 Oct 2018, 09:34

lexikos wrote:On all of the Windows 7 systems that I have set to "never notify", it has fully disabled UAC (after a reboot). On Windows 8 and later it does not disable UAC.
So I went back and re-tested it, and here is the behaviour I observed on my systems with UAC set to "never notify".

Windows 7 SP1 x64
Logged in as administrator: script launches as administrator without prompt, RunAs* is redundant since A_IsAdmin=1 from the get go and Integrity is inherited anyway
Logged in as standard user: script launches as standard user, RunAs* fails to elevate. Danger of infinite loop as described in the documentation (I prefer to pass my own parameter "AsAdmin" to the RunAs* instance and if (1=AsAdmin and A_IsAdmin!=1) then tell user it failed to elevate and ExitApp)

Windows 10 v1607 x64
Administrator: same was windows 7
Standard user: script launches as standard user, RunAs* prompts for admin credentials
pneumatic
Posts: 338
Joined: 05 Dec 2016, 01:51

Re: Suggestions on documentation improvements

10 Oct 2018, 22:25

May I suggest including in the documentation the mpress command line parameters used by ahk2exe, as for example I needed to edit the manifest of MyCompiledScript.exe which needs to be done before mpress, therefore I must use mpress manually and needed to know how to create the same resulting exe file. Also just to be confirm - compressing doesn't modify or corrupt the manifest does it?
edit: from compiler.ahk, the mpress.exe command line options are -q -x
pneumatic
Posts: 338
Joined: 05 Dec 2016, 01:51

Re: Suggestions on documentation improvements

11 Oct 2018, 23:52

https://autohotkey.com/docs/commands/RegWrite.htm wrote:If ValueType is REG_DWORD, Value should be between -2147483648 and 4294967295 (0xFFFFFFFF).
REG_DWORD cannot be negative. This caused my script to go into an infinite reboot loop and inability to even shut it down from task manager! Basically I was trying to write -1 and since the value never applies my script tries to set it again and then restart for the key to take effect, ad infinitum. To be safe I will have to pass a "WroteToRegistry" parameter to the next instance of MyScript.exe so it only tries to write registry values once :lolno:
User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

12 Oct 2018, 04:53

This number range does not apply to REG_DWORD itself, but to the Value parameter of RegWrite.

When using RegWrite in conjunction with REG_DWORD, a negative number is automatically converted into a positive number (unsigned 32-bit integer). To get a negative number with RegRead, convert its return value into a number type which can be positive or negative (signed 32-bit integer) by using OutputVar := OutputVar << 32 >> 32.

Alternatively, consider using REG_SZ to avoid this issue.

Besides, RegRead says:
REG_DWORD values are always expressed as positive decimal numbers.
pneumatic
Posts: 338
Joined: 05 Dec 2016, 01:51

Re: Suggestions on documentation improvements

12 Oct 2018, 23:22

But then negative numbers will have the same value as positive numbers, eg. -1 = 4294967295 , -2 = 4294967294, -3 = 4294967293 etc. This assumes the user doesn't want to keep their positive and negative numbers distinct from each other, which seems like a bad presupposition to make. Therefore I still think it's unwise to suggest REG_DWORD should take negative values. Even regardless of this, I still think it's unwise to advertise REG_DWORD as holding negative values just because we can use a custom scheme of encoding negative numbers into a positive number. i.e REG_DWORD appears to still be designed to hold a positive number as that's how the value is decoded in the registry editor.

Edit: or is the registry editor's decoding arbitrary? This Microsoft article just says it's a "32 bit number", nothing more, which leaves open the possibility of using it to hold negative numbers, or even floating point numbers. I guess the question is, what is reasonable to assume? Is it reasonable to assume that the user knows that when they RegWrite -1 that RegRead is going to return 4294967295? Maybe a lot of people do know this, but maybe also many do not.
User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

13 Oct 2018, 02:45

It's by design. Don't worry, I'll add some notes about this issue to reduce the confusion of the user.
burque505
Posts: 1731
Joined: 22 Jan 2017, 19:37

Re: Suggestions on documentation improvements

26 Oct 2018, 13:21

Dead link report on "Script Showcase" SKAN's Tips N Tricks (the page itself is there, but the links are dead). SKAN, would you happen to have the referenced scripts archived anywhere? For example: maybe they are in one of the archives, but so far I haven't found "How to Hook on to Shell to receive its messages" or "How to receive a script's PID". I know there are other posts on these topics, but I always find your code interesting and helpful.
Regards,
burque505
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Version 2 - MSGBOX

08 Nov 2018, 12:02

1. is there a new "documentation suggestions" for V2?

2. V2 MSGBOX doc says:
Known limitation: If the MsgBox contains only an OK button, the return value will indicate that the OK button was pressed if the MsgBox times out while its own thread is interrupted by another.
this sentence (particularly the word "while") makes no sense to me.
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

08 Nov 2018, 12:33

Code: Select all

q::
	retval := MsgBox("", "", "T2")
	MsgBox(retval)
Return

w::MsgBox("interrupt it")
press q, then press w within 2 seconds following the prior pressing of q. Wait 2 seconds, close the interrupt msgbox, the original msgbox now returns Ok instead of Timeout
idk, it seems to me its worded well enough already. maybe add "Ok instead of Timeout" in there somewhere without making it too verbose
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

08 Nov 2018, 16:58

@swagfag - thanks for the clarification. I now understand what the documentation is trying to tell me.

But, what I now don't understand is this: how can the Msgbox command timeout while it's thread is interrupted?
To me, it can't. Afterall, it's not doing anything while interrupted. To me it times out "after it's interrupted thread is resumed".

Yes, very, very minor. But, I didn't understand how it could happen the way described.
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

08 Nov 2018, 17:54

If the Timeout period elapses while another thread has interupted the thread, which created the Msgbox, it will time out after the thread is resumed and will return ok instead of timeout.
Recommends AHK Studio

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 8 guests