Suggestions on documentation improvements

Propose new features and changes
User avatar
jeeswg
Posts: 5442
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

19 Feb 2018, 17:19

- It appears that the online documentation is preventing Alt+Left/Alt+Right from working on Internet Explorer.
- I often do 'Google search, click, find, copy, back (alt+left)' in quick succession.
- Workaround:

Code: Select all

;WBGet function - AutoHotkey Community
;https://autohotkey.com/boards/viewtopic.php?f=6&t=39869

#IfWinActive, ahk_class IEFrame ;internet explorer
!Left:: ;Internet Explorer - navigate back to previous item (equivalent to Alt+Left)
WinGet, hWnd, ID, A
oWB := WBGet("ahk_id " hWnd)
try oWB.GoBack()
oWB := ""
return

!Right:: ;Internet Explorer - navigate forward to next item (equivalent to Alt+Right)
WinGet, hWnd, ID, A
oWB := WBGet("ahk_id " hWnd)
try oWB.GoForward()
oWB := ""
return
#IfWinActive
- Syntax html elements:
MouseGetPos: the comma should be after the square bracket.
WinSet, Attribute: extra spaces.

- @joefiesta: This might be useful: [EDIT: for Internet Explorer and AutoHotkey Help (HTML Help)]
Internet Explorer get/set zoom/text size - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 74#p165674

- @Ragnar: Many thanks for the case corrections: [EDIT: Many thanks also for the new 'deprecated' warnings.]
Fix case · Lexikos/AutoHotkey_L-Docs@006d88f · GitHub
https://github.com/Lexikos/AutoHotkey_L ... 3496be2830
- For reference, the Func Object 'Name' property gives a consistent case for built-in functions, so, if people were interested, to change 'lock' to 'Lock' for some functions, would require a source code change.
Func Object
https://autohotkey.com/docs/objects/Func.htm
Last edited by jeeswg on 19 Feb 2018, 18:40, edited 2 times in total.
User avatar
Ragnar
Posts: 204
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

19 Feb 2018, 17:42

