[Archived, Locked] Suggestions on documentation improvements

[tidbit]

In the tutorial, "code blocks" https://autohotkey.com/docs/Tutorial.htm#s51 , should the line:
In the following code, the msgbox is only shown if var equals 5. The code will always exit, even if var isn't 5.
be:
In the following code, the msgbox is only shown if var equals 5. The code will always exit, even if var is or isn't 5.
or In the following code, the msgbox is only shown if var equals 5. The code will always exit, no matter what.
(or something along those lines. makes it more clear it doesn't belong to the if, no matter what it's checking)

[lexikos]

The original text is correct, as is "no matter what". It doesn't make sense to specify both conditions after using the phrase "even if".

If you want it to be clear that ExitApp doesn't belong to the If, then say it. e.g. "The code will always exit, because only the MsgBox belongs to the If" or "because lines are grouped by braces, not by indentation", or something to that effect.

[jNizM]

Add unicode example (0x411)
https://autohotkey.com/docs/misc/Styles.htm#StatusBar

Code: Select all

Gui +LastFound
SendMessage, 0x410, 0, "Text to display", msctls_statusbar321

Code: Select all

#define SB_SETTIPTEXTA          (WM_USER+16)
#define SB_SETTIPTEXTW          (WM_USER+17)

Ref:
https://autohotkey.com/boards/viewtopic.php?f=5&t=28706

[guest3456]

Add unicode example (0x411)

you're on github... why not submit a pull request yourself?

[tjdickinson]

Please forgive me for not reading through all 224 posts in this thread, but I just wanted to add a comment about the documentation. I apologize if someone has already mentioned it, but then again, another voice to the opinion never hurts.

I will preface this mentioning that my programming/coding/scripting knowledge is very, VERY cursory. I started playing around with AHK for one reason and one reason only: to create and modify hotkeys or keyboard shortcuts in some programs and/or for Windows. I realize that the functionality of AHK goes way beyond that, which is great. But for me, and I'm sure for others, we're just trying to improve our workflow on our systems.

The documentation is very helpful, although I found some parts very difficult to comprehend. So this I mention as a general remark for documentation creation: if there is some prerequisite knowledge expected, please give either explanation or links to explanations (like YouTube videos or lynda.com tutorials) for gathering the fundamental knowledge for coding with AHK. The very cursory understanding I have of HTML helps me to grasp some aspects (like "escaping out", the concepts of variables, etc.), but other things I can't seem to get my head around, like hooks.

I feel like much of the documentation departs from the focus on hotkeys (etc.), and becomes rather a general scripting language guide. I realize, of course, the necessity of explaining the language. But at the same time, for me, especially as a non‑programmer, I no longer see the relevance of certain aspects of the language to the hotkey programming. For example, the section in the tutorial and in the documentation regarding objects and arrays (and also the sections on variables) give very general examples, such as an array describing the properties of a banana. But none of the examples show how, why, and when to use them in defining a hotkey.

Let me give a very brief (I hope) practical example of what I'm working on presently. I'm using a program that has some keyboard shortcuts, but I want other functions to also have shortcuts. So I am using AHK to define them. Some functions are accessible using key strokes to pan through the menu bar; other functions are accessible only through the context menu; still others are (for some reason) only accessible through clicking the button in a toolbar. I'm trying to create at least 78 hotkeys. I'm sure there's a way to streamline the script using variables and objects, but I don't understand how to make them all work together. My script will certainly be long, but without an understanding of how to make these various parts work together in a hotkey script, I can't do much better than that.

So, my two suggestions for documentation improvement: 1) either clarify expected foreknowledge/experience level in general programming (and provide links to resources, like lynda.com or other tutorials, to help those who don't have that knowledge to get it), or be more thorough in explaining otherwise basic programming concepts in the documentation itself, so users only need a "one stop shop" to get all the information necessary for programming AHK scripts; and 2) make sure the documentation, including the tutorial, ties back around to the generation of hotkeys and hotstrings, so users can clearly see how these various scripting elements work together to compile useful codes specifically for hotkeys (etc.).

Thank you for your time and consideration. I appreciate your response.

[lmstearn]

Please forgive me for not reading through all 224 posts in this thread...
...be more thorough in explaining otherwise basic programming concepts in the documentation itself...
Thank you for your time and consideration. I appreciate your response.

Hey tjdickinson! None of the 86 tutorials or Tidbit's Beginner Tutorial suit?
Then there is Ask for Help where questions can be of a very general nature and there are plenty of folk who wish to help.
The AHK reference help has been a WIP over a good many years, yet there are some areas for the volunteers on it to cover e.g more illustrations with code, particularly of the special case, counter-example or "devil's advocate" variety, especially when v2 arrives. Personally I don't think some of it is as quite well expressed as the articles on MSDN, for example, but it is still concise and factual, and makes for a hefty read in some sections.
Unfortunately, as there is only one version of the manual, it would be a Herculean attempt for anyone to make a laymans, regular, or expert's version of it. (Well we have a regular, so that's a third accounted for )
A good option is to pluck a particular section from a topic and ask for an expansion on detail of it in the Ask for Help Section.
Or take an entire topic from it, reword it, and request feedback here on how the style applied to it is superior to the existing style.
Another is to refer to code with hotkeys which are well documented. They do exist!

[tjdickinson]

Please forgive me for not reading through all 224 posts in this thread...
...be more thorough in explaining otherwise basic programming concepts in the documentation itself...
Thank you for your time and consideration. I appreciate your response.

Hey tjdickinson! None of the 86 tutorials or Tidbit's Beginner Tutorial suit?

