Suggestions on documentation improvements

Propose new features and changes
joefiesta
Posts: 264
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Continuation with Left Parenthesis

11 Jun 2019, 20:03

When starting a continuation section with a left parenthesis, that parenthesis and, optionally, any options for the continuation section, must be the only text on that line, with the exception that it may also be followed by a comment.

this is not stated in the documentation.
User avatar
jeeswg
Posts: 6452
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

20 Jun 2019, 21:42

STRPUT/STRGET
- Under 'Encoding', for complete clarity, it should say something like:
- If Encoding is not specified, it is UTF-16 (on Unicode versions) or CP0 (on ANSI versions).
- More details, here:
Basic question about the string terminator in ahk - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=65586&p=281714#p281714
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
autocart
Posts: 148
Joined: 12 May 2014, 07:42

Re: Suggestions on documentation improvements

21 Jun 2019, 07:04

joefiesta wrote:
29 Apr 2019, 08:28
Doc states:
A_ScriptDir The full path of the directory where the current script is located. The final backslash is omitted (even for root directories).

A_ScriptName The file name of the current script, without its path, e.g. MyScript.ahk.

A_ScriptFullPath The combination of the above two variables to give the complete file specification of the script, e.g. C:\My Documents\My Script.ahk
The explanation for A_ScriptFullPath is not exact. It should mention that the two variables are concatenated WITH A BACKSLASH added between them.
Helgef wrote:
29 Apr 2019, 12:55
@joefiesta the variable wouldn't yield the complete file specification of the script if it returned something which was missing something, such aa a backslash.
Helgef, although, I think, nobody would expect A_ScriptFullPath to return the path with a missing backslash somewhere in the middle, still joefiesta is right. The first part of the sentence "The combination of the above two variables to give the complete file specification of the script, e.g. C:\My Documents\My Script.ahk" actually conflicts with the second part. It might seem trivial, but all things start small, bad things as well as good things. I think, since it was noted, it would be wrong to accept, even small incorrect statements in the help file. Next time another will be accepted and another. Either we want to improve the help (I thought that is what this thread is here for) or not.
autocart
Posts: 148
Joined: 12 May 2014, 07:42

Re: Suggestions on documentation improvements

21 Jun 2019, 19:06

jeeswg wrote:
20 Jun 2019, 21:42
STRPUT/STRGET
- Under 'Encoding', for complete clarity, it should say something like:
- If Encoding is not specified, it is UTF-16 (on Unicode versions) or CP0 (on ANSI versions).
- More details, here:
Basic question about the string terminator in ahk - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=65586&p=281714#p281714
I agree, but think also that there is much more wrong with this particular help page "StrPut() / StrGet()".

Therefore, in order to be productive, though, and not destructive with lots of critisism, I tried to make a new, better, page "StrGet() / StrPut()". (I even felt it better to rename the title, swapping the order of the two functions. I hope I did not step on any toes with the suggestion of the whole revision of this chapter.)
I put it in a pdf, which is attached to this post. Could you guys look over it and tell me if I have anything wrong? Many thanks in advance.
Regards, S.
Attachments
StrGetPut_new.pdf
(106.44 KiB) Downloaded 20 times
autocart
Posts: 148
Joined: 12 May 2014, 07:42

Re: Suggestions on documentation improvements

25 Jun 2019, 03:27

Compare https://www.autohotkey.com/docs/misc/WinTitle.htm#LastFoundWindow
with https://www.autohotkey.com/docs/commands/WinGet.htm#List
and https://www.autohotkey.com/docs/commands/WinGet.htm#Count

Since, https://www.autohotkey.com/docs/misc/WinTitle.htm#LastFoundWindow already lists where LastFoundWindow can not be used, should it not also include "WinGet, OutputVar, List" and "WinGet, OutputVar, Count"? At least, it is not 100% accurate right now and potentially confusing.
User avatar
Ragnar
Posts: 239
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

25 Jun 2019, 10:35

You're right, they should be included. All changes I made can be found on GitHub as always.

Regarding StrGet / StrPut: Changes of this size should be submitted via pull request on GitHub to get a better overview of what exactly you have changed. In my opinion, I don't see any significant improvement here. Also, the boxes in the return value section bother me, although I can understand your attempt - a better distinction is needed. That's why I split StrGet / StrPut into two separate pages in the v2 docs. However, I don't think it's worth the effort to do this split for the v1 docs, because there are some things that have to be taken into account due to its long-term usage.
autocart
Posts: 148
Joined: 12 May 2014, 07:42

