Suggestions on documentation improvements

Propose new features and changes
Osprey
Posts: 294
Joined: 18 Nov 2017, 05:50

Re: Suggestions on documentation improvements

11 Dec 2017, 16:09

Hi. I think that the documentation could do a better job of helping users with arrays. Under Arrays, the topic that anyone looking to use arrays would find first, there's no basic usage information. It just gives a one liner with a link to Object() and then jumps into "advanced" examples of using arrays in loops. The link to Object() does give basic array usage information, exactly what all new array users would be looking for, but it's not clear that better, basic information is available at that link, nor is it intuitive. I think that it would be really helpful if that were more clear (like "For basic array usage info, see Object()"). Ideally, though, I think that the Arrays topic should contain that information and display the "Simple Arrays" and "Associative Arrays" sections of the Object topic, itself, rather than redirect to them. That would make things much easier and clearer for users, especially new users.

Thanks for listening and understanding.
User avatar
Ragnar
Posts: 194
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

13 Dec 2017, 10:13

I've revised this page. Maybe it's a little clearer now. See GitHub pull request #218.
User avatar
joedf
Posts: 6434
Joined: 29 Sep 2013, 17:08
Facebook: J0EDF
Google: +joedf
GitHub: joedf
Location: Canada, Quebec
Contact:

Re: Suggestions on documentation improvements

14 Dec 2017, 11:19

@Ragnar
What do you think of adding this, so the hiding of the menu doesn't seem to sudden/rough?
.h-tabs, #left {transition: width 0.4s ease 0s;}
User avatar
jeeswg
Posts: 4965
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

14 Dec 2017, 12:51