Thanks for your response! Tidbit's tutorial is fantastic, don't get me wrong! I certainly wouldn't be able to do anything with AHK without it! My remark was just that as it went on, and also in other parts of the documentation, it became more difficult to see how it should fit into hotkey programming. Tidbit has given me some great advice both in the forum and in the live chat, helping me to figure out how this or that fits into my hotkeys. I think the tutorial would be more accessible to non‑experienced people like myself if we could see just how and why something should function with hotkey scripting. I refer again to the objects part of the tutorial...it's unlikely I'll ever need to describe a banana if I'm programming hotkeys. A real‑world example of how objects help to make hotkeys would be much more tangible, in my opinion.

[Exaskryz]

I'm not sure what exactly could be written to meet your satisfaction, in all honesty. Think of hotkeys as a way to fire off your code when you manually want it to. Objects and all that are not tied to a hotkey's function... unless you want them to be. There are people who might use a hotkey and to send a random message in a chat or something. An array could be used in that. Functions can also be tied into this example as well:

Code: Select all

array:=["Hello","World","Multiple","Options"] ; in the auto-execute section
x::Send % array[myRandom(1,array.length())]

myRandom(lower,upper){
Random, var, %lower%, %upper%
return var
}

I mean, that's just an example, it's a weird purpose that not many people could use, but maybe that's the kind of thing you're looking for? Yes, it is higher level code because it depends on knowledge of arrays and their methods, expressions, and functions. But at the same time, it merges all those concepts into one script. If we wanted an example to highlight use of the array without the function, it'd look like this:

Code: Select all

array:=["Hello","World","Multiple","Options"]
x::
Random, var, 1, array.length()
Send % array[var]
return

Really the point is that the language is so flexible, there's no definitive instruction on how you should be using arrays or objects in your code -- it all depends on your personal goal. The documentation is really there to make sure you have the syntax right and you understand how the command works to transform input to output. But examples are given on most pages for your purpose.

[jeeswg]

Inconsistent title in search results for Hotkey command page (and possibly other help pages).

Is there a reason for this? Is the title stored multiple times, and differently, within the htm? The htm appears to have the usual <title>Hotkey</title>.

It confused me many times trying to find the page for the Hotkey command on Google, until I realised that the webpage title was always 'AutoHotkey' in the search results.

[title is: Hotkey]
Hotkey
https://autohotkey.com/docs/commands/Hotkey.htm

[title is: AutoHotkey]
ahk hotkey command - Google Search
https://www.google.com/#q=ahk+hotkey+command

[title is: Hotkey command]
ahk hotkey command - Bing
https://www.bing.com/search?q=ahk+hotkey+command

[title is: Hotkey command]
ahk hotkey command - Yahoo Search Results
https://search.yahoo.com/search;?p=ahk+hotkey+command

[lexikos]

It is because you searched for "ahk hotkey command", and these search engines try to be clever. The Hotkey page source code does not even contain the word "AutoHotkey".

Including "ahk" and "command" as search keywords skews the results. Use "site:autohotkey.com" instead.

[frogmorton]

This is pretty minor, but I think it would be useful to make it explicit that Instr (https://autohotkey.com/docs/commands/InStr.htm) returns 0 if the sought string isn't found (even though it's implied by the second sentence), and reiterate that the position of the left-most character is returned (this is stated in parameters).

This function returns the position of the left-most character in a specified occurrence of the string Needle in the string Haystack, or 0 if the specified occurrence of Needle is not found. Position 1 is the first character; this is because 0 is synonymous with "false", making it an intuitive "not found" indicator.

My additions are in bold. I could also see moving the second sentence to Remarks.

[Guest]

The AHK logo on the top left of the pages in the online documentation has a link back to the start https://autohotkey.com/docs/AutoHotkey.htm which is OK but it has a target=_blank so if you click it will open in a new tab each time. I find that a bit confusing. Perhaps done on purpose but I'd rather it would stay within the current tab/page and go to the homepage of the documentation e.g. replace _blank with _self or remove the target attribute entirely.

[just me]

GUI Events, Threads, and Subroutines

Clicking on a control while its g-label is already running from a prior click will have no effect and the event is discarded.

should be changed to something like

If a conrol event (e.g. clicking on a control) occurs while the associated g-label is already running from a prior event it will have no effect and the event is discarded.

[joedf]

"conrol" is a nice touch.

[just me]

That's why I wrote 'something like'.

[joedf]

haha touché !

[Gio]

Regarding DateTime controls, the docs state that:

If the control has a g-label, the label is launched whenever the user changes the date or time. For each launch, the control's associated output variable (if any) is automatically updated with the currently selected date/time.

However, the control's associated variable variable is updated whenever the user changes the contents of the control regardless of the control having a g-label. This has caused an issue for this user:
https://autohotkey.com/boards/viewtopic ... t=DATETIME

I suggest changing the text to something like:

Whenever the user changes the date or time in the control, the control's associated output variable (if any) is automatically updated with the currently selected date/time. If the control has a g-label, the label is also launched whenever the user changes the date or time.

(Link to Specific page of the docs)

[joefiesta]

The section on variables includes a subsection entitled "Built-In Variables". There one finds a number of tables of the various builtin variables.

Missing from those tables are : TRUE and FALSE

thank you

Joe Petree

[Gio]

Regarding the page of the docs for Arrays, the example code for Associative Arrays includes a lot of commented syntax that is actually Pseudo-Array syntax. I suggest removing it from the Associative Arrays examples as the pseudo-array section is right below it and it is quite confusing to include both syntaxes interchanging in the same examples.

This has caused an issue for this user: https://autohotkey.com/boards/viewtopic.php?f=5&t=36820

(Link to specific page of the docs)

[eagerahk]

This suggestion needs to be reconsidered. Thanks!