[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
joefiesta
Posts: 494
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: 6902
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: 214
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: 214
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

[The extension pdf has been deactivated and can no longer be displayed.]

autocart
Posts: 214
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: 608
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: 214
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: 214
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: 608
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: 214
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: 494
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: 494
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: 2688
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.
User avatar
tidbit
Posts: 1272
Joined: 29 Sep 2013, 17:15
Location: USA

Re: Suggestions on documentation improvements

19 Jul 2019, 18:52

I'm still very unhappy about the chm implemented in 2.7+, it just feels and looks bad, I'm sorry. And the dark theme is just an inverted scheme, text looks so gross.

But something that might help ease the pain:
1) restrict CTRL+F to the page area only. Find a way to exclude it from looking in the sidebar. it gets VERY (very) annoying.
2) set the SEARCH box to have default focus, the old (normal) CHM remembers your last used tab, and if it was Index (or Search), it pre-focused the input field, so you can type ASAP. no clicking/tabbing needed.
rawr. fear me.
*poke*
Is it December 21, 2012 yet?
User avatar
Ragnar
Posts: 608
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

21 Jul 2019, 02:55

Each of your issues has already been fixed (except #1 if you are using WinXP/IE8). Use the latest AutoHotkey version.

If you want the CHM to start with another selected tab, use the help settings by clicking the gear icon on the toolbar.

If you are still not satisfied, there is the possibility to restore the old-style CHM.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

AHK Internal Limits

22 Jul 2019, 09:39

I suspect it is somewhere, but I can't find it in the doc. I would like to know the maximum length of a string. But, what would really be nice is if the documentation had an "Internal Limits" section, detailing ALL the limits imposed by AHK. Things like
1. What is the maximum number of lines in a script?
2. What is the maximum length of a string
3. What is the maximum number of elements in an array?
4. Is there a limit to the size of an array?
5. What is the maximum length of a line in a script?
6. What is the maximum length of a variable name?

Perhaps these limits, when the exist, are not imposed by AHK but, rather, by one's operating system or system hardware configuration. But, even then, it would be nice if a single section addressed them, in one way or another. If that exists, I sure can't find it.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

FUNC()

22 Jul 2019, 10:38

At FUNC() is found:
Func() [v1.1.00+]

Retrieves a reference to the specified function.
FunctionReference := Func(FunctionName)

Parameters

FunctionName

The name of the function whose reference is retrieved. FunctionName must exist explicitly in the script.
Also in the same doc entry is this example:
; Retrieve a reference to the function named "StrLen".
fn := Func("StrLen")

; Display information about the function.
MsgBox % fn.Name "() is " (fn.IsBuiltIn ? "built-in." : "user-defined.")
Nicely, the example (although it looks like 2 separate examples) runs fine. However,
STRLEN is not EXPLICITLY DEFINED in the example. This violates the criteria specified for FUNC() and according to the doc "fn := Func("StrLen")" should return 0. It DOES NOT.
gregster
Posts: 8886
Joined: 30 Sep 2013, 06:48

Re: Suggestions on documentation improvements

22 Jul 2019, 10:48

But does "exist explicitly" mean "explicitily defined"...?
Does "explicitly exist" exclude the docs/built-in functions?
Is "explicitly" clearly defined at all in this context? Or "exist" or "defined"?
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

22 Jul 2019, 10:49

built in functions exist... implicitly, i suppose
FunctionName must be the name of a built-in function or exist explicitly in the script.
?
Helgef
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: Suggestions on documentation improvements

22 Jul 2019, 10:55

You do not have to define any built-in functions, since they are built-in :crazy:. It implies functionname will not be auto-included.

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 9 guests