Suggestions on documentation improvements

Propose new features and changes
Stamimail
Posts: 67
Joined: 06 Nov 2014, 08:48

Re: Suggestions on documentation improvements

Post by Stamimail » 18 Oct 2017, 14:25

I think that for learning AHK as a first language you need to "write a book".
I only suggested, that the examples used in this book, for explaining each chapter, will be useful example/tool.
(You can think also about giving an advanced script, and telling the user to focus for this chapter learning in some 3 lines)
While writing each chapter:
The first question is: What do I want that the user will know by reading this chapter.
The second question is: Which script is good to use for explaining the chapter goals, and giving the user useful tool.

In this way:
1. the user will learn the chapter (the main goal)
2. the user will have a useful tool, that will encourge him to go on in reading the book, and exploring more about the chapter and its relative commands, for customize his tool.

If there is no book, the user has no choice but to learn by "looking for solutions" method.
Stamimail
Posts: 67
Joined: 06 Nov 2014, 08:48

Re: Suggestions on documentation improvements

Post by Stamimail » 25 Oct 2017, 13:32

If there is no book, the user has no choice but to learn by "looking for solutions" method.
Now that I'm thinking about it... years ago I had an idea, which if had been implemented then, I think my progress in AHK and my skills now would have been completely different.

https://autohotkey.com/boards/viewtopic.php?t=5152
User avatar
Exaskryz
Posts: 2873
Joined: 17 Oct 2015, 20:28

Re: Suggestions on documentation improvements

Post by Exaskryz » 04 Nov 2017, 09:07

https://autohotkey.com/docs/misc/RemapJoystick.htm

On this page, at the top, it makes the recommendation to use the software PPJoy if you would like to make artificial joystick output. (Remap keys -> joystick; AHK is only capable of joystick -> keys). However, following the hyperlink points us to a geocities page which is now debunk and results in redirecting to a "smallbusiness.yahoo.com"

I have seen people suggest software to use for people requesting being able to produce artificial joystick output. Maybe updating the docs to recommend one of those software would be good, or someone knowing of a good site to download PPJoy from today?
egocarib
Posts: 99
Joined: 21 May 2015, 18:21

Re: Suggestions on documentation improvements

Post by egocarib » 08 Nov 2017, 13:38

MonitorGet (AHKv2) should be moved from the Misc. sidebar section to the Screen sidebar section.
egocarib
Posts: 99
Joined: 21 May 2015, 18:21

Re: Suggestions on documentation improvements

Post by egocarib » 08 Nov 2017, 15:57

Also, would be great if the v2 documentation site search bar was updated to show you search results for the v2 documentation, instead of redirecting you to results on the v1 documentation website.
User avatar
Ragnar
Posts: 200
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

Post by Ragnar » 09 Nov 2017, 04:56

egocarib wrote:MonitorGet (AHKv2) should be moved from the Misc. sidebar section to the Screen sidebar section.
I've created a pull request on GitHub for this issue.
egocarib wrote:Also, would be great if the v2 documentation site search bar was updated to show you search results for the v2 documentation, instead of redirecting you to results on the v1 documentation website.
The v2 documentation will soon receive the new sidebar from the v1 documentation, including its own search.
egocarib
Posts: 99
Joined: 21 May 2015, 18:21

Re: Suggestions on documentation improvements

Post by egocarib » 09 Nov 2017, 18:14

Nice - I hadn't noticed the new sidebar and format updates. They look awesome! :thumbup:
User avatar
Ragnar
Posts: 200
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

Post by Ragnar » 10 Nov 2017, 13:27

