[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
User avatar
tidbit
Posts: 1272
Joined: 29 Sep 2013, 17:15
Location: USA

Re: Suggestions on documentation improvements

22 Jul 2019, 14:56

ah, so they have been added/fixed. Thanks :) hopfully it'll be a bit more smooth to use now.
rawr. fear me.
*poke*
Is it December 21, 2012 yet?
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

22 Jul 2019, 15:08

Have any of you looked up the definition of EXPLICIT? And, that is THE ONLY THING ABOUT MY COMMENT THAT IS IMPORTANT. I know how built-in functions work.

Explicit: adjective
"fully and clearly expressed or demonstrated; leaving nothing merely implied; unequivocal: explicit instructions; an explicit act of violence; explicit language". (from dictionary.com)

And, from Merriam Webster:
"fully revealed or expressed without vagueness, implication, or ambiguity : leaving no question as to meaning or intent "

There is nothing "fully or clearly expressed" about a built-in function. And the call in the example to STRLEN, since IT COULD BE CALLED FROM A USER LIBRARY, is far from unequivocal.

The ONLY place STRLEN is defined is in the code that was compiled to create AHK.EXE.
Oh, it might be defined in the specifications for the function, but do they even exist?
gregster
Posts: 8886
Joined: 30 Sep 2013, 06:48

Re: Suggestions on documentation improvements

22 Jul 2019, 15:41

There is nothing "fully or clearly expressed" about a built-in function.
Well, sure, if you ignore the docs, yes... but since you are explicitly referencing the docs, you seem to be aware of their existence and contents.

The func object page which is linked directly and indirectly to on the page in question, gives further info and mentions explicitly built-in functions. Although I agree that the Func() page could also mention built-in functions more explicitly (while I also consider the example and associated infos valuable and essential parts of the docs), it would also be redundant to related pages (and there is already some redundancy). Generally, I would allow the author(s) of the docs a certain freedom in presenting and spreading the information over several pages, while it is certainly allowed to ask for improvements.
And the call in the example to STRLEN, since IT COULD BE CALLED FROM A USER LIBRARY, is far from unequivocal.
That example doesn't prescribe a certain outcome. But, afaics, some function named StrLen() will always be available, if you use an AHK version that corresponds to the docs version.

Also, the properties Name and IsBuiltIn aren't explained there, because they are already defined on the related and linked func object page. If someone wants to use function references, I would expect them to read related pages, if something isn't clear - especially the page about the func object (which could be featured more explicitly). I think, this is a not uncommon expectation in docs, in order to reduce redundancy. (But I would prefer, if the properties would be clickable.) But that's a matter of taste, of course.
Well, there is still some room on the Func() page, so if the inclusion is considered helpful and subsequently added, I probably wouldn't delete my bookmark to the docs out of protest, at least not permanently.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

31 Jul 2019, 10:26

I agree with joefiesta re. AHK internal limits:
Suggestions on documentation improvements - Page 29 - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=13&t=1434&p=285490#p285490

File object:
AHK v1 help: add 'Position' to the list of methods. (Already present in the AHK v2 help.)
(It might be good to implement 'Handle' in AHK v1, and add that to the AHK v1 help also.)

File object:
RawRead/RawWrite: 'and advances the file pointer' should be added for both.
For clarity, and consistency with other read/write methods.

FileOpen:
`n flag: it appears that 'standalone' should be added:
Replace `r`n with `n when reading and [standalone] `n with `r`n when writing.
For clarity, and consistency with `r flag.

chm file index:
Entries for the 'base' and 'this' keywords should be added.
Note: there may not currently be a good summary of the 'this' keyboard to link to. See:
terminology: objects/classes: keywords - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=66547

For loop:
The deprecated Remove method should be replaced.

Thanks.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
Peter2
Posts: 325
Joined: 21 Sep 2014, 14:38
Location: CH

Re: Suggestions on documentation improvements

05 Aug 2019, 08:13

Please add "WinWait(Close)" links / references to GUI
------------------------
Chapter "GUI" does not tell us about the importance of "WinWaitClose". For me it is totally new that a self-created GUI has to be stopped (Waited) after calling ...

