[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
User avatar
Ragnar
Posts: 608
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

05 Apr 2018, 09:21

If anyone wants the offline help with the old sidebar back, here's what you can do:
  1. Download and install Microsoft's HTML Help Workshop, if not already done (default location is C:\Program Files (x86)\HTML Help Workshop\)
  2. Download the current help files at GitHub and extract the zip file
  3. Search for compile_chm.ahk, open it in an editor and uncomment the lines after "use old sidebar" (currently line 31)
  4. Run compile_chm.ahk
  5. Search for the created AutoHotkey.chm in the same location as compile_chm.ahk
  6. Run AutoHotkey.chm (don't forget to check "Navigation Tabs" in the view menu, if it was previously unchecked)
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

05 Apr 2018, 12:59

- Very nice Ragnar, thanks so much. I tested it and it created an old-style chm as stated. So it'll be interesting to see if that works for the people that wanted it.
- Btw I had thought that I'd read that Microsoft's HTML Help Workshop was a commercial product, but this appears to freely available, direct from Microsoft. Hmm.

- [EDIT:] Re. BlockInput. The word 'and' should probably be changed to 'or'. I use Windows 7, and I recently discovered that BlockInput is not working on Notepad, unless the script is run as admin.
Note: Mode 1 and 2 might have no effect if UAC is enabled and the script has not been run as administrator. For more information, refer to the FAQ.
Link:
Block Input not working? - Ask for Help - AutoHotkey Community
https://autohotkey.com/board/topic/9721 ... t-working/
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

EXITAPP doc

06 Apr 2018, 08:19

EXITAPP states, rather succinctly, that it "Terminates the script unconditionally." But, that is not entirely correct. It goes on to say in the REMARKS "The script is immediately terminated unless it has an OnExit subroutine."

I think the second stipulation is EXTREMELY important and should be not be construed as explanatory material (as I take the remarks section to be) and that it should be included with the first sentence of the command's doc.
fatodubs
Posts: 29
Joined: 20 Sep 2017, 18:53

Splitting a Long Line into a Series of Shorter One (help doc confusing)

11 Apr 2018, 12:43

Code: Select all

ProductIsAvailable := (Color = "Red")
    ? false  ; We don't have any red products, so don't bother calling the function.
    : ProductIsAvailableInColor(Product, Color)
I see how this can code can work as intended, but it gives the impression that the first piece after the condition is the false response if you end up here and are unfamiliar with the ternary operators.

Even though I use ternary operators pretty frequently in code that works correctly, after seeing this, I had to go read the documentation on them again to be sure I was using them correctly. Having anything besides "false" as your true output would be a lot less confusing.
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

18 Apr 2018, 16:40

inspired by https://autohotkey.com/boards/viewtopic.php?f=5&t=47550

the docs on object property syntax seem very arcane to me, see https://autohotkey.com/docs/Objects.htm ... s_property

how is one to infer from the snippet provided

Code: Select all

Property[]
{
    get {
        return ...
    }
    set {
        return ... := value
    }
}
that theyre actually meant to use this instead:

Code: Select all

myProperty[] {
	set {
		; store the argument passed to the setter in a separate instance variable
		; underscore + the property's name is just a convention
		; this is done to prevent infinite loops
		; 'value' is a keyword, the argument passed to the setter, fair enough this is actually documented
		return this._myProperty := value
	}

	get {
		return this._myProperty ; you need to read from the 'dummy/placeholder' instance variable
	}
}
you might argue that the example provided further below in the docs does a good enough job, but i disagree
it mixes the get/set meta function and property syntax, while trying to explain both at the same time. its just confusing af
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

18 Apr 2018, 17:57

@iPhilip, I tried to create a list also, and found around 30 more items.
List of commands that affect ErrorLevel - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 22#p213522
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
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

19 Apr 2018, 20:17

I did another check of the command indexes.

Missing from AHK v1 list:
ComObject/Hotstring
(also: LTrim/RTrim/SendEvent/#IncludeAgain)
(also: IfNotExist/IfNotInString/#IfWinNotActive/#IfWinNotExist)
(also+: IL_XXX/LV_XXX/SB_XXX/TV_XXX)

Missing from AHK v2 list:
Hotstring
SubStr has a trailing space
(also: LTrim/RTrim/SendEvent/#IncludeAgain)
(also: DriveXXX/RandomSeed)
(also+: IL_XXX)

I know that arguably if Trim is there, you don't need to explicitly mention LTrim/RTrim etc. However, I think that actually, it's often a good idea to list every single function explicitly. It fixes things in the mind, and you don't get a surprise when you open the page and find further functions.

I've created this which may be of interest:
AutoHotkey syntax lists (text files) - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 74&t=47603
And other lists, mentioned here:
list of every command/function/variable from across all versions - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 42#p131642
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

25 Apr 2018, 10:00

jeeswg wrote:The FileGetAttrib argument could rage on forever.
Lexikos has removed the 'deprecated' note and added an explanation why the command is not deprecated (commit).
I have submitted PR#277 to implement following suggestions for the v1 docs:
jeeswg wrote:I think that warnings should be given on the #CommentFlag and #EscapeChar
derz00 wrote:A classic example that could be switched around.
iPhilip wrote:I would prefer if this read "If GuiClose is a function, the GUI is hidden by default"
jeeswg wrote:BlockInput. The word 'and' should probably be changed to 'or'.
iPhilip wrote:I would like to recommend that the ErrorLevel page list the commands that affect its value.
jeeswg wrote:Missing from AHK v1 list:
ComObject/Hotstring
(also: LTrim/RTrim/SendEvent/#IncludeAgain)
(also: IfNotExist/IfNotInString/#IfWinNotActive/#IfWinNotExist)
(also+: IL_XXX/LV_XXX/SB_XXX/TV_XXX)
PR#275 for v2 docs (some v2 issues are automatically fixed when the v1 docs is merged into v2 docs):
jeeswg wrote:Missing from AHK v2 list:
Hotstring
SubStr has a trailing space
(also: LTrim/RTrim/SendEvent/#IncludeAgain)
(also: DriveXXX/RandomSeed)
(also+: IL_XXX)
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

The phrase "task bar" in documentation

02 May 2018, 10:10

I would like to suggest that the use of the phrase "task bar" in the documentation be changed globally to "taskbar".

As it is now, the documentation contains both "taskbar" and "task bar" in various places.

Additionally, it is always difficult in Windows to search for phrases containing embedded blanks.

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

Improve definition of Buddy1 and Buddy2 for Slider

03 May 2018, 07:33

The full extent, as far as I can find, of the documentation for the BUDDY1 and BUDDY2 options of GUI, ADD, SLIDER is:
Buddy1 and Buddy2: Specifies up to two existing controls to automatically reposition at the ends of the slider. Buddy1 is displayed at the left or top side (depending on whether the Vertical option is present). Buddy2 is displayed at the right or bottom side. After the word Buddy1 or Buddy2, specify the variable name of an existing control. For example, Buddy1MyTopText would assign the control whose variable name is MyTopText
This documentation is inadequate. It gives me no way to figure out why the following code truncates the view of the two buddies it adds to the slider it creates.

Code: Select all

#Persistent
   Gui, 1: add, text,  w25 vSliderL , 0`%
   Gui, 1: add, text,  w25 vSliderR , 90`%
   Gui, 1: Add, Slider, x25 y30 w500 TickInterval10 ToolTip Range0-100 Buddy1SliderL Buddy2SliderR
   gui, 1: show
return
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

06 May 2018, 17:11

- I'm working on creating a big list of AHK v1/v2 example code lines, to test forwards/backwards conversion. (And I'm choosing names for parameters for my 'AHK v2 functions for AHK v1' library.) (And working on syntax lists for autocomplete/drop-down menus ...)
- This would all be greatly helped if there were standard names for each parameter (where each name is a valid variable name):

Code: Select all

;before:
Pause [, On|Off|Toggle, OperateOnUnderlyingThread?]
Suspend [, Mode]

;after:
Pause [, Mode, OperateOnUnderlyingThread?]
Pause [, Mode, OperateOnUnderlyingThread] ;or perhaps this (I don't mind)
Suspend [, Mode]

;choose a name of some kind where currently pipes are used

;Control-or-Pos -> ControlOrPos ;perhaps
;PID-or-Name -> PIDOrName ;perhaps
;Part# -> Part ;or leave it at is it (I don't mind)
- My intention would be to change the syntax boxes, and there wouldn't be an enormous number to change. Classic words to use would be: Mode, Options, Param1, State, String, Value.
- I made some choices here in the test script (and also in the lib itself):
commands as functions (AHK v2 functions for AHK v1) - Page 2 - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 22#p210822
- This would facilitate with copying and pasting for direct use in a script. Any literal strings would require quotes in AHK v2, so text that is ready to be used as variable names is the more useful.
- Each parameter would have a unique 'name'. You could refer to the 'XXX' parameter.
- (And there would be greater elegance.) Thanks for reading.

[EDIT:]
- Here are lines from the AHK v2 syntax boxes that contain a pipe.
- The situation in AHK v2 isn't too bad, so it might be simpler to keep things as they are in both AHK v1 and v2.
- However, I believe it would be advantageous to have a list in one place of every function with a standardised name for each parameter.

Code: Select all

CoordMode "ToolTip|Pixel|Mouse|Caret|Menu" [, "Screen|Window|Client"]
DetectHiddenText "On|Off"
DetectHiddenWindows "On|Off"
GroupClose GroupName [, "A|R"]
ListLines ["On|Off"]
MouseClick [WhichButton, X, Y, ClickCount, Speed, "D|U", "R"]
MouseGetPos [OutputVarX, OutputVarY, OutputVarWin, OutputVarControl, 1|2|3]
Pause ["On|Off|Toggle", OperateOnUnderlyingThread?]
OutputVar := PixelGetColor(X, Y [, "Alt|Slow"])
Run Target [, WorkingDir, "Max|Min|Hide", OutputVarPID]
ExitCode := RunWait(Target [, WorkingDir, "Max|Min|Hide", OutputVarPID])
SendMode "Input|Play|Event|InputThenPlay"
SetStoreCapsLockMode "On|Off"
SetTimer [Callback, Period|"On|Off|Delete", Priority]
SetTitleMatchMode "Fast|Slow"
StringCaseSense "On|Off|Locale"
#MaxThreadsBuffer On|Off
#SingleInstance [force|ignore|off]
#UseHook [On|Off]
Last edited by jeeswg on 27 Jun 2018, 19:18, edited 1 time 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
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

SUSPEND command

09 May 2018, 13:18

The doc at SUSPEND states:

"Any hotkey/hotstring subroutine whose very first line is Suspend (except Suspend On) will be exempt from suspension. "

1. If the first line is "suspend", that, perforce, excludes "suspend on".

2. The "except Suspend On" statement IMPLIES that "SUSPEND", "SUSPEND, OFF", "SUSPEND, TOGGLE" and "SUSPEND, PERMIT" all make the script exempt from suspension. (One should not have to infer meaning from documentation.) That being the case--I can't say it is, as I haven't tested this--the command's explanation would be MUCH CLEARER if that statement were: "Any hotkey/hotstring subroutine whose very first line is ANY SUSPEND COMMAND (except Suspend On) will be exempt from suspension."
JDN
Posts: 9
Joined: 09 May 2018, 01:33

Re: Suggestions on documentation improvements

18 May 2018, 15:12

Blk28 recently started a thread titled, "startup script not working". Here is a link:
https://autohotkey.com/boards/viewtopic.php?f=5&t=49224
This thread got me to thinking there is a problem in the AHK FAQ section about the "Startup Folder". Here is what the FAQ says:

-------------------------------------------------------------------------------
How do I put my hotkeys and hotstrings into effect automatically every time I start my PC?

There is a folder in the Start Menu called Startup. If you put a shortcut to your script in that folder, the script will launch automatically every time you start your PC. To create a shortcut:
Find the script file, select it, and press Control-C.
Right-click the Start button (typically at the lower left corner of the screen) and choose "Explore All Users".
Navigate to the Startup folder inside the Programs folder.
From the menu bar, choose Edit -> Paste Shortcut. The shortcut to the script should now be in the Startup folder.
-------------------------------------------------------------------------------

The current version of the FAQ (1.1.28.02) says "Navigate to the Startup folder inside the Programs folder". But that is not nearly enough information. I explained why in the above link. But I will say it again here.
Managing the "startup folder" is a real pain because that folder is very difficult to find and one of the folders in which it is contained is a hidden folder. That hidden folder is "C:\ProgramData". You must unhide it if you hope to access the Startup folder manually (without any Startup utility). I will explain how to unhide a folder. But it would be so much easier just to use Mike Lin's Startup utility. I will provide some info about that utility at the end of this post.

For example, on my PC, the startup folder is found here: "C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Startup"
Can you believe that you have to remember such a long and complicated path in order to access the Startup folder yourself? I can't believe Microsoft never provided any easier way.

The current version (1.1.28.02) of the AHK FAQ says, "Navigate to the Startup folder inside the Programs folder". But it never explains what is involved to do that and you need a lot more info to be able to do that.
One problem is that "C:\ProgramData" is a hidden folder. So you must unhide it if you want to try to access this folder yourself. For these reasons, it is so much easier to use Mike Lin's Startup utility.

One way to unhide a folder is this: You can do it by using Windows Explorer and selecting "Tools" then "Folder Options" then "View" and then specify "Show Hidden files, Foders and Drives". You must then restart Windows Explorer.
A second way is to access "Folder Options" from the Control Panel.

There is a most excellent freeware utility called "Startup" written by Mike Lin. Just Google "startup mike Lin" and download it. Here is one link but I haven't tried it: http://www.majorgeeks.com/files/details ... rsion.html
I would suggest the FAQ could benefit from some expanded explanation about the Startup folder. Can you reference that freeware utility in your FAQ?

Good luck.
Last edited by JDN on 18 May 2018, 18:08, edited 1 time in total.
swagfag
Posts: 6222
Joined: 11 Jan 2017, 17:59

Re: Suggestions on documentation improvements

18 May 2018, 17:51

JDN wrote:... I can't believe Microsoft never provided any easier way. ...
they have

3. Navigate to the Startup folder inside the Programs folder. Alternatively, press Win + R, type in shell:startup and click OK, or press Enter.
User avatar
jeeswg
Posts: 6902
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Suggestions on documentation improvements

18 May 2018, 17:53

I have just updated my Explorer tutorial to provide information about 'shell:' folders
e.g. shell:Startup and shell:Common Startup. The FAQ could possibly make reference to these 'shell:' folders.

jeeswg's Explorer tutorial - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=7&t=31755
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
JDN
Posts: 9
Joined: 09 May 2018, 01:33

Re: Suggestions on documentation improvements

18 May 2018, 18:23

swagfag wrote:
JDN wrote:... I can't believe Microsoft never provided any easier way. ...
they have

3. Navigate to the Startup folder inside the Programs folder. Alternatively, press Win + R, type in shell:startup and click OK, or press Enter.
Aha! Thank you very much for that info. I didn't know that.

I should tell you that it took me a minute to figure out that Win+R was equivalent to opening the Run Box. On my PC, Win+R does not open the Run box and I don't know why.

Also anyone who is interested should know the path I posted to the Startup folder was: "C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Startup"

That is the path to the Startup folder used for All Users - in other words for everyone who uses the PC.

The path that I got to with Shell:startup was "C:\Users\name\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup"
That is a folder used for an individual user with the name of "name". So people should be careful they know which one they want to use.

However, that was real good info and I thank you kindly.
Last edited by JDN on 18 May 2018, 18:30, edited 1 time in total.
JDN
Posts: 9
Joined: 09 May 2018, 01:33

Re: Suggestions on documentation improvements

18 May 2018, 18:28

jeeswg wrote:I have just updated my Explorer tutorial to provide information about 'shell:' folders
e.g. shell:Startup and shell:Common Startup. The FAQ could possibly make reference to these 'shell:' folders.

jeeswg's Explorer tutorial - AutoHotkey Community
https://autohotkey.com/boards/viewtopic.php?f=7&t=31755
Hello Jeeswg. That is good info you posted as well. I never knew that. The info you posted was "shell:Common Startup". That gets you to the Startup folder used for everyone - meaning for the entire PC.
The command "shell:startup" takes you to the Startup folder used by an individual user. People don't have to worry about which user that is because once someone signs in to their account, that command "shell:startup" should take them to the correct folder for their account.

I'm just posting this to try and clarify it for people who need to know into which folder they want to place the shortcut - the Startup folder for the entire PC or the Startup folder just for their account.

I thank you kindly for your info. I still think people may benefit by using Mike Lin's Startup utility and I would suggest that anyone who wants to put some apps into their startup folder, might like to experiment with both methods so they can choose which one they prefer. After all, it's good to have choices.

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 6 guests