[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
TAC109
Posts: 1098
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Re: Suggestions on documentation improvements

09 Jan 2019, 16:57

Ragnar wrote:
09 Jan 2019, 05:02
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
My scripts:-
XRef - Produces Cross Reference lists for scripts
ReClip - A Text Reformatting and Clip Management utility
ScriptGuard - Protects Compiled Scripts from Decompilation
I also maintain Ahk2Exe
User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

09 Jan 2019, 17:02

"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.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

10 Jan 2019, 17:36

- 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
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
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

What does fileopen() do?

11 Jan 2019, 13:49

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
Posts: 8916
Joined: 30 Sep 2013, 06:48

Re: Suggestions on documentation improvements

11 Jan 2019, 14:21

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
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

12 Jan 2019, 12:47

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.)
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

12 Jan 2019, 17:11

It locks other programs from editing the file and keeps you from deleting it I think.
Recommends AHK Studio
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

13 Jan 2019, 03:47

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.
Recommends AHK Studio
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

14 Jan 2019, 10:12

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.
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

14 Jan 2019, 12:52

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
Recommends AHK Studio
User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

15 Jan 2019, 06:25

So what about
Opens a file to read specific content from it and/or to write new content into it.
Is this better?
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

16 Jan 2019, 18:03

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
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

21 Jan 2019, 11:04

@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
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Format()

21 Jan 2019, 11:13

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
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Guiescape (label)

23 Jan 2019, 12:14

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).
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

23 Jan 2019, 12:19

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
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

PixelGetColor format

30 Jan 2019, 15:52

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
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

30 Jan 2019, 16:01

on one hand it does clarify it somewhat, on the other hand it's duplication. idk
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

31 Jan 2019, 10:43

@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
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: Suggestions on documentation improvements

31 Jan 2019, 10:46

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.

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 12 guests