Thanks
Peter (AHK Beginner) / Win 10 x64, AHK Version v1.1.33
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

05 Aug 2019, 10:21

what is the importance of WinWaitClose in relation to guis? elaborate
autocart
Posts: 214
Joined: 12 May 2014, 07:42

Re: Suggestions on documentation improvements

13 Aug 2019, 04:22

autocart wrote:
25 Jun 2019, 14:04
One question, though: What would be an example for
If conversion between code pages is necessary, the length of the return value may differ from the length of the source string.
? This is *not* talking about bytes, but is talking about characters, right?
Ragnar wrote:
26 Jun 2019, 04:19
I strongly suppose it means the length in characters, otherwise buffer size or similar would be written instead. For example, if you convert a string with a length of 10 characters to UTF-16, the converted string would only be 5 characters long, and vice versa.
autocart wrote:
26 Jun 2019, 04:38
That's exactly why I asked. The thing here is that the length of bytes will change from 10 to 5, if you convert from UTF-16 to UTF-8. The length of characters would in normal western cases not change. I am wondering if there might be special exceptional cases with certain unusual letters? Or if the length of characters could change when converting to unusual code pages? (Normally, I'd think not, but of course I am now a bit uncertain.)
Bump. Am I really wrong?
I thought, a conversion of the code-page would not "just" assign a different code-page to the sequence of bytes, but actually "map" the characters of the old code-page to the new code-page. Maybe I am wrong?
Could someone clarify that, please?

Thx in advance, regards, S.

EDIT:
I tested it now. Result: I must have had a brain block for a moment, sorry for that. Nevertheless, ...
Of course, StrPut must "map" the "ahk-intern" code-page to the code-page written. And StrGet must "map" the code-page read also back to the "ahk-intern" code-page.
However, if e.g. StrPut writes a string to address in the "utf-8" code-page and then StrGet reads from that address using the "utf-16" code-page, of course StrGet cannot know with which code-page in mind the bytes at address where written. That is up to the coder, to get that right. If the code-pages of StrPut and afterwards StrGet (both using the same address) differ, then the returned string of StrGet might differ in length of chars from the string written by StrPut (and actually it might also result in completely different chars.)
Therefore, the sentence
If conversion between code pages is necessary, the length of the return value may differ from the length of the source string.
in the help still is confusing. "Conversion" can only refer to the "mapping" between the code-page applied to the string at address and the "ahk-intern" code-page. In this case, the length of chars will not change. It can only change if the applied code-page when reading differs from the applied/intended code-page when writing. However, this is not a "conversion" but rather a "reinterpretation" or a "brutal assignment of a wrong code-page".
In conclusion, I would change the sentence to something like this:
If the code page used for StrGet does not correspond to the code page used when writing the string to address, then the returned string may differ from the original source string in both length and even characters.
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

13 Aug 2019, 05:25

I guess its not the length in characters but the length in code points.
Both utf-8 and utf-16 can encode one character with multiple code points. One Utf-8 code point is 8 bits where as 1 utf-16 code point is 16 bits. Utf-8 has to start encoding the unicode plane with multiple code points earlier than utf-16 - that would lead to a change in the strings length.
In AHK a strings length generally directly correponds to the amount of code points necessary to store the string - thats why you can get the size required to store the string by multiplying StrLen.
Recommends AHK Studio
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

22 Aug 2019, 18:17

CONTROL FLOW STATEMENTS: CASE? DEFAULT?
'Switch' is a CFS. The documentation should state if 'case'/'default' are/aren't CFSes. (And if not, what sort of thing they are.)
This could be mentioned in one or both of:
Switch
https://www.autohotkey.com/docs/commands/Switch.htm
Concepts and Conventions | AutoHotkey
https://www.autohotkey.com/docs/Concepts.htm#control-flow

INPUTHOOK: METHODS/PROPERTIES
KeyOpt is not in the methods list.
OnChar/OnKeyDown are not in the properties list.
Although all 3 have boxes lower down.
See:
Input - Syntax & Usage | AutoHotkey
https://www.autohotkey.com/docs/commands/InputHook.htm#object

