[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
lexikos
Posts: 9553
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

17 Jul 2016, 21:47

TAC109 wrote:There is no mention of the built-in variables 'true' and 'false' under 'variables and expressions' -> 'built-in variables' -> 'special characters' (or elsewhere under 'built-in variables').
They're under Expressions > Boolean values.

Technically they aren't variable (they don't vary, nor do A_Tab and A_Space)... True and False aren't "special characters" either.
TAC109
Posts: 1098
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Re: Suggestions on documentation improvements

17 Jul 2016, 22:12

Yes, I know they are referred to further up the help page. Other 'built-in variables' are referred to elsewhere in the documentation too. My point is that 'true' and 'false' should be referred to in the 'built-in variables' for completeness, similarly to A_Space and A_Tab.

Whether they should be referred to as variables or constants I'll leave over to you.
My scripts:-
XRef - Produces Cross Reference lists for scripts
ReClip - A Text Reformatting and Clip Management utility
ScriptGuard - Protects Compiled Scripts from Decompilation
I also maintain Ahk2Exe
lexikos
Posts: 9553
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

17 Jul 2016, 22:21

If they were defined as constants rather than variables, it would make even less sense to put them in the built-in variables section.
kinnex
Posts: 22
Joined: 09 Jun 2016, 07:52

Re: Suggestions on documentation improvements

03 Aug 2016, 10:04

Examples from:
https://autohotkey.com/docs/commands/Try.htm
https://autohotkey.com/docs/commands/Catch.htm

Neither the Try, nor the Catch page actually gives a good working example of a catch statement. You have to go to the Throw page to find out what e.Message, e.What, etc. are.

It makes a lot more sense to have something like this:

Code: Select all

			catch e
			{
				msg := "`n" . e.Message 
				msg .= "`n`nAdditional Information:`n    " . e.Extra
				msg .= "`nFrom Command: " . e.What . " @ line # " e.Line
				msg .= " in file named:`n" . e.File
				msgbox, 16, Error:, % msg
			}
That way the default example actually does something other than specifically <blank>.
lexikos
Posts: 9553
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

03 Aug 2016, 16:22

kinnex wrote:Neither the Try, nor the Catch page actually gives a good working example of a catch statement.
There are four on the Try page, and the Catch page links to them from the Examples section. There is already an example similar to the one you propose. Every complete Catch example is also a Try example - it doesn't make sense to spread them across multiple pages.
kinnex
Posts: 22
Joined: 09 Jun 2016, 07:52

Re: Suggestions on documentation improvements

05 Aug 2016, 09:56

Thank you Lexikos, I somehow missed example 3 -- which does include a good message box example. :facepalm:

I originally had some issues when attempting to use the catch clause from example 1. It would always have nothing / blank directly after "specifically". I was really confused, until I started using the code I posed above, then I was actually getting information. I am really not sure why.

To be certain, I just tested example 1 and it worked perfectly.

Clearly, the best way to improve the documentation is to get better at reading it. :lol:
p3trus
Posts: 137
Joined: 02 Aug 2016, 03:20

Re: Suggestions on documentation improvements

27 Aug 2016, 21:50

I think the Note on ClipboardAll not working with the comma operator should be mentioned in bold red letters in the comma operator's description, too.

effective_time -= comma_headache
lexikos
Posts: 9553
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

28 Aug 2016, 01:29

I don't. Absolutely anything other than a direct assignment will not work. It's not just the comma operator.
ClipboardAll is blank when used in ways other than those described above.
If someone tries to use ClipboardAll the wrong way and fails, I suppose they're more likely to look for an explanation in the ClipboardAll section than the comma section.
p3trus
Posts: 137
Joined: 02 Aug 2016, 03:20

Re: Suggestions on documentation improvements

28 Aug 2016, 01:34

.. if the person in question knows from the start that ClipboardAll is the culprit, I totally agree with you.
If the person in question only sees that his code works when using only single lines and fails as soon as he combines the assignments by commas, the person might look up the comma operator details first ;)
lexikos
Posts: 9553
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

28 Aug 2016, 01:55

Surely one would look up the ClipboardAll details next, if ClipboardAll is what is failing. My point is that putting a big bold red note in the comma documentation will only help someone who has already made the mistake and is looking for a solution. That person will find the answer soon enough without adding distracting notices to the documentation which are irrelevant to most readers most of the time.

And what about the person who tries to pass ClipboardAll to a function, or some other expression I haven't thought of? Should we add the ClipboardAll warning all over the documentation just in case? I think not.
p3trus
Posts: 137
Joined: 02 Aug 2016, 03:20

Re: Suggestions on documentation improvements

28 Aug 2016, 02:36

Ok, I'll give up ;)

(Although a poll would be interesting - how many users would see / guess the source for the error here: )

Code: Select all

; works                         |   ; doesn't work
                                |   
GetByClipboardCopy(){           |   GetByClipboardCopy(){
	_clipsave := ClipboardAll   |   	_clipsave := ClipboardAll, Clipboard := ""										
	Clipboard := ""             |   	SendInput, ^c
	ClipWait                    |   	ClipWait
	SendInput, ^c				|		_clip := Clipboard, Clipboard := _clipsave, _clipsave := ""
	_clip := Clipboard          |   	Return _clip
	Clipboard := _clipsave      |   }	
	_clipsave := ""             |
	Return _clip                |
}                               |
User avatar
jNizM
Posts: 3183
Joined: 30 Sep 2013, 01:33
Contact:

Re: Suggestions on documentation improvements

30 Aug 2016, 04:59

What happens to the Index on the left side?
Looks like the eng docs are more broken than just the index.
[AHK] v2.0.5 | [WIN] 11 Pro (Version 22H2) | [GitHub] Profile
User avatar
jNizM
Posts: 3183
Joined: 30 Sep 2013, 01:33
Contact:

Re: Suggestions on documentation improvements

31 Aug 2016, 04:52

@lexikos: Thanks for the hint. Is it possible to make the docs page as github.io (like the german one: https://ahkde.github.io/docs/AutoHotkey.htm) as backup?
[AHK] v2.0.5 | [WIN] 11 Pro (Version 22H2) | [GitHub] Profile
lexikos
Posts: 9553
Joined: 30 Sep 2013, 04:07
Contact:

Re: Suggestions on documentation improvements

01 Sep 2016, 03:31

It already is. As a backup, it does not need to have full functionality. If you want to find something, you can use a search engine of your choice or the offline help.

The current setup requires combining several .js files into "content.js", which is included by each page. Combining the files reduces the number of http requests that have to be made. Including this file on GitHub would require redundantly committing the file into version control (after it is generated by a script). I don't want to do that.

An alternative would be to create a substitute content.js which simply loads the other files. This file would be committed to version control (to appear on GitHub Pages) but would be replaced with the actual content when the help file is compiled or pulled onto this server.
asmar
Posts: 1
Joined: 01 Sep 2016, 07:58

Mistake in the basic tutorial

01 Sep 2016, 08:23

Hi, I've found that there is a mistake in the basic tutorial (in the AutoHotkey Help File and even in the web version). In part 2 - Hotkeys & Hotstrings, b. Window specific hotkeys/hotstrings are in code "untitled". So because names of windows are case sensitive it doesn't work then. I didn't know if I should put this into bug report topic but hope it doesn't make much difference.

Image
just me
Posts: 9423
Joined: 02 Oct 2013, 08:51
Location: Germany

Sleep

19 Sep 2016, 08:16

Sleep
The docs wrote:Due to the granularity of the OS's time-keeping system, Delay is typically rounded up to the nearest multiple of 10 or 15.6 milliseconds (depending on the type of hardware and drivers installed). For example, a delay between 1 and 10 (inclusive) is equivalent to 10 or 15.6 on most Windows 2000/XP systems.
I cannot test if this is correct on Win XP but at least it isn't on my Win 10 notebook.
MSDN wrote:This function causes a thread to relinquish the remainder of its time slice and become unrunnable for an interval based on the value of dwMilliseconds. The system clock "ticks" at a constant rate. If dwMilliseconds is less than the resolution of the system clock, the thread may sleep for less than the specified length of time. If dwMilliseconds is greater than one tick but less than two, the wait can be anywhere between one and two ticks, and so on.

Sleep
seems to be right.
Helgef
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: Suggestions on documentation improvements

19 Sep 2016, 09:48

just me wrote: I cannot test if this is correct on Win XP but at least it isn't on my Win 10 notebook.
You can test it like this:

Code: Select all

SetBatchLines,-1
N:=100
t1:=A_TickCount
Loop,% N	
	Sleep,10
t2:=A_TickCount
MsgBox,% "Total Sleep time: " t2-t1 "ms.`nAverage sleep time per sleep: " (t2-t1)/N " ms."
I get 15.6 ms per Sleep, (1,...,20) on win7
just me
Posts: 9423
Joined: 02 Oct 2013, 08:51
Location: Germany

Re: Suggestions on documentation improvements

19 Sep 2016, 09:54

I said "on Win XP". You might want to try my test script:

Code: Select all

#NoEnv
SetBatchLines, -1
ListLines, Off
DllCall("QueryPerformanceFrequency", "Int64P", F)
SL := 1
F1::
S := A_TickCount
DllCall("QueryPerformanceCounter", "Int64P", C1)
Sleep, %SL%
DllCall("QueryPerformanceCounter", "Int64P", C2)
C := (C2 - C1)
MsgBox, % C . " - " . ((C * 1000) / F) . " - " . (A_TickCount - S)
Return
F2::
Sleep, 1 ; to 'sync' the script with A_TickCount
S := A_TickCount
DllCall("QueryPerformanceCounter", "Int64P", C1)
Sleep, %SL%
DllCall("QueryPerformanceCounter", "Int64P", C2)
C := (C2 - C1)
MsgBox, % C . " - " . ((C * 1000) / F) . " - " . (A_TickCount - S)
Return
Esc::
ExitApp
Helgef
Posts: 4709
Joined: 17 Jul 2016, 01:02
Contact:

Re: Suggestions on documentation improvements

19 Sep 2016, 12:03

just me wrote:I said "on Win XP". You might want to try my test script:
Does neither of our scripts work on Xp, or do you not have a Xp machine available? I'll test your script when I get back to the computer. In this case I prefer measuring the average though.

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 17 guests