Exaskryz wrote:On RemapJoystick.htm, at the top, it makes the recommendation to use the software PPJoy if you would like to make artificial joystick output. (Remap keys -> joystick; AHK is only capable of joystick -> keys). However, following the hyperlink points us to a geocities page which is now debunk and results in redirecting to a "smallbusiness.yahoo.com"
just me wrote:ControlGet -> Choice: ; It will be -1 if there is no item selected. is definitely wrong for 32-bit AHK because SendMessage returns an UINT value (4294967295 in this case).
just me wrote:The Standard Windows Fonts page contains outdated information and shoud be updated, removed, or replaced by an external link (I didn't find any useful).
TAC109 wrote:format() is missing from the list of built-in functions.
nnnik wrote:InsertAt example: ; This is the new "position" of "B" should be ; This is the new "position" of "A"
Fixes/changes/additions for these issues can be found in another pull request on GitHub.
User avatar
jeeswg
Posts: 5140
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

Post by jeeswg » 11 Nov 2017, 04:53

Fragment identifiers.
- It would be good to have direct links available for each code example at the bottom of a page e.g.
Run / RunWait
https://autohotkey.com/docs/commands/Run.htm#ExecScript
Each code example would need some sort of meaningful identifier, and not something like '#Example1', in case the examples were shuffled/added to.
- Alternatively, is there some url suffix available to jump to the specified string if it exists. I would happy with this solution instead.

Scrolling.
Since the website was updated, when I open the page, I cannot scroll up or down with the arrow keys etc.

Thanks for reading.
egocarib
Posts: 99
Joined: 21 May 2015, 18:21

Re: Suggestions on documentation improvements

Post by egocarib » 11 Nov 2017, 13:40

jeeswg wrote:Fragment identifiers.
- It would be good to have direct links available for each code example at the bottom of a page e.g.
Run / RunWait
https://autohotkey.com/docs/commands/Run.htm#ExecScript
I agree that it would be a nice enhancement. Though I don't think it is a significant issue. If you're directing someone else to an example, you can usually just link to #Examples and add provide a short description of which one you're referring to. I took a quick look and these seem to be the only pages with ~40 or more lines in the example section. If someone does want to add anchors, these would most likely be the pages to focus on. A few of these already have anchors to their individual examples.
Spoiler
jeeswg wrote:Scrolling.
Since the website was updated, when I open the page, I cannot scroll up or down with the arrow keys etc.
Seems to be related to the new sidebar change. The focus isn't on the main content now when you load a page. If you click in the main content area, you can then scroll with up/down arrows. Ragnar might know how to fix this.
User avatar
jeeswg
Posts: 5140
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

Post by jeeswg » 11 Nov 2017, 15:55

- The mouse wheel works to scroll the window fine, but even when I click in the middle area or scrollbar, up/down, PgUp/PgDn don't scroll. Tested on Internet Explorer 11. At least I can create an AHK script to handle the website: Send, {WheelDown}.
- Your suggestion to focus on fragment identifiers for pages with a lot of examples is fine.
If you're directing someone else to an example, you can usually just link to #Examples and add provide a short description of which one you're referring to.
- I was doing this and it was getting incredibly tiresome. It's also an issue if I want to revisit that example myself, and I have to find it again. A jump to the first occurrence of a string, if simple/possible, would be a general solution, that wouldn't require editing multiple webpages.

Link:
list fragment identifiers on a webpage (hash that jumps to point) - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=5&t=28053
User avatar
Barney
Posts: 50
Joined: 28 May 2014, 20:03
Location: Germany

Re: Suggestions on documentation improvements

Post by Barney » 13 Nov 2017, 23:56

For BlockInput it says
BlockInput On might have no effect if UAC is enabled and the script has not been run as administrator.
After reading this I was under the impression only Mode 1 is affected, but actually BlockInput, Send, i.e. Mode 2, is affected, too.
User avatar
Ragnar
Posts: 200
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

Post by Ragnar » 14 Nov 2017, 12:08

jeeswg wrote:Scrolling.
Since the website was updated, when I open the page, I cannot scroll up or down with the arrow keys etc.
Should be fixed. You can test it in the German docs. Note that Edit and ListBox in the Index and Search tab remain focused when used.
jeeswg wrote:The mouse wheel works to scroll the window fine, but even when I click in the middle area or scrollbar, up/down, PgUp/PgDn don't scroll. Tested on Internet Explorer 11.
I don't have any problems with that. It even works in IE8 on Windows XP.
jeeswg wrote:A jump to the first occurrence of a string, if simple/possible, would be a general solution, that wouldn't require editing multiple webpages.
Do you already know CTRL+F? ;) Otherwise, I think egocarib's suggestion is sufficient: Link to #Examples and add a short description. But I don't want to stop anyone from making this change at GitHub.
User avatar
jeeswg
Posts: 5140
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