Just to let you know, I believe that Ctrl+F to find/focus text on Internet Explorer 11 (Windows 7) is not working on the AHK v1/v2 documentation pages. (It's working on Firefox and Chrome.)

[EDIT:] The find box appears fine, but when I press enter, no text is found/focused. I then try the same thing on another tab, e.g. this forum, and it works fine.
Last edited by jeeswg on 14 Dec 2017, 13:33, edited 1 time in total.
joefiesta
Posts: 153
Joined: 24 Jan 2016, 13:54

Re: Suggestions on documentation improvements

14 Dec 2017, 13:05

I don't normally use IE. So, I tried since I have IE 11 on Win7 Pro. I should also add that my IE 11 is almost entirely vanilla.

What I found is: CTRL + F works fine for me. That it, it brings up the search box.

What seems to be erratic is the searching process itself. Sometimes it finds things and sometimes it doesn't. I didn't play with it that long so I didn't come up why it's erratic or when.
User avatar
Ragnar
Posts: 194
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

15 Dec 2017, 06:38

joedf wrote:What do you think of adding this, so the hiding of the menu doesn't seem to sudden/rough?

Unfortunately not a good idea at the moment. If you have hidden the sidebar, you will see the transition effect every time you open a new page, which is quite annoying. Furthermore, the effect in Chrome is quite laggy. In order for all this to work smoothly, more needs to be done than just this line.

jeeswg wrote:Just to let you know, I believe that Ctrl+F to find/focus text on Internet Explorer 11 (Windows 7) is not working on the AHK v1/v2 documentation pages.

This also applies to Edge. The reason for this is the change I introduced: Exclude sidebar content when searching via Ctrl+F. Unfortunately, the search feature of IE/Edge cannot handle this correctly. I've "reversed" this change specifically for IE/Edge; see GitHub pull request #218.
User avatar
joedf
Posts: 6434
Joined: 29 Sep 2013, 17:08
Facebook: J0EDF
Google: +joedf
GitHub: joedf
Location: Canada, Quebec
Contact:

Re: Suggestions on documentation improvements

15 Dec 2017, 09:30

I see. Custom Js implementation then...
User avatar
jeeswg
Posts: 4965
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

21 Dec 2017, 12:21

CTRL+F

(Btw this is still not working on the AHK v1/v2 documentation.)
(Fixing the AHK v2 index is my main concern, because I can use Google for the AHK v1 documentation.)

==================================================

DEPRECATED COMMANDS

I would strongly suggest to make clear deprecated v. preferred functions/commands:
- Discourage the use of StringReplace/StringSplit/StringGetPos/SetFormat(/RegExMatch variable mode).
- Encourage the use of StrReplace/StrSplit/InStr/Format(/RegExMatch object mode).

E.g. of stating that something is deprecated:
Object
https://autohotkey.com/docs/objects/Object.htm#Insert

I.e. anything that is difficult to convert to AHK v2, that already has a better alternative in AHK v1. Other examples would be the IfXXX commands.

AHK v1 to AHK v2 conversion tips/changes summary - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=37&t=36787

==================================================

A PAGE(/TEXT FILES) CONTAINING KEY TERMS

Potential sources:

list of every command/function/variable from across all versions - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=7&t=27321&p=131642#p131642

Index of /download/1.0
https://autohotkey.com/download/1.0/
AutoHotkey104805.zip\Extras\Editors\Syntax
CommandNames.txt -> control flow statement/command/directive names
Functions.txt -> function names
Variables.txt -> variable names

Note: errors in Variables.txt:
A_ISAdmin -> A_IsAdmin
A_MDAY -> A_MDay
A_YEAR -> A_Year

Note: There may be listview and treeview functions in AHK v2 not yet listed in the AHK v2 documentation functions index (or in my list).

I would recommend to list command/function *names* only, and not lists of parameters, until AHK v2 is nearer completion.

==================================================

CAPITALISATION OF 'LOCK'

It gets confusing to remember whether something is 'Lock' or 'lock'.

SetCapsLockState
SetNumLockState
SetScrollLockState
SetStoreCapslockMode [e.g. make it: 'CapsLock']
A_StoreCapslockMode [e.g. make it: 'CapsLock']

Also there are inconsistent references in the documentation to {CapsLock} (preferred) and {Capslock} for example.

This is one reason why I think there should be official list pages/text files. They would state what the standards are, for use with parsers/lexers/script correctors/converters etc.

==================================================

CAPITALISATION OF ' UP}' and ' DOWN}'

{RAlt Up} or {RAlt up}

It would be better if all examples used one or the other. I think '{RAlt Up}' is better, more elegant.

==================================================

Thanks for reading.
User avatar
derz00
Posts: 495
Joined: 02 Feb 2016, 17:54
GitHub: derz00
Location: Middle of the round cube

Re: Suggestions on documentation improvements

21 Dec 2017, 13:56

You're not inferring that AHK is case-sensitive? I hadn't known that. If it isn't, and you're only concerned about a standard, I suppose other things would be more important to standardize--for sure indentation.
try it and see
...
joefiesta
Posts: 153
Joined: 24 Jan 2016, 13:54

Re: Suggestions on documentation improvements

21 Dec 2017, 16:15

VARSETCAPACITY()

As to what this function does, the doc says:

"Enlarges a variable's holding capacity or frees its memory. Normally, this is necessary only for unusual circumstances such as DllCall."

But, it can also CREATE a variable.

It may be argued that this is implied, but I only find the implication after much reading. Specifically, at the definition of "FillByte" parameter the doc says: "This parameter is normally omitted, in which case the memory of the target variable is not initialized ..."

The first thing I want to read about a command or function is what it does. Maybe not all the subtle nuances and intricasies, but what it does. If it's not there, I assume it doesn't do what it doesn't say it does AT THE VERY BEGINNING of its doc.
User avatar
jeeswg
Posts: 4965
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

21 Dec 2017, 19:22

- @derz00: AFAIK most things in AutoHotkey are case insensitive, including variable/function names.
- I can't think of anything more fundamental to any documentation than the index. And part of getting the index is right, is getting the capitalisation right.
- Capitalisation issues re. 'A_' variables, 'Lock', ' Up}/ Down}', UrlDownloadToFile, and Cdecl, for different reasons, have caused me a lot of wasted time. So much so that I decided to finally check the entire documentation, to try and avoid further such issues. Although my script won't spot ' Up}/ Down}'.

- I have provided an example script where I retrieved text from the AHK v1 and v2 documentations, and looked for the inconsistent capitalisation of mixed case words e.g. 'Lock', 'Cdecl', 'Numpad'.
htm to txt, AutoHotkey Help (chm file) to txt - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=26402&p=189959#p189959

- Re. the need for indexes:
- Btw #AllowSameLineComments, #DerefChar and #Delimiter are missing from the AHK v1 index, although they will be removed in AHK v2. [EDIT: #AllowSameLineComments should not be added to the list, it was only for use with AutoIt.]
Spoiler
Last edited by jeeswg on 25 Dec 2017, 20:29, edited 1 time in total.
joefiesta
Posts: 153
Joined: 24 Jan 2016, 13:54

Re: Suggestions on documentation improvements

21 Dec 2017, 21:09

Re capitalization and documentation

