ThanksRagnar wrote: ↑09 Jan 2019, 05:02The 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.
[Archived, Locked] Suggestions on documentation improvements
Re: Suggestions on documentation improvements
My scripts:-
XRef - Produces Cross Reference lists for scripts
ReClip - A Text Reformatting and Clip Management utility
ScriptGuard - Protects Compiled Scripts from Decompilation
XRef - Produces Cross Reference lists for scripts
ReClip - A Text Reformatting and Clip Management utility
ScriptGuard - Protects Compiled Scripts from Decompilation
Re: Suggestions on documentation improvements
"present by default" means more like "this style is present by default". The default styles of a GUI window are WS_POPUP, WS_CAPTION, WS_SYSMENU and WS_MINIMIZEBOX (see common styles). As you can see, WS_MAXIMIZEBOX alias MaximizeBox is not included.
Regarding point 2, I will add the following sentence:
Regarding point 2, I will add the following sentence:
This always hides the maximize and minimize buttons, regardless of whether the WS_MAXIMIZEBOX and WS_MINIMIZEBOX styles are present.
Re: Suggestions on documentation improvements
- The DllCall page is a bit vague about the Float and Double types.
DllCall() - Syntax & Usage | AutoHotkey
https://autohotkey.com/docs/commands/DllCall.htm#types
- It could probably be more specific cf. this link re. AHK's native floating-point format, which mentions binary64 and IEEE 754.
Concepts and Conventions | AutoHotkey
https://autohotkey.com/docs/Concepts.htm#pure-numbers
- [EDIT:] Also, there is the question of whether any revisions are important re. functionality.
- Links:
IEEE 754 - Wikipedia
https://en.wikipedia.org/wiki/IEEE_754
IEEE 754-1985 - Wikipedia
https://en.wikipedia.org/wiki/IEEE_754-1985
IEEE 754-2008 revision - Wikipedia
https://en.wikipedia.org/wiki/IEEE_754-2008_revision
Single-precision floating-point format - Wikipedia
https://en.wikipedia.org/wiki/Single-precision_floating-point_format
Double-precision floating-point format - Wikipedia
https://en.wikipedia.org/wiki/Double-precision_floating-point_format
DllCall() - Syntax & Usage | AutoHotkey
https://autohotkey.com/docs/commands/DllCall.htm#types
- It could probably be more specific cf. this link re. AHK's native floating-point format, which mentions binary64 and IEEE 754.
Concepts and Conventions | AutoHotkey
https://autohotkey.com/docs/Concepts.htm#pure-numbers
- I could guess that DllCall's Float and Double types are equivalent to the IEEE 754 binary32 and binary64 formats, but I haven't seen any evidence for this. Thanks.AutoHotkey primarily uses two data types for pure numbers:
•64-bit signed integers (int64).
•64-bit binary floating-point numbers (the double or binary64 format of the IEEE 754 international standard).
- [EDIT:] Also, there is the question of whether any revisions are important re. functionality.
- Links:
IEEE 754 - Wikipedia
https://en.wikipedia.org/wiki/IEEE_754
IEEE 754-1985 - Wikipedia
https://en.wikipedia.org/wiki/IEEE_754-1985
IEEE 754-2008 revision - Wikipedia
https://en.wikipedia.org/wiki/IEEE_754-2008_revision
Single-precision floating-point format - Wikipedia
https://en.wikipedia.org/wiki/Single-precision_floating-point_format
Double-precision floating-point format - Wikipedia
https://en.wikipedia.org/wiki/Double-precision_floating-point_format
Last edited by jeeswg on 14 Apr 2019, 14:58, edited 1 time in total.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
What does fileopen() do?
What does fileopen() do? the doc says, very tersly, "Opens a file".
There is more to it that than, and I don't think it actually "opens" a file.
If I use Windows Explorer--yes, that is an application and so may use it's own terminology--and I right click a file and select OPEN, the file opens. If it is a PDF, for example and the filetype .PDF is registered to a program, it OPENS the file (using the registered program).
Considering that, one expects:
fileopen("c:\mypdf.pdf")
to open the file C:\mypdf.pdf with the registered program. IT DOES NOT.
There are either multiple definitions of OPEN for computer terminology, or OPEN, in the case of FILEOPEN(), is a misnomer.
To me it LOADS the file (into storage). But, I'm not really sure what it does. In either case, I feel FILEOPEN() needs better documentation.
There is more to it that than, and I don't think it actually "opens" a file.
If I use Windows Explorer--yes, that is an application and so may use it's own terminology--and I right click a file and select OPEN, the file opens. If it is a PDF, for example and the filetype .PDF is registered to a program, it OPENS the file (using the registered program).
Considering that, one expects:
fileopen("c:\mypdf.pdf")
to open the file C:\mypdf.pdf with the registered program. IT DOES NOT.
There are either multiple definitions of OPEN for computer terminology, or OPEN, in the case of FILEOPEN(), is a misnomer.
To me it LOADS the file (into storage). But, I'm not really sure what it does. In either case, I feel FILEOPEN() needs better documentation.
Re: Suggestions on documentation improvements
In my understanding, FileOpen() literally opens a file for directly writing to and reading from it (including raw binary data).
Yes, its return value is a file object which "[p]rovides an interface for file input/output"; that means it doesn't open a file with the program it might be associated with via the registry (or some other specified program) - that would be run.
But afaik, the AHK usage of "opening a file" corresponds to the usage of the term in other programming languages like C++ or the Windows API.
That's why I wouldn't call it a misnomer.
As always, that doesn't mean that we have reached peak AHK docs
Yes, its return value is a file object which "[p]rovides an interface for file input/output"; that means it doesn't open a file with the program it might be associated with via the registry (or some other specified program) - that would be run.
But afaik, the AHK usage of "opening a file" corresponds to the usage of the term in other programming languages like C++ or the Windows API.
That's why I wouldn't call it a misnomer.
As always, that doesn't mean that we have reached peak AHK docs

