[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
JDN
Posts: 9
Joined: 09 May 2018, 01:33

Re: Suggestions on documentation improvements

19 May 2018, 10:16

As Lexicos pointed out in the following thread:

https://autohotkey.com/boards/viewtopic.php?f=5&t=49224

I was mistaken in posting that you can remove the Hidden attribute from the C:\ProgramData folder by using the Folder Options from Windows Explorer or the Control Panel. It enables one to see that folder when using Windows Explorer but it does not change the Hidden Status.

I had spent several hours trying to update my Startup folder and was only able to do it when I discovered that freeware Startup utility. I guess I was very tired and got confused.

I want to thank Lexicos for correcting my errors.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

WORD WRAP in GUI TEXT control

29 May 2018, 08:19

I would like to see the documentation for GUI, ADD, TEXT include the following:

When automatic word-wrapping is enable in a TEXT control, any words which by necessity would need to be split (at the end of a row) are, instead, truncated.

(or, of course, some similar language)

Thank you

Joe Petree
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

what does "=" do?

01 Jun 2018, 15:03

At the documentation for OPERATORS In EXPRESSIONS (part of VARIABLES AND EXPRESSIONS), =, while it is shown, IS NOT DEFINED. There the doc states:
Equal (=), case-sensitive-equal (==), and not-equal (<> or !=). The operators != and <> are identical in function. The == operator behaves identically to = except when either of the inputs is not a number, in which case == is always case sensitive and = is always case insensitive (the method of insensitivity depends on StringCaseSense). By contrast, <> and != obey StringCaseSense.
This does not say what = does. I find this especially confusing since = can also be used for assignment.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

What is a PARENT window?

02 Jun 2018, 13:21

The documentation for +PARENT (found in the GUI topic) says the following:
Parent [v1.1.03+]: Use +Parent immediately followed by the name or number of an existing Gui or the HWND of any window or control to use it as the parent of this window. To convert the Gui back into a top-level window, use -Parent. This option works even after the window is created.
That is all it says. This does not tell me what a PARENT gui is or does.
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: What is a PARENT window?

02 Jun 2018, 17:01

joefiesta wrote:The documentation for +PARENT (found in the GUI topic) says the following:
Parent [v1.1.03+]: Use +Parent immediately followed by the name or number of an existing Gui or the HWND of any window or control to use it as the parent of this window. To convert the Gui back into a top-level window, use -Parent. This option works even after the window is created.
That is all it says. This does not tell me what a PARENT gui is or does.
using the option implies prior awareness of the window creation hierarchy. i dont think it should be explained here, really. i dont think it even could be, without introducing bloat that is. maybe link to https://msdn.microsoft.com/en-us/librar ... S.85).aspx for those wanting to dig deeper, but a downside to that is that u never know when MS will 404 it
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

05 Jun 2018, 00:01

SORT
- This quote from the Sort command page has caused me a lot of confusion.
When the function deems the first parameter to be greater than the second, it should return a positive integer
- I might suggest something like:
When the function deems that the first parameter should be placed later in the final/sorted list than the second, it should return a positive integer
- Also, the page does not warn about stable v. unstable sort, which again caused much confusion for me.
- I've collected a list of rules of useful info for custom sort functions, here (including comments on stable v. unstable sort):
Numerically AND Alphabetically sorting data - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 83#p222183

FORMAT
- The Format function page could do with some more examples. I've collected some here:
jeeswg's characters tutorial - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=7&t=26486
- One tricky thing to do is to produce a number of the form '6.6' e.g. 000123.456000 or -000123.456000.

REGEX QUICK REFERENCE
The AHK v2 version of this AHK v1 page:
Regular Expressions (RegEx) - Quick Reference
https://autohotkey.com/docs/misc/RegEx-QuickRef.htm
mentions these: LS/line separator/chr(0x2028) and PS/paragraph separator/chr(0x2029), which I believe are applicable to AHK v1 also, but not mentioned. Also, the AHK v1 page does not mention the O (object) mode.

INPUTBOX
InputBox
https://autohotkey.com/docs/commands/InputBox.htm
Default values of W375 H189 are mentioned.
On Windows 7 I get: W384 H204 (window), and W368 H166 (client).
What do the numbers refer to?

GUI (AHK V2)
This page lacks a Related Pages section at the bottom:
GuiControl Object
https://lexikos.github.io/v2/docs/objec ... ontrol.htm
E.g. this page does have a Related Pages section:
GUI Control Types
https://lexikos.github.io/v2/docs/comma ... ntrols.htm
Perhaps all pages could consistently use 'Related' or 'Related Pages'. 'Related Pages' would be better because you could skip to it directly by doing Ctrl+F, 'Related P', whereas 'Related' could appear in the document in other places.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

GUI shortcut keys

12 Jun 2018, 09:09

At the doc for GUI, ADD for controltype TEXT the use of a shortcut key (letter preceded by ampersand to indicate keyboard shortcut) in the TEXT parameter is mentioned and a pointer (link) to "shortcut key" at "Keyboard navigation" exists.

However, none of the other GUI ADD control types' documentation includes this (except GUI ADD BUTTON).

This is inconsistent. Each control type that allows a shortcut key should include the reference to a shortcut key.

One should not have to read about GUI ADD TEXT to learn about GUI ADD CHECKBOX etc. If information of a general or all-inclusive nature is to be included for individual control types, I believe it should PRECEDE all the specific information.

( the shortcut key is also valid for CHECKBOX and BUTTON. There may be others.)
User avatar
hoppfrosch
Posts: 443
Joined: 07 Oct 2013, 04:05
Location: Rhine-Maine-Area, Hesse, Germany
Contact:

V2-Docu: FileCreateDir is missing

18 Jun 2018, 02:30

Within V2-Documentation, the command "FileCreateDir" is undocumented. The command is still referenced on page "Script Compatibility".

The command "FileCreateDir" seems to be replaced with "DirCreate" - nevertheless the command is still available in V2
Helgef
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: Suggestions on documentation improvements

18 Jun 2018, 03:39

nevertheless the command is still available in V2
I get call to non-existent function,

Code: Select all

filecreatedir "a"
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

18 Jun 2018, 05:30

@hoppfrosch: Which version of AHK v2 are you using? I tried FileCreateDir as a command and function in AHK v2.0-a096 and got the same error as Helgef.
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
User avatar
hoppfrosch
Posts: 443
Joined: 07 Oct 2013, 04:05
Location: Rhine-Maine-Area, Hesse, Germany
Contact:

Re: Suggestions on documentation improvements

18 Jun 2018, 06:25

:oops: My fault - just ignore my request
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

SEND and special characters

27 Jun 2018, 11:12

The following sends an "Alt" character:

Code: Select all

send, !
What does the following send?

Code: Select all

	a := "!"
	send, %a%
	
The documentation for SEND does not make the answer to this question at all obvious.
gregster
Posts: 8916
Joined: 30 Sep 2013, 06:48

Re: Suggestions on documentation improvements

27 Jun 2018, 11:19

Why should a:= "!" and Send %a% do anything else than Send ! ? a gets de-referenced like it is customary in Autohotkey. Does it have to be mentioned when it works as expected?

Although, without a following key it doesn't do anything, anyway... in any case. But this is consistent, imho.
The modifiers !+^# affect only the very next key. To send the corresponding modifier key on its own, enclose the key name in braces.
Hence, the modifier ! only makes sense, if there is something to modify. And to send a literal !, brackets, raw and text mode are available. Putting a string into a variable is obviously different.

Edited
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Overlapping GUI controls and G-labels

03 Jul 2018, 10:12

Apparently, the sequence in which GUI controls are created is relevant. I can not find this documented anywhere.

Specifically, it appears that when two controls with g-labels are created and they overlap (partially or fully), when clicking a location where they overlap, the G-label of the first created control is triggered.

The only way I have found to make the second created control's G-label to be triggered in this case is by HIDING the first created control (which, of course, is not really what one might want).

Here is a short macro which you can use to test this. This sample is not very practical. In reality, my first control is a PICTURE and the second control is TEXT (which only covers a small portion of the picture and is, therefore, much more logical). I haven't used a picture in the sample for lack of a universal picture file.

Pressing BUTTON 2 has no effect until after Clicking TEXT1 control area (which then HIDES TEXT1).

I also find this interesting in that one has every reason to think that the LAST control created over a certain location has the highest priority.

Code: Select all

#SingleInstance, force
   Gui, 1: Add, text, x001 y000 w300 h400    vText1  gText1,  This is TEXT ONE.
   Gui, 1: Add, button, x101 y105   vMsgTxt gButton2 -background, button two.......
   Gui, 1: Show, x0 y0        , TestGuisOverlapping
   return

Text1:
   msgbox text1 routine
   GuiControl, 1: hide, Text1
   return

Button2:
  msgbox button2 routine
  return
iPhilip
Posts: 796
Joined: 02 Oct 2013, 12:21

Re: Overlapping GUI controls and G-labels

03 Jul 2018, 18:49

joefiesta wrote:Apparently, the sequence in which GUI controls are created is relevant. I can not find this documented anywhere.

Specifically, it appears that when two controls with g-labels are created and they overlap (partially or fully), when clicking a location where they overlap, the G-label of the first created control is triggered.

The only way I have found to make the second created control's G-label to be triggered in this case is by HIDING the first created control (which, of course, is not really what one might want).

Here is a short macro which you can use to test this. This sample is not very practical. In reality, my first control is a PICTURE and the second control is TEXT (which only covers a small portion of the picture and is, therefore, much more logical). I haven't used a picture in the sample for lack of a universal picture file.

Pressing BUTTON 2 has no effect until after Clicking TEXT1 control area (which then HIDES TEXT1).

I also find this interesting in that one has every reason to think that the LAST control created over a certain location has the highest priority.

Code: Select all

#SingleInstance, force
   Gui, 1: Add, text, x001 y000 w300 h400    vText1  gText1,  This is TEXT ONE.
   Gui, 1: Add, button, x101 y105   vMsgTxt gButton2 -background, button two.......
   Gui, 1: Show, x0 y0        , TestGuisOverlapping
   return

Text1:
   msgbox text1 routine
   GuiControl, 1: hide, Text1
   return

Button2:
  msgbox button2 routine
  return
Hi Joe,

I would consider what you described a bug. You might consider posting the issue in that forum.

- iPhilip
Windows 10 Pro (64 bit) - AutoHotkey v2.0+ (Unicode 64-bit)
Helgef
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: Suggestions on documentation improvements

04 Jul 2018, 00:34

I also find this interesting in that one has every reason to think that the LAST control created over a certain location has the highest priority.
Why? As you said,
I can not find this documented anywhere.
User avatar
CerpinTaxt
Posts: 13
Joined: 23 Dec 2017, 12:16

Re: Suggestions on documentation improvements

17 Jul 2018, 04:40

Ambiguous phrasing in Library list on Functions page

Reference: https://autohotkey.com/docs/Functions.htm#lib

The list of libraries has:

Code: Select all

%A_ScriptDir%\Lib\  ; Local library - requires [v1.0.90+].
%A_MyDocuments%\AutoHotkey\Lib\  ; User library.
path-to-the-currently-running-AutoHotkey.exe\Lib\  ; Standard library.
but shouldn't that third line be something like:

Code: Select all

directory-of-the-currently-running-AutoHotkey.exe\Lib\`  ; Standard library.
or even:

Code: Select all

% StrReplace(A_AhkPath, "AutoHotkey.exe", "Lib\") ; Standard library
Also, maybe consider adding a sentence to the Objects page or the For-Loop page mentioning that a For-Loop enumerates an object alphabetically? I'm sure it's intuitive/obvious for most folks, especially those with prior programming experience, but I didn't realize that until just now and I've been learning AutoHotkey for a decent amount of time.
Image
and with just one faint glance back into the sea
the mollusk lingers with its wandering eye
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

29 Jul 2018, 16:23

The spaces and hyphens are inconsistent here. Thanks.
FormatTime - Syntax & Usage | AutoHotkey
https://autohotkey.com/docs/commands/Fo ... _sensitive
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
User avatar
Ragnar
Posts: 611
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

30 Jul 2018, 03:34

@jeeswg

I wonder why you (and most other people interested in programming) don't change such simple and obvious issues by yourself? It'll only take five minutes. No more. Just press the pen button on the page of your choice, do your changes and follow the instructions on the screen. Much knowledge of Git or HTML is not required. The only "disadvantage" is of course that you have to register first. There are many instructions on the Internet how you do this such as https://help.github.com/articles/editin ... epository/.

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 4 guests