Post by jeeswg » 14 Nov 2017, 13:24

@Ragnar:
- Great, it didn't work in the English docs, but did in the German docs, working nicely. (Navigation with arrow keys on the website in Internet Explorer 11.)
- If there's a standard for a url that in effect did what Ctrl+F does, that would be great, I'd like it for my website.
- I needed some sort of radical solution re. examples, I looked back at urls I'd made to the examples sections of pages, and seeing that adding fragment identifiers to every example is not necessarily easy or something I want to do depend on ... The best solution is actually to copy and paste the code, once I've found it, to the forum post, or to my text files, to save people having to navigate to it in the help file, and to save having to think about what text to copy and paste, to uniquely identify the example. (It actually often takes a while when looking at an example, to find some good candidate text for Ctrl+F.)
- Feel free to use information from here in the documentation, modified as much or as little as you want. E.g. 'Format function examples'.
jeeswg's documentation extension tutorial - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=7&t=33596
- Btw I don't see DirExist or Exception here (e.g. FileExist / DirExist, Throw / Exception):
Alphabetical Function Index
https://lexikos.github.io/v2/docs/commands/index.htm
- So you've done a lot of good things with the documentation, what've you got planned? Cheers.
User avatar
Ragnar
Posts: 200
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

Post by Ragnar » 15 Nov 2017, 09:02

Barney wrote:After reading this I was under the impression only Mode 1 is affected, but actually BlockInput, Send, i.e. Mode 2, is affected, too.
You're right. I've changed the line to Mode 1 and 2 might have no effect... and add it to the pull request on GitHub.
jeeswg wrote:Btw I don't see DirExist or Exception here (e.g. FileExist / DirExist, Throw / Exception):
I've added Exception to v1's command and function list (which will be later automatically integrated into the v2 docs), and DirExist to v2's function list.
User avatar
derz00
Posts: 495
Joined: 02 Feb 2016, 17:54
GitHub: derz00
Location: Middle of the round cube

Re: Suggestions on documentation improvements

Post by derz00 » 02 Dec 2017, 08:48

Should there not be a index item for A_Args (v2 only)? There is one parameters passed to a script, which gets you pretty close.... But if A_Args is a thing, it should be in the index
try it and see
...
User avatar
Ragnar
Posts: 200
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

Post by Ragnar » 02 Dec 2017, 17:45

derz00 wrote:Should there not be a index item for A_Args (v2 only)?
It should. Added to pull request on GitHub.
guest3456
Posts: 2419
Joined: 09 Oct 2013, 10:31

Re: Suggestions on documentation improvements

Post by guest3456 » 10 Dec 2017, 10:51

ragnar, good work with the docs updates

joefiesta
Posts: 154
Joined: 24 Jan 2016, 13:54

Re: Suggestions on documentation improvements

Post by joefiesta » 10 Dec 2017, 13:21

WinMove - parsing problem should be documented

The following script produces an error. Specifically "Missing ]".

winmove, KEDIT - [, , 15, 43, 1316, 954

Because the WINMOVE command has 2 syntaxes, the parser has a problem. While the above is a valid syntax for the WINMOVE command (2nd version, with more than 2 parameters), the parser sees the "[" as the beginning of the definition of an array.
This is discussed at https://autohotkey.com/boards/viewtopic ... 14&t=41101

Additionally, the workaround could be documented (again, see the discussion).

Thank you

Joe Petree
Post Reply

Return to “Wish List”