Re: Suggestions on documentation improvements

25 Jun 2019, 13:47

Ragnar wrote:
25 Jun 2019, 10:35
You're right, they should be included.
Thx for the confirmation.
Ragnar wrote:
25 Jun 2019, 10:35
Regarding StrGet / StrPut: Changes of this size should be submitted via pull request on GitHub to get a better overview of what exactly you have changed. In my opinion, I don't see any significant improvement here. Also, the boxes in the return value section bother me, although I can understand your attempt - a better distinction is needed. That's why I split StrGet / StrPut into two separate pages in the v2 docs. However, I don't think it's worth the effort to do this split for the v1 docs, because there are some things that have to be taken into account due to its long-term usage.
Thanks for taking the time to look at it! IMHO it is much more easy to understand. The layout and style is only meant as an example and of course matter to taste. It is good to hear that these two fuctions will be split up in the docs of v2. Yes, I agree then, that in v1 no real changes are needed. So, I will refrain from making a pull request and wait for v2.

[EDIT:]
Of course v2 doc is already online and I had a quick look.
https://lexikos.github.io/v2/docs/commands/StrGet.htm
The parameter Target is named in a confusing way. Would be easier to understand if it was called Source (maybe?). Target is something where one copies something TO and not from.
All in all, it is much better, I think.
autocart
Posts: 148
Joined: 12 May 2014, 07:42

Re: Suggestions on documentation improvements

25 Jun 2019, 14:04

Ok, I saw something else:
String := StrGet(Target [, Length] [, Encoding := None])
...
Encoding
Type: String

The source encoding; for example, "UTF-8", "UTF-16" or "CP936". If Target and Length are not specified, numeric identifiers must be prefixed with "CP". Specify an empty string or "CP0" to use the system default ANSI code page.
Target CAN NOT not be specified. Besides, Encoding could be String or Integer and it's safer to say that in case Length *is* specified the CP may be left away and it may be numeric. The prefixed CP is the one which works always, not the other way around.

I am having 2nd thoughts about my "all in all" statement, which was based on first glance. Sorry for having been so superficial.
[EDIT:] I relativize my relativization: The v2 version is a bit better and clearer than the v1 version.

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?
User avatar
Ragnar
Posts: 239
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

26 Jun 2019, 04:19

I implemented your suggestions.
autocart wrote: 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?
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
Posts: 148
Joined: 12 May 2014, 07:42

Re: Suggestions on documentation improvements

26 Jun 2019, 04:38

Ragnar wrote:
26 Jun 2019, 04:19
I implemented your suggestions.
...
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.
1) I am glad I could contribute.
2) 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.)
joefiesta
Posts: 264
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

GUI SUBMIT

01 Jul 2019, 10:22

GUI SUBMIT doc states:
Submit

Saves the contents of each control to its associated variable (if any) and hides the window unless the NoHide option is present.
This is not exact. It should read:
Saves the contents of each INPUT-CAPABLE control ...
It omits the proviso (stated at "associated output variable"):
Note: Gui Submit does not change the contents of variables of non-input-capable controls (such as Text and GroupBox), nor certain others as documented in their sections (such as ListView and TreeView
joefiesta
Posts: 264
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Empty arrays

02 Jul 2019, 10:37

at https://www.autohotkey.com/docs/Objects.htm#Usage is shown the syntax for creating an array:
Create an array:

Array := [Item1, Item2, ..., ItemN]
Array := Array(Item1, Item2, ..., ItemN)
Looking at this, it is not clearly evident that

Array := []

is valid syntax and is how one creates an empty array. Yes, this syntax is shown, but in an example and elsewhere (at https://www.autohotkey.com/docs/misc/Arrays.htm ).
wolf_II
Posts: 2678
Joined: 08 Feb 2015, 20:55

Re: Suggestions on documentation improvements

03 Jul 2019, 13:07

objects wrote:In AutoHotkey v1.x, simple arrays and associative arrays are the same thing. However, treating [] as a simple linear array helps to keep its role clear, and improves the chance of your script working with a future version of AutoHotkey, which might differentiate between simple arrays and associative arrays.
Suggested improvement: clarify version to use correct version number
objects wrote:In AutoHotkey v1.1+, simple arrays and associative arrays are the same thing. However, treating [] as a simple linear array helps to keep its role clear, and improves the chance of your script working with a future version of AutoHotkey, which might differentiate between simple arrays and associative arrays.
see here.

Return to “Wish List”

Who is online

Users browsing this forum: No registered users and 7 guests