Jump to content

Sky Slate Blueberry Blackcurrant Watermelon Strawberry Orange Banana Apple Emerald Chocolate
Photo

Suggestions on documentation improvements


  • Please log in to reply
244 replies to this topic
JDN
  • Members
  • 313 posts
  • Last active: Sep 03 2016 06:51 AM
  • Joined: 24 Mar 2004
I have found some minor typos in the Help file. I try to wait a few weeks and find several typos before posting. I think it would be a nuisance to post every time I find one. Here are five of them:

In the following list, I use the abbreviations "s.b." to mean "should be". I hope you can find all the following OK and that you can follow my meaning as to what is the problem and what is the solution.

------------------------------------------------------------------------------------

Functions - Builtin Functions - Substr - "Length is the maximum number of characters to retrieve (fewer than the maximum are retrieved whenever the remaining part of the string too short)." ... s.b. "of the string is too short)."

Variables and Expressions - Variable Types (very near top of section) - However, a variable containing only digits (with an optional decimal point) is automatically interpreted a number when a math operation or comparison requires it. ... s.b. "interpreted as a number"

also - (with an optional decimal point) ... sb ... (with an optional decimal point and/or minus sign) ? (I'm not sure if this is correct or not)

RegExMatch - Parameters - NeedleRegEx - followed by an close-parenthesis - s.b. "followed by a close parenthesis"

alphabetic list of commands - #winactivate force - "of of" s.b. "of".

JDN
  • Members
  • 313 posts
  • Last active: Sep 03 2016 06:51 AM
  • Joined: 24 Mar 2004
The command SetTimer is listed under "Flow of Control" as well as "Misc Commands" under the Contents tab of the Help file.

I don't know if this might be an error or not. But I don't see any other commands listed in more than one category.

lilalurl.T32
  • Members
  • 391 posts
  • Last active: Jul 05 2011 03:39 PM
  • Joined: 17 May 2007
Missing i in classified, in the last sentence of the first paragraph of the entry for A-Cursor.

The hand-shaped cursors (pointing and grabbing) are classified as Unknown.

________
DC MARIJUANA DISPENSARIES

a_h_k
  • Members
  • 685 posts
  • Last active: Sep 28 2015 12:32 AM
  • Joined: 02 Feb 2008
Exit

Is:
"Exits the current thread or (if the script is not persistent contains no hotkeys) the entire script."

Should be:
"Exits the current thread or (if the script is not persistent & contains no hotkeys) the entire script"



Also: Why not rid the trailing "." at end of lines/paragraphs? (at least for these description lines) --> It would look a bit better (i tend to avoid using "." whenever possible, leaving it to the realm of books/newspapers/etc !)
Anyway, you know that you have reached the end of the line/paragragh by way of the "EoL marker" (= <nothing>), so having the "." there as well is unecessary duplication of the EoL marker (like having CR/LF + TAB to mark end of file lines!) :)

By "lines/paragraphs" I meant omitting [color=red].[/color] at end of single sentences, & at end paragraphs (last sentence):
[color=olive]A single sentence[/color]
             (no [color=red].[/color])
[color=olive]A single sentence[/color][color=red].[/color] [color=olive]Another single sentence[/color][color=red].[/color] [color=olive]Yet another single sentence[/color]
                ([color=red].[/color])                      ([color=red].[/color])                       (no [color=red].[/color])


a_h_k
  • Members
  • 685 posts
  • Last active: Sep 28 2015 12:32 AM
  • Joined: 02 Feb 2008
Critical

Is:
Critical [, Off]
Critical 50 ; See bottom of remarks.

Should be:
Critical [, On|Off]
Critical MessageCheckInterval ; See bottom of remarks

SoLong&Thx4AllTheFish
  • Members
  • 4999 posts
  • Last active:
  • Joined: 27 May 2007
Perhaps add a short note about different keyboard layouts on these two pages:

<!-- m -->http://www.autohotke...ocs/Hotkeys.htm<!-- m -->
<!-- m -->http://www.autohotke...cs/Tutorial.htm<!-- m -->

As some users may expect a simple #z to work while it generates an "Error: invalid hotkey" which may confuse a new scripter

See <!-- m -->http://www.autohotke...pic.php?t=46711<!-- m -->

Edit: updated link

Lexikos
  • Administrators
  • 9844 posts
  • AutoHotkey Foundation
  • Last active:
  • Joined: 17 Oct 2006

If this is the letter A and the next 3 parameters are omitted, the active window will be used.

The above seems to apply to any command which accepts a window title, but the documention fails to mention it for several commands.

WinGet - Why?

WinActivate and WinActivateBottom - OK, there probably isn't any conceivable use for activating the active window.