Jeeswg has a very good point. The problem is twofold.

1. The documentation does not define the syntax it uses and
2. The systax is not as logical as it could be.

IBM mainframe documentation--most of you will never need to read it--is a thing of beauty and from years of reading it I would like to offer the following suggestions. One point here. With IBM, commands can very often be abbreviated. Commands are written in mixed case, with the minimum abbreviation being all uppercase. So, for example, if the command is STRREPLACE and it may be abbreviated to as short as STRREP, the documentation shows it as STRREPlace. Thus, all commands begin in at least one uppercase letter. AHK doesn't have abbreviations, so we can use case for something different.

1. The command/function name is mixed case and must being with a capitalized letter.
2. Any parameter which must be coded as show must be ALL CAPS
3. use all lower case for parameter "names".
4 use italicized case for parameters that are the name of a variable. (Note sure show this applies to V2. Has it fixed this issue?)

I would actually prefer to see #1 (command/function names) as ALL CAPS, but the above preserves the neatness already extant in AHK doc in that regard (mixed case emphasizing each different subword).

But, this really is only a beginning. The REAL problem is HOW THOROUGHLY COMPLICATED AHK is. There is also the case of when a parameter can be an expression. Is that the same as #4 above?

Let's look at one example, LISTLINES.

The following all work:

; example 1
listlines, ON

;example 2
a := "on"
listlines, %a%

;example 3
a := ""
listlines, %a%

But, what does the doc say?
1. It doesn't tell us the parameters (ON|OFF) can be a variable's value (%var%)
2. It says the parameter must be "blank or omitted" to have listlines show lines executed. But, example 3 shows the parameters can be a variable with a null value. Is that what BLANK means?

For the doc to be clear it must clarify all the above. But, it is ABSURD that it should have to do so by using verbiage when a CLEARLY DEFINED SYNTAX structure would obviate tons of verbosity. Maybe V2 solves--I think it does--the issue of how complicated AHK is. I've written basic, fortran, APL, assembler, COBOL and REXX languages. But, none of these has been so difficult to learn as AHK (basically because it uses a conglomeration of syntaxes taken from here, there and everywhere).
lexikos
Posts: 6129
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: Suggestions on documentation improvements

22 Dec 2017, 16:31

joefiesta wrote:VARSETCAPACITY()
[...]
But, it can also CREATE a variable.
No, it cannot.