SLEEP AND NOOP
Since(/while) there is no official NoOp, people are independently thinking of 'Sleep 1'/'Sleep 0' as a NoOp, which has disadvantages:
NOOP (No Operation) - Suggestions - AutoHotkey Community
https://autohotkey.com/board/topic/12707-noop-no-operation/
Check if variable has something - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=53553
(0) or an alternative could/should be recommended on the Sleep page as a NoOp.

STATEMENT SEPARATOR/STATEMENT TERMINATOR
Scripting Language | AutoHotkey
https://www.autohotkey.com/docs/Language.htm
Line breaks generally act as a statement separator
It would be helpful if the documentation could clarify what AHK uses for:
statement separator
statement terminator
E.g. this page mentions statement separators/statement terminators:
Comparison of programming languages (syntax) - Wikipedia
https://en.wikipedia.org/wiki/Comparison_of_programming_languages_(syntax)

FILE OBJECT: RAWREAD AND NULL BYTES
When RawRead is done, direct to a variable; it would be useful if the documentation could state if there are a guaranteed number of null bytes, directly after the buffer.
E.g. 1 null byte, and msvcrt\strlen can be used to safely search for null bytes.
E.g. 2 null bytes, and msvcrt\wcslen can be used to safely search for null shorts at even intervals (for an even-sized buffer).
E.g. 3 null bytes, and msvcrt\wcslen can be used to safely search for null shorts at even intervals (for an odd-sized buffer).

COMMAND PARAMETER TYPES
A minor point. In docs\static\source\data_index.js (AHK v1):
AFAICS, these:
Catch=I
KeyHistory=SS
Should be:
Catch=O
KeyHistory=
This information is useful for AHK v1 to AHK v2 converters/syntax highlighters.

Thanks.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
smouldery
Posts: 1
Joined: 23 Aug 2019, 05:25
Contact:

Re: Suggestions on documentation improvements

23 Aug 2019, 05:33

GUI >> GUI Control Types >> Edit >> Edit Options
"Number: Prevents the user from typing anything other than digits into the field (however, it is still possible to paste non-digits into it). An alternate way of forcing a numeric entry is to attach an UpDown control to the Edit."
Wording is unclear about pasting into edit box - can be read as "you CAN (as in normally/always) paste non-digits in the box" but the actual behavior of the control indicates it's more "you usually can't but it may still be possible". some clarity on this would be good.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: A_Programfiles

29 Aug 2019, 11:32

Doc for A_ProgramFiles states:
The Program Files directory (e.g. C:\Program Files or C:\Program Files (x86)). This is usually the same as the ProgramFiles environment variable
It goes on to clarify some qualifications for 64-bit systems.

on a 32-bit system, which is it: C:\Program Files or C:\Program Files (x86) ?
(The word USUALLY makes me ask that question.) I ask that because I have set the Programfiles (x86) environment variable on my 32-bit systems.

I think the whole explanation of A_ProgramFiles would be much clearer if there were two distinctly labeled sections: 1 for 32-bit systems and 1 for 64-bit sections.

Let me be the first to say I find the ProgramFiles (x86) stuff hard to fathom in lieu of the fact that so many 32 bit programs will install themselves in c:\Program Files on 64-bit systems. Why even have ProgramFiles (x86)? (this is probably best considered a rhetorical question.)
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Function SYNTAX

02 Sep 2019, 10:04

In the "Functions" section, the syntax for a function is not explicitly defined (other than by showing an example, which I would not consider a definition).

Specifically

1. The fact that it must includes BRACES and where they may be coded IS NOT EXPLICITLY STATED.

The word BRACE is not used until 3/4 of the way through the article.

As with commands, I feel Functions should include a SYNTAX box and START BY DEFINING their syntax.
User avatar
lmstearn
Posts: 681
Joined: 11 Aug 2016, 02:32
Contact:

Re: Suggestions on documentation improvements

07 Sep 2019, 10:35

Windows 1809: In example 7 in Gui: Examples, %A_WinDir%\system32\ntimage.gif won't load because it isn't there anymore.
Spoiler
:arrow: itros "ylbbub eht tuO kaerB" a ni kcuts m'I pleH
User avatar
jNizM
Posts: 3183
Joined: 30 Sep 2013, 01:33
Contact:

Re: Suggestions on documentation improvements

