Suggestions on documentation improvements

Propose new features and changes
TAC109
Posts: 239
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 programs:-
ReClip - a Text Reformatting and Clip Management utility
XRef - Produces Cross Reference lists for scripts
User avatar
Ragnar
Posts: 210
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: 5555
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.

- Links:
IEEE 754 - Wikipedia
https://en.wikipedia.org/wiki/IEEE_754
Single-precision floating-point format - Wikipedia
https://en.wikipedia.org/wiki/Single-pr ... int_format
Double-precision floating-point format - Wikipedia
https://en.wikipedia.org/wiki/Double-pr ... int_format
joefiesta
Posts: 216
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.
User avatar
gregster
Posts: 1653
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: 216
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: 3685
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: 3685
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: 216
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: 3685
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: 210
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: 216
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

Yesterday, 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?

Return to “Wish List”

Who is online

Users browsing this forum: No registered users and 2 guests