[Archived, Locked] Suggestions on documentation improvements

[TAC109]

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.

Thanks

[Ragnar]

"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:

This always hides the maximize and minimize buttons, regardless of whether the WS_MAXIMIZEBOX and WS_MINIMIZEBOX styles are present.

[jeeswg]

- 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

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).

- 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.
- [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

[joefiesta]

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.

[gregster]

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

[joefiesta]

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.)

[nnnik]

It locks other programs from editing the file and keeps you from deleting it I think.

[nnnik]

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.

[joefiesta]

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.

[nnnik]

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

[Ragnar]

So what about

Opens a file to read specific content from it and/or to write new content into it.

Is this better?

[joefiesta]

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?

[joefiesta]

@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.

[joefiesta]

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: 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.

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

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.

[joefiesta]

at https://autohotkey.com/docs/commands/Gui.htm#GuiEscape is defined the GUIESCAPE label. It states:

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.

The second sentence is not entirely correct. It should read:

If this label is absent, pressing Escape has no effect (unless an ESCAPE hotkey has been defined).

[nnnik]

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.

[joefiesta]

PixelGetColor:

this doc states, for COLORID,

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.

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. The default format (BGR) may be overridden by use of the Mode RGB option (see below).

[swagfag]

on one hand it does clarify it somewhat, on the other hand it's duplication. idk

[joefiesta]

@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.

[Helgef]

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.