[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

Re: Suggestions on documentation improvements

09 Nov 2018, 12:16

I fully understand the issue now. In that case, let me restate my propoisition:

I feel the doc at IFMsgBox which states:
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.
would be much clearer if it were worded something like:
Known limitation: If the MsgBox contains only an OK button, and it's thread is interrupted, and it times out during the interrupt, upon resumption of the thread the return value will indicate that the OK button was pressed.
lexikos
Posts: 9553
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

09 Nov 2018, 22:00

nnnik wrote:it will time out after the thread is resumed
Not so. In most cases, the MsgBox times out (the dialog is closed and the user can no longer read or interact with it) when the timeout period expires, regardless of whether the thread has been interrupted. If the timeout occurs before the thread is resumed, the return value will be "OK".

However, the timeout can be delayed by a long-running DllCall, file I/O calls, or anything else that prevents the program from pumping messages. Even if the timeout is delayed in this way, it might still occur before the thread is resumed.

Edit: The limitation will be removed in v1.1.30.01.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Dead link in doc

18 Nov 2018, 11:49

The documentation at "Gui Control types" at the description of the PICTURE control includes, in the "Animated Gif" paragraph a link to www.autohotkey.com/forum/topic19264.html, which redirects to:
https://autohotkey.com/board/topic/1772 ... -your-gui/.

At THAT site, there is a link labeled "Control_AniGif.ahk", which is: https://ahknet.autohotkey.com/~PhiLho/C ... AniGif.ahk

This is a DEAD LINK.

This is from offline doc 1.1.28.00. I see the current online doc does not have this problem. I haven't looked at 1.1.30.00 offline. (not there yet!)
ahk7
Posts: 574
Joined: 06 Nov 2013, 16:35

Re: Suggestions on documentation improvements

20 Nov 2018, 14:04

tmplinshi updated the code incl. dll here https://github.com/tmplinshi/AniGIF-AHK
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

20 Nov 2018, 14:24

does WinGet, ControlList[Hwnd] retrieve controls in order from topmost to bottommost, just like WinGet, List does for top level windows? and if so, shouldn't that be mentioned on the helppage too?

https://autohotkey.com/docs/commands/WinGet.htm

User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

20 Nov 2018, 19:11

guest3456 wrote:
20 Nov 2018, 14:24
does WinGet, ControlList[Hwnd] retrieve controls in order from topmost to bottommost, just like WinGet, List does for top level windows? and if so, shouldn't that be mentioned on the helppage too?
I'll add the following paragraph from v2's WinGetControls/WinGetControlsHwnd:
Controls are sorted according to their Z-order, which is usually the same order as the navigation order via Tab key if the window supports tabbing.
guest3456
Posts: 3454
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

20 Nov 2018, 23:14

i'm not sure if it does retrieve the controls in Z-order, that's part of what i was asking

User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

21 Nov 2018, 04:42

It usually does. Internally, both WinGetControls/Hwnd and WinGet ControlList/Hwnd use the same function to retrieve the controls (EnumChildWindows). The only difference is the return value (array vs string list).
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

30 Nov 2018, 12:00

I disagree. I find the grammar confusing. There is NO GRAMMATICAL reason why the second sentence of the paragraph also relates to "Using the {key:value} notation..." of the first sentence.

I feel it would be much clearer if worded as:
Using the {key:value} notation:
1. quote marks are optional for keys which consist only of word characters.
2. Any expression can be used as a key, but to use a variable as a key, it must be enclosed in parentheses
Quite frankly, I find this kind of somewhat imprecise English grammar occurs fairly often in the AHK doc. But, no wants to accept any help to improve it. So, all I can do is point it out when I find it.
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

30 Nov 2018, 12:02

You could improve it on GitHub.
Recommends AHK Studio
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

30 Nov 2018, 12:11

really? WOW. I'm thrilled. I've long wanted to help with AHK in some way. The documentation is very, very good. The problem is: it is an EXTREMELY complicated language. But, if you were ever IBM mainframe documentation, you would think any other documentation sucks. Back in my mainframe days, if I wrote to IBM a comma was missing, they would fix it.

@nnnik: thanks a zillion!
User avatar
ineuw
Posts: 172
Joined: 11 Sep 2014, 14:12

Re: Suggestions on documentation improvements

20 Dec 2018, 18:00

Please consider adding "Raw mode", "Text mode", and "Normal mode" to be included in the help index. It would really help.
Win 10 Professional 64bit 21H2 16Gb Ram AHK current as of 2021-12-26 .
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

What is a correct Guiname?

30 Dec 2018, 15:53

I received an error saying my gui name was invalid.

What is a valid gui name? I can not find this documented anywhere.

(It would also be nice, since searching works horribly for strings with embedded blanks, if the doc used "guiname" everywhere it mentions "gui name".)
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

31 Dec 2018, 12:10

@Helgef: thank you for the response. I was running 1.1.28.00 and had no idea the doc for 1.1.30 is SO GREATLY IMPROVED!! nice! I am particularly happy to see each GUI subcommand having it's own SYNTAX BOX. (Using examples as was done in the past was soooooo nasty.) I would like to add my comments, however, to help in the ever ongoing process to make AHK better. I believe:

1. Each GUI command syntax box should include GUINAME. In addition--I haven't looked--each GUICONTROL that allows GUINAME should do so. For example, I believe the syntax for the (main) GUI command should be:

Gui, [Guiname:] SubCommand [, Value1, Value2, Value3]

2. I believe GUINAME should have it's own documentation subsection and that this subsection should precedie the SUBCOMMANDs subsection.

Again, my compliments for the great doc improvements in 1.1.30.
TAC109
Posts: 1098
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Re: Suggestions on documentation improvements

08 Jan 2019, 23:26

Ragnar wrote:
05 Apr 2018, 09:21
If anyone wants the offline help with the old sidebar back, here's what you can do:
  1. Download and install Microsoft's HTML Help Workshop, if not already done (default location is C:\Program Files (x86)\HTML Help Workshop\)
  2. Download the current help files at GitHub and extract the zip file
  3. Search for compile_chm.ahk, open it in an editor and uncomment the lines after "use old sidebar" (currently line 31)
  4. Run compile_chm.ahk
  5. Search for the created AutoHotkey.chm in the same location as compile_chm.ahk
  6. Run AutoHotkey.chm (don't forget to check "Navigation Tabs" in the view menu, if it was previously unchecked)
@Ragnar - do you have the equivalent instructions for v2? (The location of the .zip in point 2 and any changed instructions.)
Thanks
My scripts:-
XRef - Produces Cross Reference lists for scripts
ReClip - A Text Reformatting and Clip Management utility
ScriptGuard - Protects Compiled Scripts from Decompilation
I also maintain Ahk2Exe
User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

09 Jan 2019, 05:02

The location for the v2 docs is https://github.com/Lexikos/AutoHotkey_L ... ive/v2.zip

Everything else remains the same. Note that you still need AHK v1 to run compile_chm.ahk.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

GUI +toolwindow

09 Jan 2019, 12:19

Gui +toolwindow command will mean the gui window will have no minimize button and no maximize button.

I can not find this documented at GUI where +Toolwindow is defined.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

09 Jan 2019, 15:06

@Ragnar: That is where I looked. The OPTIONS section is 6 pages, so I did not read it all. I was only concerned with what +TOOLWINDOW does. At +TOOLWINDOW, all that is found is:
ToolWindow: Provides a narrower title bar but the window will have no taskbar button.
As an aside, I just also notice the following inconsistencies/problem. That OPTIONS section also includes the following:
MaximizeBox: Enables the maximize button in the title bar. This is also included as part of Resize below.

MinimizeBox (present by default): Enables the minimize button in the title bar.
1. The maximize box is also present by default. The "present by default" needs to be included everywhere it is relevant.

2. since the lack of the Maximize and Minimize boxes is an aspect of +TOOLWINDOW, +TOOLWINDOW needs to point that out.

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 5 guests