Instead of relying on the reader having read what a "variable reference" is, Chris oversimplified and wrote it as "The name of the variable (not in quotes). " But make no mistake, VarSetCapacity takes a variable reference (that's just how you write a variable reference in an expression). The variable always exists before you call VarSetCapacity.
User avatar
jeeswg
Posts: 4965
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

23 Dec 2017, 12:41

- @joefiesta: I like the parameters to be presented as CamelCase, as they are now, because the variable names will be CamelCase in my script. E.g.:
InStr
https://lexikos.github.io/v2/docs/commands/InStr.htm
FoundPos := InStr(Haystack, Needle [, CaseSensitive := false, StartingPos := 1, Occurrence := 1])
- Optional parameters are denoted with square brackets. This does confuse new users, so hopefully (a) the square brackets notation will be explained somewhere obvious/easy to find, (b) there will be good examples showing how to use the function.
- The documentation in AHK v1 will say 'can be an expression' where appropriate, but most/all of the parameter issues are solved by AHK v2.
- Perhaps there is/could be a link that explains all of the key information re. parameters, I will cover it in my beginner tutorial. I think it would be better to have one place, that contains all of the main information re. parameters in commands/functions, than to re-explain it on each command/function page.
- Possibly there could be a link within every syntax box, to tell you more information re. parameters in commands/functions.
- Btw re. txt files/basic pages that list function names/parameters etc, I had thought that something like this should be amongst the text files:
Scintillua-ahk/ahk.lua at master · Lexikos/Scintillua-ahk · GitHub
https://github.com/Lexikos/Scintillua-ahk/blob/master/ahk.lua#L818
With perhaps '...' to indicate an unlimited number of parameters, and square brackets/parentheses to indicate the greatest possible number of optional parameters.
joefiesta
Posts: 153
Joined: 24 Jan 2016, 13:54

Re: Suggestions on documentation improvements

26 Dec 2017, 15:07

lexikos: RE: Varsetcapacity

I don't understand. You say Varsetcapacity does not create a variable. Then, can you please explain what is happening in the following script. It certainly appears to me that the variable BIN is being created by varsetcapacity.



As this shows, bin is 16 bytes of 0x44. (of course, 0x44 = 68 decimal.)

I CERTAINLY HOPE that you will not suggest that ALL VARIABLES start with an implicit null value (which, of course, they do) AND that varsetcapacity is simply modifying that null value. That would mean A := "abc" does not create a variable. That would be hard to swallow.

I guess this is going to end up be a matter of semantics. I am under the impression that AHK is a interpreted language--essentially because it is not compiled (of course, that excludes compiled scripts). And so, if we put a MSGBOX after varsetcapacity, let's see. The point of interest is opening the script at that point and looking at the VARIABLES AND THEIR CONTENTS. Interestingly "c" is shown, with, as we would expect a null value. But, if AHK is an interpeted language, why does "c" exist at that point? hmmmmm.

I went to Wikipedia for a definition of an interpeter. I was surprised to learn there are various "degrees" of interpreting:
An interpreter generally uses one of the following strategies for program execution:

parse the source code and perform its behavior directly;
translate source code into some efficient intermediate representation and immediately execute this;
explicitly execute stored precompiled code made by a compiler which is part of the interpreter system.


I guess AHK, when running non-compiled code, is like case 2. so, he's adding Bin and C to a symbol table or something. But, that leaves us at the beginning, which would mean, IN A SENSE, NO VARIABLES are created by ANY commands.
lexikos
Posts: 6129
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: Suggestions on documentation improvements

26 Dec 2017, 20:30

Don't belittle semantics. If you aren't using correct semantics, the words you write have the wrong meaning. "VarSetCapacity also creates variables" is untrue.
Any non-dynamic reference to a variable creates that variable the moment the script launches.
Source: Functions
In AutoHotkey, variables are created simply by using them.
Source: Concepts and Conventions (documentation added in v1.1.27.00)
Except where noted on the functions page, variables are not declared; they come into existence simply by using them (and each variable starts off empty/blank).
Source: Variables and Expressions (v1.0)

Even in VarSetCapacity(%varname%, n), %varname% creates the variable, not VarSetCapacity.

If you write VarSetCapacity(myvar, 0) and myvar has never been assigned a value or passed to VarSetCapacity (with a non-zero capacity), the function has no effect. Why would you want the documentation to say it creates the variable? It simply does not. Did you think that it would fail to work if you haven't already "created" the variable using other means?

Think of it this way: how can you assign to a variable if that variable doesn't exist? At some point before the assignment actually occurs, the variable must implicitly be created. In AutoHotkey, the variable exists because you write it in the code (or as in other languages, because you declare it), not because you assign a value or call VarSetCapacity.
User avatar
nnnik
Posts: 3201
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

27 Dec 2017, 05:35

lexikos wrote:
Any non-dynamic reference to a variable creates that variable the moment the script launches.
Source: Functions
In AutoHotkey, variables are created simply by using them.
Source: Concepts and Conventions (documentation added in v1.1.27.00)
Except where noted on the functions page, variables are not declared; they come into existence simply by using them (and each variable starts off empty/blank).
Source: Variables and Expressions (v1.0)
I always thought of the AutoHotkey helpfile as documentation - seems I was wrong it's a puzzle.
Recommends AHK Studio
joefiesta
Posts: 153
Joined: 24 Jan 2016, 13:54

Re: Suggestions on documentation improvements

28 Dec 2017, 14:24

Lexikos:

After reading your reply, I looked at "concepts and conventions." It contains an HUGE amount of information I HAVE NEVER READ. That is because, "concepts and conventions" is not in the documentation that is included in AHK. It appears (unless I am wrong) that is it ONLY IN THE ONLINE DOCUMENTATION. Additionally, I see the ONLINE documentation is, to a large degree, VERY DIFFERENT in regards to "general" content (as opposed to specifics for commands, functions, etc).

I use the doc in the .CHM file in windows.

This, I now realized is one reason I have ALWAYS had problems understanding AHK. For TEN YEARS now. It's things like this that make the AHK documentation a puzzle, as NNNIK called it
User avatar
derz00
Posts: 495
Joined: 02 Feb 2016, 17:54
GitHub: derz00
Location: Middle of the round cube

Re: Suggestions on documentation improvements

28 Dec 2017, 15:11

It must be your .CHM file is outdated.

Concepts.htm was added in v1.1.27.00 which is only as old as this last Christmas.
try it and see
...

Return to “Wish List”

Who is online

Users browsing this forum: No registered users and 3 guests