Re: Suggestions on documentation improvements
Okay, OPEN may not be a misnomer. But, my whole point is this: There is nothing in the documentation of FILEOPEN() to lead an AHK user (of any degree of expertise) to believe that when he codes "xx := fileopen("C:\Mypdf.pdf")" , for example, the PDF will not be "opened" by a PDF reader program .
I come from a mainframe background. There, when a file is OPENed, all that occurs is a control block is created (after, of course, validating the file's existence, etc.). My suspicion is that windows (DOS?) FILEOPEN (I am assuming FILEOPEN is a windows function) does just the same thing. Is that true, or does the creation of the "object" mean the file is actually LOADED into storage (in one form or another)? (Yes, i could discover this empirically by testing the speed of FILEOPEN() or checking the resource utilization of the test script... But, I don't want to get knowledge that way in this case.)
I come from a mainframe background. There, when a file is OPENed, all that occurs is a control block is created (after, of course, validating the file's existence, etc.). My suspicion is that windows (DOS?) FILEOPEN (I am assuming FILEOPEN is a windows function) does just the same thing. Is that true, or does the creation of the "object" mean the file is actually LOADED into storage (in one form or another)? (Yes, i could discover this empirically by testing the speed of FILEOPEN() or checking the resource utilization of the test script... But, I don't want to get knowledge that way in this case.)
Re: Suggestions on documentation improvements
It locks other programs from editing the file and keeps you from deleting it I think.
Recommends AHK Studio
Re: Suggestions on documentation improvements
On the DLLCall page, in the ptr type description, there is a note that:
In order to pass NULL to a function pass the Integer 0.
This note is more confusing than helpful. We need to remove it, or rephrase it in a way that people know that an Integer value is meant and not the int type.
In order to pass NULL to a function pass the Integer 0.
This note is more confusing than helpful. We need to remove it, or rephrase it in a way that people know that an Integer value is meant and not the int type.
Recommends AHK Studio
Re: Suggestions on documentation improvements
Re: FILEOPEN
Does Fileopen() invoke the File.open method (described here: https://docs.microsoft.com/en-us/dotnet ... work-4.7.2 )?
If it does, it should be noted that there the open process is described as "Opens a FileStream on the specified path."
And, if it does, then I believe the doc for FILEOPEN() should say the same thing.
A second possibility is that FILEOPEN() uses the FileSystem.FileOpen method, described here: https://docs.microsoft.com/en-us/dotnet ... work-4.7.2
There, the open process is defined as: "Opens a file for input or output. The My feature gives you better productivity and performance in file I/O operations than FileOpen. For more information, see FileSystem."
But, that definition is distinctly different than that supplied by AHK doc.
Does Fileopen() invoke the File.open method (described here: https://docs.microsoft.com/en-us/dotnet ... work-4.7.2 )?
If it does, it should be noted that there the open process is described as "Opens a FileStream on the specified path."
And, if it does, then I believe the doc for FILEOPEN() should say the same thing.
A second possibility is that FILEOPEN() uses the FileSystem.FileOpen method, described here: https://docs.microsoft.com/en-us/dotnet ... work-4.7.2
There, the open process is defined as: "Opens a file for input or output. The My feature gives you better productivity and performance in file I/O operations than FileOpen. For more information, see FileSystem."
But, that definition is distinctly different than that supplied by AHK doc.
Re: Suggestions on documentation improvements
AHK does not use .NET at all. AHK uses the WinAPI directly it seems to open the stream with:
https://docs.microsoft.com/en-us/window ... reatefilew
https://docs.microsoft.com/en-us/window ... reatefilew
Recommends AHK Studio
Re: Suggestions on documentation improvements
So what about
Is this better?Opens a file to read specific content from it and/or to write new content into it.
Re: Suggestions on documentation improvements
A small digression re FILEOPEN() (since I've been studying more deeply): Why are some FLAG NUMBERS shown as decimal while others are shown as hexadecimal?
Re: Suggestions on documentation improvements
@Ragnar: Re: "is this better?" Yes, that is MUCH better. It may still not be perfect,but not knowing enough about what goes on programatically when a file is "opened", I can't suggest anything that may be more perfect.
Format()
I find the FORMAT() function one of the most difficult to understand. It is complicated--but, that can not be helped. However, it's doc has much room for improvement.
PRECISION: Included is the following:
PRECISION: Included is the following:
What is the stuff about F, e, E etc. about? There is NO EXPLANATION of what is trying to be expressed here. I believe the doc would be greatly improved by changing it, perhaps something like:Precision: a decimal integer which controls the maximum number of string characters, decimal places, or significant digits to output, depending on the output type. It must be preceded by a decimal point. Specifying a precision may cause the value to be truncated or rounded.
•f, e, E: Precision specifies the number of digits after the decimal point. The default is 6.
•g, G: Precision specifies the maximum number of significant digits. The default is 6.
•s: Precision specifies the maximum number of characters to be printed. Characters in excess of this are not printed.
•For the integer types (d, i, u, x, X, o), Precision acts like Width with the 0 prefix and a default of 1.
Precision: a decimal integer which controls the maximum number of string characters, decimal places, or significant digits to output, depending on the output type. It must be preceded by a decimal point. Specifying a precision may cause the value to be truncated or rounded
Output types and how each is affected by the precision value are as follows. See table below for an explanation of the different output types.
•f, e, E: Precision specifies the number of digits after the decimal point. The default is 6.
•g, G: Precision specifies the maximum number of significant digits. The default is 6.
•s: Precision specifies the maximum number of characters to be printed. Characters in excess of this are not printed.
•For the integer types (d, i, u, x, X, o), Precision acts like Width with the 0 prefix and a default of 1.
Guiescape (label)
at https://autohotkey.com/docs/commands/Gui.htm#GuiEscape is defined the GUIESCAPE label. It states:
The second sentence is not entirely correct. It should read:GuiEscape: Launched when the user presses Escape while the GUI window is active. If this label is absent, pressing Escape has no effect. Known limitation: If the first control in the window is disabled (possibly depending on control type), the GuiEscape label will not be launched. There may be other circumstances that produce this effect.
If this label is absent, pressing Escape has no effect (unless an ESCAPE hotkey has been defined).
Re: Suggestions on documentation improvements
Nah I would just remove that part. And rewrite it as "Escape does not have a default action that will be overwritten by the presence of this label" or similar.
Recommends AHK Studio
PixelGetColor format
PixelGetColor:
this doc states, for COLORID,
this doc states, for COLORID,
This is not entirely correct. It should be revised something like the following:ColorID
The decimal or hexadecimal color ID to search for, in Blue-Green-Red (BGR) format, which can be an expression. Color IDs can be determined using Window Spy (accessible from the tray menu) or via PixelGetColor. For example: 0x9d6346.
ColorID
The decimal or hexadecimal color ID to search for, in Blue-Green-Red (BGR) format, which can be an expression. Color IDs can be determined using Window Spy (accessible from the tray menu) or via PixelGetColor. For example: 0x9d6346. The default format (BGR) may be overridden by use of the Mode RGB option (see below).
Re: Suggestions on documentation improvements
on one hand it does clarify it somewhat, on the other hand it's duplication. idk
Re: Suggestions on documentation improvements
@swagfag:
It is not duplication. I should not have to read the details of EVERY option just to learn the FULL details of ONE. Do you expect people to read an entire documentation entry for one piece of information? It is also not duplication because the way I have suggested it be written makes the reader go to MODE RGB option to get the exact details.
It is not duplication. I should not have to read the details of EVERY option just to learn the FULL details of ONE. Do you expect people to read an entire documentation entry for one piece of information? It is also not duplication because the way I have suggested it be written makes the reader go to MODE RGB option to get the exact details.
Re: Suggestions on documentation improvements
You should read about all parameters before attempting to call the function. I think it is redundant, but certainly no big deal either way.
Cheers.
Cheers.
Return to “Suggestions on Documentation Improvements”
Who is online
Users browsing this forum: No registered users and 3 guests