jeeswg wrote:It appears that the online documentation is preventing Alt+Left/Alt+Right from working on Internet Explorer.
At the moment, every default Alt+ shortcut is disabled due to my lack of attention :headwall: (I don't use those shortcuts). A fix has already been submitted.
joefiesta
Posts: 197
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

19 Feb 2018, 17:58

@jeeswg - I looked at your code. Thank you for pointing it out. But, what I don't understand (and this is rhetorical) is why do people us IE? As a firefox user, I have no problem with the help online (in regard to the font size). I can easily change the magnification level of any page and the Firefox add Zoom Page WE will remember that setting each time I return to that page. But, I dont' want (1) to have to rely on having online access and (2) prefer the offline version because I can more easily program automation routines for it since it is a standalone process (meaning I don't have to worry about whether it is the active tab in Firefox , in it's own window, what happens to other tabs when I do something etc. etc.).

Secondly, I fail to comprehend how something as straightforward (I would assume) as creating a file for a WINDOWS utility could be so messed up. Are there not guidelines for creating a .CHM file? There are over 500 .chm files on my C drive. Yes, many are trivial.... but, still, I'm sorry, Ahk's is a mess.

Thirdly, I don't want a workaround. I spent well over an hour investigating and documenting the FONT size problem. If no one appreciates that effort, then I will stop wasting my time trying to help improve AHK. All I ask is that someone says "yes, it is broken and we'll fix it" even if it takes 6 months to fix or until the official release of Version2. Just look at how many posts there are in the help forum. Gazillions of them ask the same things over and over again. And gazillions of them are because people can not extract the information they need from the documentation because it is so difficult to find something in it. Hopefully, Version 2 is going to fix much of that, but is that not far off for the average user?

Lastly, I hope I not offending you. I know I can be abrasive sometimes. I appreciate every reponse you make.
User avatar
jeeswg
Posts: 5442
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

19 Feb 2018, 18:37

- The zoom/text size techniques work on Internet Explorer (online) *and* HTML Help (offline).
- @joefiesta: My hunch is that it might be good if you collected your documentation ideas together, a bit like this:
jeeswg's documentation extension tutorial - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=7&t=33596
Ultimately AutoHotkey is just volunteers, and you appear motivated and able on this issue.

- [EDIT:] The AHK v2 documentation has a ComObject page, but the AHK v1 documentation doesn't.
ComObject()
https://lexikos.github.io/v2/docs/comma ... Object.htm

- [EDIT:] The use of ():
[lists Max()/Min() instead of Max/Min]
Alphabetical Function Index
https://lexikos.github.io/v2/docs/commands/index.htm
[title ComObjArray() instead of ComObjArray]
ComObjArray()
https://lexikos.github.io/v2/docs/comma ... jArray.htm
[title ComObject() instead of ComObject]
ComObject()
https://lexikos.github.io/v2/docs/comma ... Object.htm

- [EDIT:] Is this correct? There appears to be a contradiction here, should it be 'between 0 and 100'?
- Also, if this parameter 'can be an expression', then that would suggest that it would incorrectly interpret '+10' as '10', unless there is some special handling for this parameter.
SoundSet
https://autohotkey.com/docs/commands/So ... undSet.htm
Percentage number between -100 and 100 inclusive (it can be a floating point number or expression). If the number begins with a plus or minus sign
- [EDIT:] Btw. Awkward.
AutoHotkey Beginner Tutorial
https://autohotkey.com/docs/Tutorial.htm
Untitled - Notepad (Windows XP/7)
untitled - Paint (Windows XP)
Untitled - Paint (Windows 7)
- It was recently changed to 'Untitled', which makes sense, however, (not that I'm that concerned about it,) possibly mentioning the discrepancy, or using the class instead, or mentioning about case sensitivity, could be a good idea.

- [EDIT:] Something quite important. When I do innerText on a syntax box ('pre' element) e.g. WinGetPos, the square brackets are removed. Is there any obvious reason for this? It's important because that's how I keep my syntax lists up-to-date, and also, that information is then lost in my txt version of the AutoHotkey help. Thanks.
offtopic
joefiesta
Posts: 197
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

27 Feb 2018, 11:42

A_args and "READ/WRITE"

You new doc on A_args is rather nice. However, one point of inconsistency was introduced with it.

A_args is shown as "READ/WRITE". The older read/write builtins are not. (Clipboard and ErrorLevel)
User avatar
Ragnar
Posts: 204
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

28 Feb 2018, 07:59

jeeswg wrote:The use of ()
See PR #243.
jeeswg wrote:SoundSet: There appears to be a contradiction here, should it be 'between 0 and 100'?
This would incorrectly mean that no negative values are allowed. If that were the case, how else do you want to subtract a specific value from the current volume?
jeeswg wrote:SoundSet: Also, if this parameter 'can be an expression', then that would suggest that it would incorrectly interpret '+10' as '10', unless there is some special handling for this parameter.
The next sentences basically imply that you must specify a plus sign if you want to add a value, regardless of whether the parameter is an expression or not. So what's wrong with this?
jeeswg wrote:Tutorial: It was recently changed to 'Untitled', which makes sense, however, (not that I'm that concerned about it,) possibly mentioning the discrepancy, or using the class instead, or mentioning about case sensitivity, could be a good idea.
A tutorial does not have to address every aspect. If you want more details, go to the corresponding command page.
jeeswg wrote:When I do innerText on a syntax box ('pre' element) e.g. WinGetPos, the square brackets are removed. Is there any obvious reason for this?
They are span elements now. innerText ignores HTML elements (for example, you can use innerHTML instead and regexreplace them). I suppose Lexikos wanted to make the syntax more readable and simplify copy-and-paste (because you don't have to remove the square brackets manually anymore).
joefiesta wrote:A_args is shown as "READ/WRITE". The older read/write builtins are not. (Clipboard and ErrorLevel)
See PR #244.
User avatar
jeeswg
Posts: 5442
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

28 Feb 2018, 10:19

Thanks Ragnar.
Percentage number between -100 and 100 inclusive (it can be a floating point number or expression). If the number begins with a plus or minus sign, the current setting will be adjusted up or down by the indicated amount. Otherwise, the setting will be set explicitly to the level indicated by NewSetting.
- Don't worry, I felt that it would make more sense as '0 to 100'. Whether changed or kept as it is, either way it's a bit counterintuitive.
- AFAIK for a normal 'can be an expression' parameter, '+10' would become '10'. Anyhow, this affects my converter and I'll mention it in the AHK v2 forum instead. It's a reason why an official list of all commands and their parameter types (input/output/can be an expression/normal/nonstandard) would be useful. This is one of the very few 'nonstandard' parameters I've come across, they're hard to spot, so I'll have to put a request out for people to point them out to me. I'll start a new thread myself based on this:
Scintillua-ahk/ahk1.lua at master · Lexikos/Scintillua-ahk · GitHub
https://github.com/Lexikos/Scintillua-a ... r/ahk1.lua

- Re. syntax boxes, thanks for the explanation and workaround re. the appearance/copy-and-paste discrepancy.
- Interestingly, IE retains the square brackets, Firefox/Chrome don't, when you copy and paste.

- Btw joefiesta mentioned this before, perhaps 'True' and 'False' could be added to the 'Misc' list for clarity (even though they're mentioned elsewhere):
Variables and Expressions
https://autohotkey.com/docs/Variables.htm#Misc
joefiesta
Posts: 197
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

01 Mar 2018, 13:06

The new help for 1.1.28.00 - Top tabs

The tab bar at the top of the 1.1.28.00 Help is now bigger than it was in 1.1.27. (It is taller.)

I suspect this was accidental, especially since it is now unnecessarily large.

Make me sad. I programmed hotkeys to click the buttons and I have to change my program. (Yes, it does take less time than writing this.) This is because I have to hardcode where to click. ahhhh.... (But, please, change it back or keep it the same! I don't want to have to reprogram some hotkeys every new version.)
joefiesta
Posts: 197
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

01 Mar 2018, 13:21

Offline HELP - Shortcut Keys

The VIEW shortcut keys are for Contents, Index, Search and Favorites.
I don't think there is any reason for favorites. It uses ALT + I. ALT + I would be much more logical for the INDEX.
joefiesta
Posts: 197
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

07 Mar 2018, 10:19

WINGET() and references to Win Title

The Winget() command doc says it returns the "unique Id (HWND)". That is a link to what would presume is a definition of "unique ID (HWND). But, it is not. It links to WINGET, which doesn't define "unique ID (HWND)" or describe it's usage.

I believe all references to "unique ID (HWND" (and there are surely very many) should point to the "WINTITLE" section. There "unique ID (HWND)" is CLEARLY DEFINED and it's usage (specifcally along with "ahk_id") is also CLEARLY DEFINED.

(Personally I can never remember the differnce between ID and PID. Why is ID not UID and "ahk_uid"? That woud make the two consistent in regard to the "ahk_id" and "ahk_pid" parameters. Then there is also the "Ahk_PID" issue, if we go on. It's not really an AHK id at all. It is a WINDOWS process id. But, now I'm probably gong too far now.)
joefiesta
Posts: 197
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

07 Mar 2018, 12:46

Directives - Force vs. Restart

1. It would be nice if there was an entry in the doc that describes directives. (If there is, I can't find it.) I was particularly perplexed when my script which included "#SingleInstance, Off" as the first line did not display that line in LISTLINES. (The doc mentioned #SingleInstance is ignored if a command line parameter is passed, but could also mention it is not displayed in LISTLINES or show it as **IGNORED** or something.)

2. The FORCE and RESTART directives are mutually exclusive, unless I am misunderstanding something. For most languages I have encountered, when multiple mutually exclusive options are specified for a command, the one specified LAST is used. (Basically, this makes parsing much easier,etc.) However, it appears that that is not the case for AHK.

Specifying "/F /RESTART" has the same effect as "/RESTART /F". The effect is that /RESTART takes precedence and /FORCE is, effectively, ignored. (So, then you could say they are not mutually exclusive. Their definitions, however, imply they are.)

a. It would be nice if this behavior was documented, or

b. they were considered mutally exclusive and parsed accordingly.

(I say all this because I run REXX language scripts to create my AHK commands on the fly,etc. etc. but that really doesn't matter.)
User avatar
jeeswg
Posts: 5442
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

07 Mar 2018, 18:52

deprecated commands:
- I would remove the 'deprecated' notice from FileGetAttrib.
- Potentially, I might add deprecated notices to: #CommentFlag, #EscapeChar, GetKeyState command, #IfWinXXX.
- There are further low-priority candidates here: 'COMMANDS ETC WHICH CAN BE DISCARDED IN AUTOHOTKEY V1':
AHK v1 to AHK v2 conversion tips/changes summary - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 37&t=36787
- Note: If DateAdd/DateDiff were backported to AHK v1, it would simplify the narrative, EnvAdd/EnvSub could be described as deprecated. Perhaps something can be done for IfMsgBox. (Note: I would recommend a Format:="yyyyMMddHHmmss" parameter for DateAdd.)
User avatar
Ragnar
Posts: 204
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

09 Mar 2018, 10:54

joefiesta wrote:The new help for 1.1.28.00 - Top tabs

The tab bar at the top of the 1.1.28.00 Help is now bigger than it was in 1.1.27. (It is taller.)

I suspect this was accidental, especially since it is now unnecessarily large.

Make me sad. I programmed hotkeys to click the buttons and I have to change my program. ...
This is a side effect of the change to display CHM help correctly with other DPI settings. Soon there will be a way to specify various settings (content font size, selected tab, sidebar visibility) the help should be started with by default. Be patient.
joefiesta wrote:Offline HELP - Shortcut Keys

The VIEW shortcut keys are for Contents, Index, Search and Favorites.
I don't think there is any reason for favorites. It uses ALT + I. ALT + I would be much more logical for the INDEX.
Yes, more logical but not in line with the predefined CHM hotkeys. Some older scripts rely on ALT+N to open the index tab.
joefiesta wrote:WINGET() and references to Win Title

The Winget() command doc says it returns the "unique Id (HWND)". That is a link to what would presume is a definition of "unique ID (HWND). But, it is not. It links to WINGET, which doesn't define "unique ID (HWND)" or describe it's usage.

I believe all references to "unique ID (HWND" (and there are surely very many) should point to the "WINTITLE" section. There "unique ID (HWND)" is CLEARLY DEFINED and it's usage (specifcally along with "ahk_id") is also CLEARLY DEFINED.
Next time, please be more specific, where do you found such issues (for example, link to them as far as possible via URL tag). See PR #246.
joefiesta wrote:Directives - Force vs. Restart
Sounds like this issue would be more suitable for "Ask For Help" or "Bug Reports". I have no idea if it's meant to be like this.
jeeswg wrote:deprecated commands:
Such notes are only given entities which have a better alternative within v1. v2 has its own docs. The entities you proposed have neither an alternative nor a better one. Why for example #If WinXXX() is not always better than #IfWinXXX, see Lexikos' explanations in the merged PR#228.
User avatar
jeeswg
Posts: 5442
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

09 Mar 2018, 12:51

- @joefiesta: Other chm files, chm files in general, use Alt+N for index, and Alt+I for Favorites. Although AutoHotkey can be used to 'fix' this, if undesirable.

- @Ragnar: My suggestions re. the 'deprecated' notices were to avoid people having to do complex manual replacements in their scripts, when converting from AHK v1 to AHK v2.
- FileGetAttrib and FileExist both exist in both AHK v1 and AHK v2. By that logic FileGetAttrib is not deprecated.
- The GetKeyState command has a better alternative in AHK v1, the GetKeyState function. (Similar logic to StringReplace v. StrReplace.)
- #CommentFlag and #EscapeChar are not available in AHK v2, and are the ultimate in awkward-to-convert. I would strongly advise users of AHK v1 not to use these directives. So if not 'deprecated', perhaps a comment re. future script compatibility would be best.
- You are correct about #IfWinXXX v. #If, I saw that #If was optimised in AHK v2, so if it is optimised in AHK v1, that would be the right time to add the notice. Many thanks for the link.
- I am particularly concerned to let people know that using FileGetAttrib is OK going forward, and to avoid using #CommentFlag or #EscapeChar. Cheers.

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

YWeek/A_YWeek. Where Monday is defined as the first day of the week.
FormatTime
https://autohotkey.com/docs/commands/FormatTime.htm
Variables and Expressions
https://autohotkey.com/docs/Variables.htm

'Contains 1 and 0'. Should be 'Contain'.
Variables and Expressions
https://autohotkey.com/docs/Variables.htm

[EDIT:] The Sort page should give a warning about stable sort/unstable sort. This issue can corrupt user data. Perhaps almost all users would expect stable sort to be the default, that when two items are considered equal, the item that was earlier in the input list will be earlier in the output list.
Sort
https://autohotkey.com/docs/commands/Sort.htm
See example note and scripts here:
jeeswg's documentation extension tutorial - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=7&t=33596
User avatar
tidbit
Posts: 1094
Joined: 29 Sep 2013, 17:15
Location: USA

Re: Suggestions on documentation improvements

21 Mar 2018, 17:27

any reason the chm was changed in 1.28? Is it easier to maintain? if not, why fix what aint broke?
it's messing with my editor. in my editor, I could just press F1 and it'd open ahk's docs to either the selection or a dead page if no selection. Now with the new one, I just get a blank page, can't even see the sidebar to manually navigate, requires me to close it.
Image

some links also don't work (seems to be all functions? could just be my editor. commands and variables work fine).
Image
rawr. fear me.
*poke*
Is it December 21, 2012 yet?
User avatar
Exaskryz
Posts: 2876
Joined: 17 Oct 2015, 20:28

Re: Suggestions on documentation improvements

21 Mar 2018, 18:29

New .chm has given me troubles. Super slow to respond when clicking in the search box; nevermind that it does not default to the Search tab any longer. I'm not a fan of it even after a month trying to get used to it.
User avatar
joedf
Posts: 6693
Joined: 29 Sep 2013, 17:08
Facebook: J0EDF
Google: +joedf
GitHub: joedf
Location: Canada, Quebec
Contact:

Re: Suggestions on documentation improvements

22 Mar 2018, 14:00

What editor is that? :o
Image Image Image Image Image
Windows 10 x64 Professional, Intel i5-8500 @ 3.00 GHz, 16GB DDR4 3200 MHz, NVIDIA GTX 1060 6GB | [About Me] | [ASPDM - StdLib Distribution]
[Populate the AHK MiniCity!] | [Qonsole - Quake-like console emulator] | [LibCon - Autohotkey Console Library] | [About the AHK Foundation]
User avatar
jeeswg
Posts: 5442
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

22 Mar 2018, 14:17

Maybe the best approach would be to go back to the old-style chm file, but make available useful scripts to replicate any new functionality. It seems that everyone was happy with the old-style chm. Plus 'if it ain't broke, don't fix it', is a key argument for sticking with the old-style chm. Also, there is no reason why we can't have *BOTH*, but with the new-style chm as an alternative, and the old-style chm as the default.
User avatar
tidbit
Posts: 1094
Joined: 29 Sep 2013, 17:15
Location: USA

Re: Suggestions on documentation improvements

22 Mar 2018, 14:46

Joe: everedit. costs $$$. I no longer recommend it. new releases are super buggy and development has basically died.

jeeswg: 'both' is more effort for the only ahk dev. 1 would probably be best. If someone, like you, feels like creating the 'new & buggy' one AND maintaining it with every release, go ahead. I don't think Lex (or whoever manages the docs) needs any more work than he has. plus bundling 2 chms would be confusing.

if the new one is much easier to manage (not sure how much work updating the chm is), keep it. But don't ignore all the issues people are having, make it work as expected.
rawr. fear me.
*poke*
Is it December 21, 2012 yet?
User avatar
jeeswg
Posts: 5442
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

22 Mar 2018, 15:13

- @tidbit: I was always very happy with the old-style chm, I was unsettled when I saw that it had changed, but thought that I would give it a chance.
- Also, I had already developed various scripts to give me additional functionality for the old-style chm and other non-AutoHotkey chm files.
- I stated above that there should be one help file bundled with AutoHotkey. The old-style one. One thing I like about AutoHotkey and the old-style help is the aim of simplicity, of not being needlessly complex.
- I welcome the new-style one as an interesting experiment. It could have its own thread. It's interesting to see the power and capabilities of a custom chm file.
- For me the most important thing would be to share information/tips on creating the old-style/new-style chm files.

Return to “Wish List”

Who is online

Users browsing this forum: No registered users and 8 guests