Suggestions on documentation improvements

Propose new features and changes
User avatar
tidbit
Posts: 1131
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: 270
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: 2661
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: 6547
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: 243
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 7 x64, AHK Version v1.1.22.xx
swagfag
Posts: 2758
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: 149
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: 4233
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

Return to “Wish List”

Who is online

Users browsing this forum: No registered users and 18 guests