[Archived, Locked] Suggestions on documentation improvements

Share your ideas as to how the documentation can be improved.
TAC109
Posts: 1096
Joined: 02 Oct 2013, 19:41
Location: New Zealand

Re: Suggestions on documentation improvements

12 Jan 2018, 23:16

TAC109 wrote:A general comment on the new help. It does not perform well when viewed on an iPad. (I find it quite handy to have the AHK help open on my iPad when writing scripts on my computer.)

Problems noted so far are:-
  • the main window does not scroll properly in the web browser.
    When scrolling, the text movement stops dead when the finger is lifted. This makes it difficult to scroll up and down rapidly.
    Also cannot scroll to top of text by touching the top of the screen.
  • The 'Command and Function list/index' is not shown as a table, rather each entry is shown as two lines with the top line giving the command and the second line giving the description.
I hope these problems can be corrected so that the new help works correctly (like the old help).
Hey, you've got it all working!

Many thanks for all your hard work :thumbup:
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
just me
Posts: 9406
Joined: 02 Oct 2013, 08:51
Location: Germany

Re: Suggestions on documentation improvements

18 Jan 2018, 08:20

Related: Possible A_LoopFileLongPath bug

It should be mentioned in the docs that the use of A_LoopFileLongPath might seriously reduce the speed of Loop (files & folders).
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

19 Jan 2018, 10:52

MSGBOX:

Msgbox doc includes the statement
The Help button: When the Help button option (83) is present in Options, pressing the Help button will have no effect unless both of the following are true:
This appears incorrect. Isn't the HELP BUTTON option 16384?
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

19 Jan 2018, 13:08

MSGBOX and options values:

Msgbox doc states
The Options parameter can be a combination (sum) of one or more of the following values.
It goes on to display a chart of values and their meanings.

This is not entirely correct. Certain values are mutally exclusive. For example:

Msgbox, 8, ...

is invalid. The Help does not explain why "Msgbox, 8, ..." is invalid.
User avatar
Ragnar
Posts: 608
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

19 Jan 2018, 15:42

joefiesta wrote:This [83] appears incorrect. Isn't the HELP BUTTON option 16384?
You're right. I'll change this. The WM_HELP message was mistakenly meant (83 = 0x53).
joefiesta wrote:Msgbox, 8, ... is invalid. The Help does not explain why "Msgbox, 8, ..." is invalid.
Actually, one can (and should) logically deduce that it doesn't make sense to combine 2 (Abort/Retry/Ignore) and 6 (Cancel/Try Again/Continue), but I've revised the MsgBox's option table for clarity.
stealzy
Posts: 91
Joined: 01 Nov 2015, 13:43

Re: Suggestions on documentation improvements

20 Jan 2018, 07:44

Help file use system font color, but not use system background color. I see it with dark windows theme:
Image
Please specify text color as black or use system background color instead white.

If first input letter is widespread (a, e) I get this:
Image
Yes, I press no and continue input, then it work.
If it's hard optimize, live search should trigger after second input letter.
User avatar
Ragnar
Posts: 608
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

20 Jan 2018, 14:12

@stealzy, I've fixed your IE8 issues. See PR #228.
User avatar
derz00
Posts: 497
Joined: 02 Feb 2016, 17:54
Location: Middle of the round cube
Contact:

Re: Suggestions on documentation improvements

20 Jan 2018, 15:58

@Ragnar: I also noticed as stealzy did that the documentation uses the system font colour, but not the system background colour. (On Firefox for me) Can this be changed? Either to make the font always black, or the background be the system colour.
try it and see
...
User avatar
Ragnar
Posts: 608
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

20 Jan 2018, 18:01

The fixes I made for IE8 above should also apply to Firefox and any other browser. But to be honest, I couldn't reproduce your issue. Although I changed the system colors in Windows XP and commented out the corresponding CSS properties, my Firefox uses by default white for the background and black for the text.
User avatar
derz00
Posts: 497
Joined: 02 Feb 2016, 17:54
Location: Middle of the round cube
Contact:

Re: Suggestions on documentation improvements

20 Jan 2018, 18:07

See this screen shot after changing the firefox default font to white. https://www.dropbox.com/s/6hoyger0s2u95 ... t.png?dl=0
try it and see
...
User avatar
Ragnar
Posts: 608
Joined: 30 Sep 2013, 15:25

Re: Suggestions on documentation improvements

20 Jan 2018, 19:17

You can avoid this issue by opening "about:config" and setting "browser.display.use_system_colors" to false (which is actually the default value). But as I said before, the IE8 fixes should also apply to Firefox.
stealzy
Posts: 91
Joined: 01 Nov 2015, 13:43

Re: Suggestions on documentation improvements

21 Jan 2018, 17:18

@Ragnar, thank you, it works perfectly :thumbup:!
Now I'll try figure out how to make a button for dark(night) style:
☰ ◀ ▶ Z P N
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

22 Jan 2018, 10:06

System Colors for Offline AHK HELP:

This is very obscure. I have found that with Windows (I run windows 7 Pro) the OFFLINE AHK help file uses the following colors:

1. The FONT is garnered from Internet Options. Control Panel --> Internet Options. This opens "Internet Properties" . Choose the GENERAL tab and under "appearance" choose COLORS. The TEXT color defined there is the TEXT color for the AHK .chm HELP display.

2. The backgound color for the HELP is WHITE (0xFFFFFF). I don't know how to change that. (I can also add that this is NOT from a color in the REGISTRY from Control Panel/Appearance/Colors or Desktop/Colors. None of mine are 255 255 255.) One would expect that that BACKGROUND color at Internet Properties would be used, but, sadly, it appears not so. Can this be changed? Is this WHITE hardcoded somewhere?
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

22 Jan 2018, 10:37

Doc for GUI DEFAULT:

The doc at Gui for DEFAULT states:
Gui, GuiName:Default

Changes the current thread's default GUI window name, which is used whenever a window name is not specified for GuiControl, GuiControlGet, and the Gui command itself. In the following example, the default window name is changed to "MyGui": Gui MyGui:Default. See thread's default window for more information about the default window.
This is not complete. The Gui DEFAULT command is also used for all the builtin functions for LISTVIEW. (Are there other functions as well?)
stealzy
Posts: 91
Joined: 01 Nov 2015, 13:43

Re: Suggestions on documentation improvements

22 Jan 2018, 10:38

Btw, new help file process get 55 Mb - up to 100 Mb memory. Previous classic help get 20-25 Mb (working set).
joefiesta wrote:Is this WHITE hardcoded somewhere?
Yes, it is. Compare with Putty help:
Image
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

31 Jan 2018, 10:20

Documentation: GUISIZE

The documentation at GUISIZE states very succinctly:
GuiSize: Launched when the window is resized, minimized, maximized, or restored.
This is FAR FROM COMPLETE.

As the following sample script can show,

1. GUISIZE is launched when a GUI is first shown. (Yes, it may be argued that it is at that time being RESIZED. But, do we need to argue about documentation?)

2. After the first msgbox is closed, clicking the script's button on the Windows Taskbar activates the GUISIZE subroutine.

sample script:

Code: Select all

Gui, 2:Add, Edit, r1 w225 vText, howdy
Gui, 2:Show
return

2guisize:
  msgbox guisize label
  return
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

05 Feb 2018, 09:38

What is a THREAD?

Doc for THREAD does not precisely define what constitutes a thread. It says:
The current thread is defined as the flow of execution invoked by the most recent event; examples include hotkeys, SetTimer subroutines, custom menu items, and GUI events.
1. If a thread is an EVENT, then what is a EVENT?

2. "Examples include"... .this is lacking, for it does not say what else is NOT INCLUDED in this list of examples. That is, it does not tell us these are (if that is the case) ALL events that constitute a thread.

This sort of phrasing (re. "examples ...") is used elsewhere in the same doc item, with equally vague meaning:

a.
single script can have multiple simultaneous MsgBox, InputBox, FileSelectFile, and FileSelectFolder dialogs. This is achieved by launching a new thread (via hotkey, timed subroutine, custom menu item, etc.) while a prior thread already has a dialog displayed.
b.
Any thread (hotkey, timed subroutine, custom menu item, etc.) with a priority lower than that of the current thread cannot interrupt it.
The use of the word "ETCETERA" in these cases only makes me wonder (what the other things are). Additionally, the a. and b. above may be considered defining "THREAD" for a second and third time. Thus, I think, the parenthetical phrases in each should not exist.

Joe Petree
neogna2
Posts: 586
Joined: 15 Sep 2016, 15:44

Re: Suggestions on documentation improvements

06 Feb 2018, 05:45

suggestion 1: make Autohotkey Help default to the Index pane, not Content.

suggestion 2: searching (ctrl+F) used to stay within the right side big window pane. But now the search first finds matches in the left side Index pane before searching text on the right side pane. Any way to force the search to start with the pane that has focus?
User avatar
lmstearn
Posts: 681
Joined: 11 Aug 2016, 02:32
Contact:

Re: Suggestions on documentation improvements

10 Feb 2018, 07:02

joefiesta wrote:What is a THREAD?
Doc for THREAD does not precisely define what constitutes a thread. It says:
The current thread is defined as the flow of execution invoked by the most recent event; examples include hotkeys, SetTimer subroutines, custom menu items, and GUI events.
1. If a thread is an EVENT, then what is a EVENT?
Joe Petree
Threads & Processes said:
A process, in the simplest terms, is an executing program. One or more threads run in the context of the process. A thread is the basic unit to which the operating system allocates processor time. A thread can execute any part of the process code, including parts currently being executed by another thread.
Window Messages said
For each thread that creates a window, the operating system creates a queue for window messages. This queue holds messages for all of the windows that are created on that thread
Maybe an analogy for a thread is a lane on a multilane highway where the vehicles (messages) are queued and released at the OS tollgate.
An event is something created either by the user, OS, or a series of statements executing on (at least) one thread.
Perhaps a cross-link over to Concepts might help as well.
:arrow: itros "ylbbub eht tuO kaerB" a ni kcuts m'I pleH
joefiesta
Posts: 494
Joined: 24 Jan 2016, 13:54
Location: Pa., USA

Re: Suggestions on documentation improvements

19 Feb 2018, 10:02

Subject: MORE FONT PROBLEMS using the help .CHM file

As I mentioned before, one problem with the .CHM file is the font sizes. Each time the file is opened, the fonts revert to size 3 (of the 1 (smallest) to 5 (largest)).

I want the fonts to be size 4 ALWAYS. Should not be a problem. But, it's a huge problem.

So, I automated opening the .CHM file (using, yeah, you guessed it, AutoHotkey). When it opens (font 3) my scripts clicks the magnifier and, voila!, font size 4. Great. (Not great is the fact that the shortcuts don't work and I have to program the APPROXIMATE click location.)

But, now I change topics. Voila, font 3. Not great. Now, I could refine my script, but it would start to get ridiculous. (Since the window title has changed, I could record each title change, whether or not I increased the font on that page, change it or not change it accordingly, etc. etc. this is absurd!) But, wait, it gets far worse. So confounded that it would be almost impossible to write this code.

Sometimes clicking the magnifier MAKES THE FONT SMALLER. Try this:

1. open .chm file
2. Click "recent changes"
3. Click magnifier 3 time. This should make mag level 1 (smallest).
4. Change topics. Click "script showcase" (mag level will not be 3)
5. Click "recent changes". (Don't us BACK button. I THINK this may work differently). Mag level will now be RESET TO DEFAULT: 3
6. Click magnifier. FONT GETS SMALLER.

.CHM files for other applications do not exhibit these behaviors.

Return to “Suggestions on Documentation Improvements”

Who is online

Users browsing this forum: No registered users and 12 guests