[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
User avatar
joedf
Posts: 8937
Joined: 29 Sep 2013, 17:08
Location: Canada
Contact:

Re: Suggestions on documentation improvements

22 Mar 2018, 22:29

I feel this conversation would be better voiced on the github issues page
Image Image Image Image Image
Windows 10 x64 Professional, Intel i5-8500, NVIDIA GTX 1060 6GB, 2x16GB Kingston FURY Beast - DDR4 3200 MHz | [About Me] | [About the AHK Foundation] | [Courses on AutoHotkey]
[ASPDM - StdLib Distribution] | [Qonsole - Quake-like console emulator] | [LibCon - Autohotkey Console Library]
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

23 Mar 2018, 14:34

@joedf: I disagree. Many people have voiced issues with the new .CHM. I know I have mentioned many problems it has. Moving the discussion to github would just bury it. I don't understand why reverting to the old .CHM is such a problem. The new .CHM format may offer many benefits, but it simply is too full of bugs. In my opinion: it was poorly tested. The biggest problem may be the stupid MOUSE attached to me pc. One of the biggest reasons I use AHK is to automate things so I DON'T HAVE TO TOUCH THE DAMN MOUSE. I can't automate using the new .CHM to this day.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

23 Mar 2018, 14:40

MSGBOX and MODALITY OPTIONS:

1. What does "system modal" mean? The way I read this option is "always on top". But, the msgbox is NOT always on top when this option is used. I switch applications and it gets buried.
2. What does "task modal" mean? I haven't tried this other than to find out it too is not "always on top".
3. Always-on-top. Wow. this is always on top. But, in that regard, it is NOT LIKE SYSTEM MODAL as the doc says. Yes, it does omit the icon. (what purpose that serves is beyond me. Is that AHK or windows?)

Additionally, googling 'system modal' did not get me very far. But, I shouldn't have to go out to Microsoft to learn how AHK works. (If I do, please point the way with a link.) When I did, it did not get me the answer.
User avatar
nnnik
Posts: 4500
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Suggestions on documentation improvements

24 Mar 2018, 03:55

You have to go to Microsoft to learn how Windows works. AHK is just using the Windows API to run on Windows.
The AHK Help File just shares what Windows shares about it's own API e.g. according to Windows System Modal means that it needs to be responded to first before you can continue with any other application.
If you want details you need to look for it in the Win APi documentation.
Here you can find instructions on how to find what you are looking for
Recommends AHK Studio
User avatar
joedf
Posts: 8937
Joined: 29 Sep 2013, 17:08
Location: Canada
Contact:

Re: Suggestions on documentation improvements

25 Mar 2018, 12:29

joefiesta wrote:@joedf: I disagree. Many people have voiced issues with the new .CHM. I know I have mentioned many problems it has. Moving the discussion to github would just bury it. I don't understand why reverting to the old .CHM is such a problem. The new .CHM format may offer many benefits, but it simply is too full of bugs. In my opinion: it was poorly tested. The biggest problem may be the stupid MOUSE attached to me pc. One of the biggest reasons I use AHK is to automate things so I DON'T HAVE TO TOUCH THE DAMN MOUSE. I can't automate using the new .CHM to this day.
I understand your point, but those who make the direct changes to CHM are directly notified on the GitHub issues page. I personally would use either design, but really I just always end using the webbrowser. I imagine in the mean time, an older CHM could be used to mitigate your situation. I presume you have already done so.
Image Image Image Image Image
Windows 10 x64 Professional, Intel i5-8500, NVIDIA GTX 1060 6GB, 2x16GB Kingston FURY Beast - DDR4 3200 MHz | [About Me] | [About the AHK Foundation] | [Courses on AutoHotkey]
[ASPDM - StdLib Distribution] | [Qonsole - Quake-like console emulator] | [LibCon - Autohotkey Console Library]
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

25 Mar 2018, 12:40

AutoHotkey v2 is in alpha. Chm v2 is in alpha. It shouldn't be official until there is widespread approval. We need a new forum thread for it, because it's taking up too many posts on this thread, 'Suggestions on chm improvements'.

I believe that this:
Ptr := A_PtrSize ? "Ptr" : "UInt"
should be changed to:
Ptr := A_PtrSize ? "Ptr" : "Int"
This is of particular concern because it perpetuates a fundamental misunderstanding.
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
derz00
Posts: 497
Joined: 02 Feb 2016, 17:54
Location: Middle of the round cube
Contact:

Re: Suggestions on documentation improvements

27 Mar 2018, 07:32

@joefiesta --- @Ragnar-F has designed this help file, and would be happy to help anyone who kindly tells him what is not working with the help file. Opening an issue on github would be the best place to do that, but he watches this thread too. Might be busy, etc right now.
try it and see
...
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

27 Mar 2018, 11:55

AHK Offline .CHM - Alt + C, I or N failure:

When using the AHK .CHM file, the ALT+I, ALT+N and ALT+S shortcuts DO NOT WORK after restoring the window from a MINIMIZED state. All the other shortcuts (those of the Menu Bar) work fine at this point.
User avatar
Ragnar
Posts: 608
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

27 Mar 2018, 14:36

tidbit wrote:any reason the chm was changed in 1.28? Is it easier to maintain? if not, why fix what aint broke?
If you mean the new sidebar, this change already exists since v1.27.00. This makes it easier to control the sidebar and possibly expand it with additional features. See closed PR #185 on GitHub for details.
tidbit wrote: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.
Here I have to tell you that your editor (everedit) is not well configured. It is a no-go to open a non-existed page in CHM. SciTE4AutoHotkey and many other editors go to the start page if the selected keyword is not available.
tidbit wrote:some links also don't work (seems to be all functions? could just be my editor. commands and variables work fine).
This issue has been there all the time. The reason is simple: Only keywords with exact matches can be passed to the CHM. For commands, built-in vars, etc. there are exactly matching keywords in the index list, but not for functions - they all end with (). This could only be solved by removing the parentheses, or using v2, where they have already been removed.
Exaskryz wrote:New .chm has given me troubles. Super slow to respond when clicking in the search box;
In terms of performance, I don't notice any problems on my system. I suppose you still use Windows XP, whose CHM is based on IE8? IE8 and below is known for its poor performance and many quirks.
jeeswg wrote: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.
As Lexikos has already said here, you can restore the CHM to its old state in just a few steps. Actually, it's not that hard.
joefiesta wrote:When using the AHK .CHM file, the ALT+I, ALT+N and ALT+S shortcuts DO NOT WORK after restoring the window from a MINIMIZED state.
This can be fixed by unchecking "Navigation Tabs" in the view menu.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

27 Mar 2018, 14:48

- I've looked at the message again. I have no idea how to compile a chm, and I haven't had the time to investigate. Does it need proprietary software?
- I would appreciate if somebody would write a guide in full. Both to compile an old-school chm, and to compile an edited version of the current one. I plan to investigate this myself eventually, but it could be months away.
- If it's so easy to compile the chm, then perhaps somebody should compile it for everybody else. Generally things in AutoHotkey should be made easy, so that non-techies can proceed with things without too much bother.
- All of that said, I greatly appreciate the work that is being put into developing the chm files.

- Btw, please check the top of this post, where I list any items that are missing from the AHK v1/v2 documentation indexes.
list of every command/function/variable from across all versions - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 42#p131642
[AHK v1: #Delimiter, #DerefChar]
[AHK v2: CaretGetPos, ClipboardAll, IL_Add/IL_Create/IL_Destroy, WinGetClientPos, #SuspendExempt]
- Also, I like lexikos's idea (mentioned on GitHub) to swap the order of function information, on pages that feature deprecated commands. E.g. put StrSplit info above StringSplit info.
- Btw the FileGetAttrib command is not deprecated, and the GetKeyState command is deprecated. Thanks.
Last edited by jeeswg on 28 Mar 2018, 17:42, edited 2 times in total.
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: 608
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

27 Mar 2018, 17:34

jeeswg wrote:Btw, please check the top of this post, where I list any items that are missing from the AHK v1/v2 documentation indexes.
list of every command/function/variable from across all versions - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 42#p131642
Done, except for IL_XXX functions. They will presumably be converted to object members like the ListView and TreeView functions, so it's not worth it.
jeeswg wrote:Also, I like lexikos's idea (mentioned on GitHub) to swap the order of function information, on pages that feature deprecated commands. E.g. put StrSplit info above StringSplit info.
If I understood correctly (related to this post), Lexikos' idea was to swap the order of the old and new syntax like in LoopFile etc., not the order of the command and function.
jeeswg wrote:Btw the FileGetAttrib command is not deprecated, and the GetKeyState command is deprecated. Thanks.
Well, within v1 I would advise everyone to use FileExist instead of FileGetAttrib, since it's a function. That's what the 'deprecated' is all about. The GetKeyState site has already been revised, but not merged yet.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

27 Mar 2018, 18:13

- Potentially links to IL_/LV_/SB_/TV_ could be added to the AHK v1 index.
- As I mentioned before, I think that warnings should be given on the #CommentFlag and #EscapeChar pages re. forwards compatibility, it's not a lot of fun to alter such scripts to make them AHK v2-ready.
- That was the correct GitHub link, thanks.
- The FileGetAttrib argument could rage on forever. My perspective is that the FileGetAttrib command would be converted to the FileGetAttrib function when converting a script, and that maintaining the FileGetAttrib name is preferable to using FileExist, because the name says what it does, it is more intuitive/readable. (A similar argument is WinExist v. WinGetID in AHK v2, where both do the same thing, but using the different names for different purposes can improve readability.)
- [EDIT:] A minor point, there is an asymmetry between the Pause/Suspend pages (for both AHK v1/v2). I only noticed this because I was checking the parameter names for 'AHK v2 functions for AHK v1'.
- [EDIT:] There are various points listed here, it is my general collection of important content that is/could be in the documentation, e.g. I just added the point about WinWait/WinWaitActive.
jeeswg's documentation extension tutorial - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=7&t=33596
Last edited by jeeswg on 27 Mar 2018, 23:26, edited 5 times in total.
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
derz00
Posts: 497
Joined: 02 Feb 2016, 17:54
Location: Middle of the round cube
Contact:

Re: Suggestions on documentation improvements

27 Mar 2018, 18:53

Ragnar wrote:If I understood correctly (related to this post), Lexikos' idea was to swap the order of the old and new syntax like in LoopFile etc., not the order of the command and function.
A classic example that could be switched around. https://autohotkey.com/docs/commands/StringReplace.htm
try it and see
...
User avatar
Exaskryz
Posts: 2882
Joined: 17 Oct 2015, 20:28

Re: Suggestions on documentation improvements

27 Mar 2018, 20:44

Ragnar wrote:
Exaskryz wrote:New .chm has given me troubles. Super slow to respond when clicking in the search box;
In terms of performance, I don't notice any problems on my system. I suppose you still use Windows XP, whose CHM is based on IE8? IE8 and below is known for its poor performance and many quirks.
jeeswg wrote: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.
As Lexikos has already said here, you can restore the CHM to its old state in just a few steps. Actually, it's not that hard.
I'm on Windows 8.1. I just have 6 GB RAM as too little RAM. I'm going to record a video right now and see how slow it is.

https://www.youtube.com/watch?v=quhpknkZhZw

Thanks for sharing the link to the old one, will likely jump back to that if I can get it figure dout. Fancy animations are nice and I may use them if I install another 4 GB of RAM; this goes for all kinds of programs, especially web browsers. I don't like the script heavy sites nowadays.
User avatar
Ragnar
Posts: 608
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

28 Mar 2018, 06:37

That's strange. Even on my netbook (Win7, IE11, 1GB RAM, 1.6GHz - 2 CPUs, 250MB GPU) the CHM runs almost smoothly. Do you have the same problems when you open the online help in Internet Explorer or Chrome etc.? Which IE version do you have?
User avatar
Exaskryz
Posts: 2882
Joined: 17 Oct 2015, 20:28

Re: Suggestions on documentation improvements

28 Mar 2018, 07:07

Generally not; I don't use IE. I'd guess it's IE 9? Could be 10. I just checked, I'm actually on 11 -- had no idea it went up that high.

Once any browser is loaded into RAM and has done all its prep, navigating to the help page works just fine. I haven't experienced any issues in particular when using a web browser directly for the docs. It behaves like you saw in the latter half of the video with immediately reacting to input, and then networking and rendering is quick.
iPhilip
Posts: 791
Joined: 02 Oct 2013, 12:21

Re: Suggestions on documentation improvements

28 Mar 2018, 21:37

Hi folks,

The documentation page for GuiClose states
[v1.1.20+]: If GuiClose is a function, the GUI is closed by default.
I would prefer if this read
[v1.1.20+]: If GuiClose is a function, the GUI is hidden by default
as closed is ambiguous to me. In the context of GUIs it either means hidden or destroyed. In fact, in the example given, the GUI is hidden if the user selects Yes.

Here is some code to demonstrate the effect:

Code: Select all

Gui, Show, w200 h100, MyGuiTitle
return

F3::
DetectHiddenWindows, On
MsgBox % WinExist("MyGuiTitle ahk_class AutoHotkeyGUI")
DetectHiddenWindows, Off
return

GuiClose(GuiHwnd) {  ; Declaring this parameter is optional.
    MsgBox 4,, Are you sure you want to hide the GUI?  ; Note that I changed "close" to "hide"
    IfMsgBox No
        return true  ; true = 1
}
Thank you.
Windows 10 Pro (64 bit) - AutoHotkey v2.0+ (Unicode 64-bit)
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

01 Apr 2018, 09:18

AHK OFFLINE HELP (.chm) - Tabbing through the CONTENTS problems

1. While using the TAB key to navigate entries in the CONTENTS of OFFLINE AHK help, tabbing is inconsistent.

Certain unexpanded ( + ) entries are skipped. For example, starting at the top and setting focus at the top, USAGE AND SYNTAX is skipped if it not exanded. Proceding, ENVIRONMENT (again unexpanded) is skipped, as well as the next 4. But MATHS (still unexpanded is NOT SKIPPED.

2. When arriving at an UNEXPANDED contents entry (again, via TABBING), I can EXPAND the entry with the ENTER key, but then FOCUS JUMPS to the explanation area.

3. After 2 above, I can use SHIFT + TAB to get focus back to the Sidebar. But, focus is now at the bottom of the screen. As an aside, I have used other .chm files and they sometimes have a Function key built in that moves focus from the different sections. This was always F6.

4. After expanding some CONTENTS area, (see 2 above), I CAN NOT UNEXPAND them. For example, after expanding MATHS, I can not unexpand that section.

Of course, this all has to do with not using that hideous thing called a mouse.
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

AHK Offline HELP (.chm) Keyboard Shortcuts

01 Apr 2018, 10:32

AHK Offline HELP (.chm) Keyboard Shortcuts

I have written a group of Hotkey Functions for using the OFFLINE AHK (.chm) FILE. I hope people like it. It is here: https://autohotkey.com/boards/viewtopic.php?f=6&t=46496

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 12 guests