WinShow, WinWait, IfWin and variations - If DetectHiddenWindows is Off, WinWaitClose or WinWaitNotActive can be used to wait for a hidden window to become active, while WinWait or WinWaitActive can be used to wait for a visible window to become active. Similarly, IfWin can be used to determine whether the active window is visible. One common example of a hidden active window: whenever a popup menu is shown, the window which owns it is activated. AutoHotkey's menus and all other tray icon menus I've tested are owned by hidden windows.

More importantly, WinActive() and WinExist() are often used to retrieve the ID of the active window. However, their sections in the documentation link to IfWinActive and IfWinExist, which do not mention "A". The following thread prompted my post: WinGetActiveID?.

Crash&Burn
  • Members
  • 228 posts
  • Last active: Jul 16 2014 10:10 PM
  • Joined: 02 Aug 2009
Can Rajat's updated messages.txt be added to the AutoHotkey.CHM?

Lexikos
  • Administrators
  • 9844 posts
  • AutoHotkey Foundation
  • Last active:
  • Joined: 17 Oct 2006

Variable names may be up to 254 characters long

Is this really correct? MAX_VAR_NAME_LENGTH is defined as (UCHAR_MAX - 2), i.e. 253.

infogulch
  • Moderators
  • 717 posts
  • Last active: Jul 31 2014 08:27 PM
  • Joined: 27 Mar 2008
The default values for SetKeyDelay are listed near the bottom of it's documentation. I think most people would expect this information to be listed in the parameter descriptions, especially since this command's defaults affect other commands.

infogulch
  • Moderators
  • 717 posts
  • Last active: Jul 31 2014 08:27 PM
  • Joined: 27 Mar 2008
Lexikos: you are correct, running the following test script, one sees that it fails at 254 characters, so the max is actually 253 characters:
loop
{
	ToolTip, Trying length: %A_Index%
	nam .= "a"
	%nam% := "Testing " A_Index
}


Lexikos
  • Administrators
  • 9844 posts
  • AutoHotkey Foundation
  • Last active:
  • Joined: 17 Oct 2006

When the Gui Submit command is used, the control's associated output variable (if any) receives the hotkey modifiers and name, which are be compatible with the Hotkey command.
Source: GUI Control Types



engunneer
  • Moderators
  • 9162 posts
  • Last active: Sep 12 2014 10:36 PM
  • Joined: 30 Aug 2005

U: (snip) If the either Random or Foptions are in effect, duplicates are removed only if they appear adjacent to each other as a result of the sort. For example, when "A|B|A" is sorted randomly, the result could contain either one or two A's.


Topic

Chris
  • Administrators
  • 10727 posts
  • Last active:
  • Joined: 02 Mar 2004
Thanks for all the corrections and suggestions. I have made almost all these changes, though a few I didn't apply because the current method seems slightly better.

WinActive() and WinExist() are often used to retrieve the ID of the active window. However, their sections in the documentation link to IfWinActive and IfWinExist, which do not mention "A". The following thread prompted my post: WinGetActiveID?.

I've added the missing text to IfWinExist, and also mentioned WinExist("A") in the WinActive() section. Thanks.

WinShow, WinWait, IfWin and variations - If DetectHiddenWindows is Off, WinWaitClose or WinWaitNotActive can be used to wait for a hidden window to become active, while WinWait or WinWaitActive can be used to wait for a visible window to become active. Similarly, IfWin can be used to determine whether the active window is visible. One common example of a hidden active window: whenever a popup menu is shown, the window which owns it is activated. AutoHotkey's menus and all other tray icon menus I've tested are owned by hidden windows.

I can see that mentioning WinTitle "A" in those sections would improve completeness and accuracy. However, since working with an active window that is hidden seems very rare, maybe mentioning "A" would be more distracting than it's worth. I'm not sure.

Can Rajat's updated messages.txt be added to the AutoHotkey.CHM?

Maybe it's best that the list omit really obscure messages that are unlikely to be used by any scripts, especially if there are dozens or hundreds of obscure messages currently missing. For the more common messages that are missing, if someone would like to update the current list, it is at <!-- w -->www.autohotkey.com/docs/misc/SendMessageList.htm<!-- w -->

Thanks again for all the corrections and improvements. More are welcome anytime.

jaco0646
  • Moderators
  • 3165 posts
  • Last active: Apr 01 2014 01:46 AM
  • Joined: 07 Oct 2006
The documentation for A_EndChar notes that it only applies to non-auto-replace hotstrings. For consistency, A_ThisHotkey should have the same note.

EDIT: ...unless it's an easy fix to make, but that's an item for the Wish List. :)