[Archived, Locked] Suggestions on documentation improvements

[lexikos]

Adding prefix "My" to examples #126
https://github.com/Lexikos/AutoHotkey_L-Docs/pull/126

In almost every example, the variable names are just variable names and have no special meaning to the interpreter (but some have meaning to the reader). You can use virtually whatever name you want (except operators like and/or and built-in variable names), even if it's the name of a function or command. Array := Array() demonstrates this. I don't really understand the "keyword vs not" confusion you seem to be concerned about, but I suppose that the problem would be averted by teaching the basics of the language first.

It's like I said before,

I think the underlying problem is that there is no structured overview of the language, nor anything to teach the basic programming concepts required to tie everything together.

Have you considered that if every example uses the same name, users mightn't see that they can use whatever name they want?

"FuncRef" doesn't appear to follow the convention - no "My" prefix. Furthermore, the variable merely contains a reference to an object of type "Func", yet for other object types you do not use the "Ref" suffix. Later in the page you've replaced "func" (a method name) with "Function" - I can't imagine why. I can understand why you've replaced "func" (the parameter) with "aFunc", but in that case the parameter was being defined in the example, so it should already be especially clear that it's not a keyword in that context.

Why shorten "Parameters" to "Params", but expand "RetVal" to "ReturnValue"?

"Parameters" should be replaced with - not contain - a list of parameters. (It is assumed that the reader is already familiar with function calls and knows how to write a parameter list.) I don't know of anywhere else in the documentation that uses "params" other than as the name of a variable/parameter containing an array of parameter values, which is not what is needed in this case. By contrast, "RetVal" is just an arbitrary variable name; the assignment is there to succinctly show that the expression yields the function's return value.

I don't see the purpose of replacing "length" with "StringLength". As far as I can recall, none of the method/property names for any of the built-in objects include the object type in the method/property name. I think that would be contrary to common OOP conventions.

[fxx]

https://www.autohotkey.com/docs/commands/NumGet.htm

"General remarks" part is likely copied from NumPut and not changed to apply to NumGet.

[T-Rock]

I don't really understand the "keyword vs not" confusion you seem to be concerned about, but I suppose that the problem would be averted by teaching the basics of the language first.

Ok, if you reduce it to this, my pull request doesn’t make sense.
Meanwhile I understand the examples, but they did not support me, if I needed it.
But maybe that's just me.

[T-Rock]

In almost every example, the variable names are just variable names and have no special meaning to the interpreter (but some have meaning to the reader). You can use virtually whatever name you want (except operators like and/or and built-in variable names), even if it's the name of a function or command. Array := Array() demonstrates this.

You are right (of course), but these examples are not about showing or expressing this fact, they are about using objects.

I don't really understand the "keyword vs not" confusion you seem to be concerned about, but I suppose that the problem would be averted by teaching the basics of the language first.

I am still struggling with this argument.
I think the main point ist, even if a user knows the basics, if he starts the first time in his life with objects (while developing a script), these examples are more confusing than helping.
For me it looks like that you require users to have already experience and knowledge with objects, before they should start using objects in AutoHotkey.

It's like I said before,

I think the underlying problem is that there is no structured overview of the language, nor anything to teach the basic programming concepts required to tie everything together.

Sounds like a longterm goal, so why not simplify examples meanwhile to compensate this a little bit?

Have you considered that if every example uses the same name, users mightn't see that they can use whatever name they want?

Yes, I did and I think that could be explained in one or two sentences (which I do not have in the pull request ...).
Have you considered, that maybe on the other hand exactly this could run like a golden thread through this chapter?

Why shorten "Parameters" to "Params", but expand "RetVal" to "ReturnValue"?

Consistency, „ReturnValue was already used in this form before.
What are the rules to shorten a word and when to shorten it?
Why shorten words at all in examples?
These examples are not supposed to show a good developing style at first but to explain how to use objects.

[lexikos]

I think the main point ist, even if a user knows the basics, if he starts the first time in his life with objects (while developing a script), these examples are more confusing than helping.

What do you find confusing?

My point about the basics is this: If a user is confused about (for example) which "Array" in Array := Array() is meant literally and which is meant as an example, he probably does not know the basics. For the variable, obviously you should assign to whichever variable you want to store the value (the array) in. For the function call, you obviously can't change the name because then you would be calling a different function.

On the other hand, maybe he knows the basics and just isn't thinking rationally.

Consistency, „ReturnValue was already used in this form before.

My question was why you made one shorter and the other longer. It bothered me because it is inconsistent, so it is ironic that you would say you did it for consistency. It wasn't for clarity either, since "Parameters" is clearer than "Params".

On review, I see that I had used "Params" in the Function References section (written in 2015) and "Parameters" in the Objects section (written in 2011). They should have both been "Parameters".

Why shorten words at all in examples?

For brevity.

[nnnik]

The SendMessage page creates the impression that:

Code: Select all

N:="New Title"
SendMessage,0xC,0,N,,Unbenannt - Editor

works. Yet it does not.

[just me]

A string may be sent via wParam or lParam by specifying the address of a variable. The following example uses the address operator (&) to do this:

Code: Select all

SendMessage, 0xC, 0, &MyVar, ClassNN, WinTitle  ; 0XC is WM_SETTEXT

In v1.0.43.06+, a string put into MyVar by the receiver of the message is properly recognized without the need for extra steps. However, this works only if the parameter's first character is an ampersand (&); for example, 5+&MyVar would not work but &MyVar or &MyVar+5 would work.

A quoted/literal string may also be sent as in the following working example (the & operator should not be used in this case):

Code: Select all