25 Sep 2019, 04:24

Remove the TimeUnits Parameter from Var -= Value [, TimeUnits] in EnvSub since this does not work
Ref: https://www.autohotkey.com/docs/commands/EnvSub.htm

works:
[code]tomorrow := ""
tomorrow += 1, days
MsgBox % tomorrow[/code]

Does not work:
[code]yesterday := ""
yesterday -= 1, days ; <- parameter #2 invalid.
MsgBox % yesterday[/code]
[AHK] v2.0.5 | [WIN] 11 Pro (Version 22H2) | [GitHub] Profile
gregster
Posts: 8886
Joined: 30 Sep 2013, 06:48

Re: Suggestions on documentation improvements

25 Sep 2019, 04:32

jNizM wrote:
25 Sep 2019, 04:24
Remove the TimeUnits Parameter from (Var -= Value [, TimeUnits] in EnvSub since this does not work
Ref: https://www.autohotkey.com/docs/commands/EnvSub.htm

Does not work:

Code: Select all

yesterday := ""
yesterday -= 1, days     ; <- parameter #2 invalid.
MsgBox % yesterday
Why? It works as advertised (yesterday is not in the right format in your example):
https://www.autohotkey.com/docs/commands/EnvSub.htm#Parameters wrote:If present, this parameter directs the command to subtract Value from Var as though both of them are date-time stamps in the YYYYMMDDHH24MISS format.

Code: Select all

var1 := 20050126
var2 := 20040126
EnvSub, var1, %var2%, days
MsgBox, %var1%  ; The answer will be 366 since 2004 is a leap year.
User avatar
jNizM
Posts: 3183
Joined: 30 Sep 2013, 01:33
Contact:

Re: Suggestions on documentation improvements

25 Sep 2019, 04:36

I talk about Var -= Value [, TimeUnits] and not EnvSub, Var, Value [, TimeUnits]
Image

My suggestion is just to delete the parameter TimeUnits in Var -= Value [, TimeUnits]
Image
[AHK] v2.0.5 | [WIN] 11 Pro (Version 22H2) | [GitHub] Profile
gregster
Posts: 8886
Joined: 30 Sep 2013, 06:48

Re: Suggestions on documentation improvements

25 Sep 2019, 04:38

Which are equivalent:
https://www.autohotkey.com/docs/commands/EnvSub.htm wrote:Synonymous with: Var -= Value.
Why would you delete it?
It works just the same like EnvSub:

Code: Select all

var1 := 20050126
var2 := 20040126
var1 -= var2, days
MsgBox, %var1%  ; The answer will be 366 since 2004 is a leap year.

var1 := 20050126
var2 := 20040126
EnvSub, var1, %var2%, days
MsgBox, %var1%  ; The answer will be 366 since 2004 is a leap year.
In your example above, yesterday is just not a timestamp in the YYYYMMDDHH24MISS format:
https://www.autohotkey.com/docs/commands/EnvSub.htm#Parameters wrote:If present, this parameter directs the command to subtract Value from Var as though both of them are date-time stamps in the YYYYMMDDHH24MISS format.
User avatar
jNizM
Posts: 3183
Joined: 30 Sep 2013, 01:33
Contact:

Re: Suggestions on documentation improvements

25 Sep 2019, 04:46

nvm.. its a date diff and not math.
It confused me with the word EnvSub from substract something

EnvAdd (sounds like add or + ) but it is math
EnvSub (sounds like substract or - ) but it is a diff for dates
[AHK] v2.0.5 | [WIN] 11 Pro (Version 22H2) | [GitHub] Profile
gregster
Posts: 8886
Joined: 30 Sep 2013, 06:48

Re: Suggestions on documentation improvements

25 Sep 2019, 04:51

Yeah, this happens all 3-4 years to me. ;)
Until I remember again...
User avatar
jNizM
Posts: 3183
Joined: 30 Sep 2013, 01:33
Contact:

Re: Suggestions on documentation improvements

25 Sep 2019, 04:52

I use this so rarely that I didn't keep it from the last time :D
[AHK] v2.0.5 | [WIN] 11 Pro (Version 22H2) | [GitHub] Profile

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 13 guests