Run Notepad
WinWait Untitled - Notepad
SendMessage, 0xC, 0, "New Notepad Title"  ; 0XC is WM_SETTEXT

?

[Bruttosozialprodukt]

Not sure if that was suggested before, but I would really like to know if there is a good reason to not document the Frequently-used functions in the same way most (if not all) other commands are documented. I mean in a more structured way with examples etc..
I caught myself probably more than 20 times now reading through the SubStr documentation just to find a detail that I keep forgetting. https://autohotkey.com/docs/Functions.htm#SubStr
And I really feel like I spend way too much time on reading just to find that little detail.
That doesn't really happen for other commands because there is a good chance you will simply remember where exactly that detail was located.
That doesn't really work too well for a single block of text.

I'd be willing to write the new documentation sites including examples myself if they would get added.

[lexikos]

I'd be willing to write the new documentation sites including examples myself if they would get added.

Please do.

It was suggested on Trello in 2012 and there are even a few open issues on GitHub for it.

[Bruttosozialprodukt]

Great! So how does this work? Do I just post the files here?

[lexikos]

I would prefer that you fork the project on GitHub and submit a pull request. You may post the files here instead if you wish.

[Bruttosozialprodukt]

Oh that makes sense. I didn't know there was a second repository for the docs.

[Exaskryz]

Is there any documentation or quick-start guide to the Window Spy tool? The only mention I can find outside of the forums that I can find is on the homepage with the quote "A tool to retrieve detailed information about program windows and controls. Right click AutoHotkey tray icon to activate." (And of course, many mentions in the documentation with that say "(as revealed by the included Window Spy utility)" with that exact quote coming from the note on "WinText" parameters.) While the purpose of the tool and how to access it (albeit only one way, and admittedly missing a step as a right click alone won't launch it) is contained in those two sentences, I don't know if people will really turn to the homepage and scroll down that far to get help. We have a nice big "Docs" button in the first screen of the homepage. I expect any users who would've been keen enough to pick up on the information they were looking for being on the front page would have turned to the documentation once they saw that as a possible place to find their desired information.

The alternative people had would just be going into the search bar and searching Window Spy. Unfortunately there's not a clear best result here. The top result, in subsets of archived/forums, is this one: https://autohotkey.com/board/topic/6336 ... indow-spy/ which is an answered question for how to launch the tool.

If someone could write up what each of the items/data listed in a Window Spy tool has and some examples of code based on a screenshot of the tool, that would be nice to see. Example code I was thinking of would be kind of redundant of things like WInTitle to explain how to use the values found in Window Spy; how to use ControlClick or ControlSend in conjunction with the screenshot of the tool; PixelSearch; MouseMove and MouseClick/Click and differentiating the CoordModes; and finally WinMove. (Perhaps also including how MouseGetPos, WinGetPos, WinGetTitle, and PixelGetColor can get you the same information?)

[helpy]

@Exaskryz: you could create a tutorial with screenshots + basic examples in the tutorial section so it can be linked to from the official AutoHotkey documentation?

[jNizM]

Scripts.htm#ahk2exe
==> mpress.exe Website is down for a long time.

Should we host it (mpress) on autohotkey.com?

mpress.zip (95 KB)

Code: Select all

BugReport.txt
FAQ.TXT
History.txt
license.txt
mpress.exe

VirusTotal Scan (SHA256: 19ffee93706dff67f83d9ef48c0c794dea761d4459b11c37f9bc65b04af736c5)

[TheDewd]

Should we host it (mpress) on autohotkey.com?

+1

I found another mirror by HotKeyIt... Located in the following archive in the "Compiler" folder:
https://github.com/HotKeyIt/ahkdll-v1-r ... master.zip

[joedf]

So sad.
I doubled checked the license.
It's basically a pseudo-MIT license.
I will have it hosted in my free time, if nobody gets to it before I do.

[joedf]

did a quick search on WaybackMachine and got their latest snapshot...
https://web.archive.org/web/20150801005 ... mpress.htm
It would have been great to release the source if it were to be abandonned...

[DrReflex]

Using GuiControl with HWND as the ControlID is not adequately documented. This is a variant usage of HWND compared to the other GUI Control functions. When using HWND as the ControlID - ONLY - the HWND value is used as the ControlID.

Because this is a variant, there should be an example in the AHK wiki GuiControl entry:

GuiControl,, %ControlHwnd%, %MyNewText%
WHERE ControlHwnd contains the HWND value for the control whose text is to be replaced
AND MyNewText contains the text to replace the existing text.

NOTE: A control's HWND can be obtained while adding a control to a GUI, with ControlGet, with MouseGetPos, and with WInGet.

[lexikos]

Using GuiControl with HWND as the ControlID is not adequately documented.

What's not clear about "ControlID can be the HWND of a control"? A HWND is a HWND. "ahk_id 0x1234" is not a HWND; it is a keyword followed by a HWND.

This is a variant usage of HWND compared to the other GUI Control functions. When using HWND as the ControlID - ONLY - the HWND value is used as the ControlID.

I think what you're saying is that passing the HWND is different with GuiControl than with the Win and Control functions, which use the ahk_id prefix. None of the GUI commands use the ahk_id prefix, because none of those commands have a WinTitle parameter.

the AHK wiki GuiControl entry

The what? If the documentation was in wiki form, you could add it yourself.

Because this is a variant, there should be an example in the AHK wiki GuiControl entry:

GuiControl,, %ControlHwnd%, %MyNewText%

I'd agree that an actual example of retrieving and using a HWND may be helpful, but I don't see how this example helps anyone. That still doesn't show what the value should be. It just shows basic parameter/variable substitution, which everyone should already know.