Sidebar changes

[Ragnar-F]

These changes was made with the focus on mobile device support and reducing CHM dependency.

Examples:

Online: https://ahkde.github.io/docs/AutoHotkey.htm
CHM file: https://github.com/ahkde/docs/releases/download/v1.1.26.00/AutoHotkeyHelp_DE.zip

Minimum requirements:

• CSS2-capable browser like Internet Explorer 8 and later (that is, at least Windows XP)
• JavaScript enabled

Test environments:

• IE8-11, Edge, Chrome, Firefox (Android and PC)

New features/changes:

• Search (developed by @Lexikos and improved by @joedf) with keyword highlighting and support for non-english characters
• Toolbar with various buttons:
  • 'Hide/Show sidebar'
  • Outside of the CHM file:
    • 'Home page'
    • 'Change language'
    • 'Change AHK version'
    • 'Edit page on GitHub'
  • Inside the CHM file:
    • 'Back'
    • 'Forward'
    • 'Change font size'
    • 'Print'
• Mobile device support:
  • Appropriate font size
  • Hide sidebar automatically
  • Responsive tables (and some tables simplified, like KeyList.htm)
  • Long words shortened/changed
• External link icons
• Code download support for Edge
• Sticky sidebar (not only the index tab)
• Resizing the side bar
• New design according to the forum theme (Simplicity)
• New code box design (with select and download buttons on mouse hover)
• Reduced the use of space to a minimum to set the focus on the main content
• Match/Mismatch indicator for the index's and search's input field
• Shortcut keys similar to the ones of the CHM (ALT+C/N/S)
• Searching via docs/search.htm?q=query&m=mode (mode is 1 for index tab and 2 for search tab)

CHM file:

• Internal sidebar replaced with the JavaScript sidebar
• As mentioned above, new toolbar buttons added which replace the old ones because they are connected with the disabled internal sidebar

Known issues:

• Because of the IE8's catastrophically JavaScript performance and missing support for IndexOf, a long-running-script warning message could be shown (for example when typing "e")
• Because of the new sidebar in the CHM file, some AHK scripts which interact with this file (for example the F1 hotkey of SciTE4AutoHotkey) no longer work

Possible future extensions:

• Button for changing between dark and light theme
• Button for editing the page via GitHub [Added]
• Inpage TOC (or heading list)
• Syntax highlighting

[fincs]

Internal sidebar replaced with the JavaScript sidebar
Because of the new sidebar in the CHM file, some AHK scripts which interact with this file (for example the F1 hotkey of SciTE4AutoHotkey) no longer work

I don't like this change, it basically entails to severely crippling the CHM file. Is there any way that the standard CHM sidebar/etc could be preserved?

[Ragnar-F]

Your main problem is command.help.$(file.patterns.ahk)=$(CurrentWord)!$(AutoHotkeyDir)\AutoHotkey.chm in platforms.properties. Am I right?

What do you think about receiving the possibility to replace it with:

command.help.$(file.patterns.ahk)="hh.exe" "$(AutoHotkeyDir)\AutoHotkey.chm::search.htm#$(CurrentWord)"

and setting command.help.subsystem.$(file.patterns.ahk) to 2 instead of 4 inside ahk.commands.properties? I can give you the modified CHM file for testing purposes, if you want.

Apart from that, the functionality of the JavaScript sidebar is almost identical to the CHM sidebar (except the favorite tab which nobody is using), so I see no "severely crippling".

[fincs]

It's a breaking change. The old method wouldn't work for newer help files, and the new method wouldn't work for older help files. CHM files are supposed to be openable directly within an application using the HTML Help API (which is what SciTE and Ahk2Exe use to open the help file). It shouldn't be necessary to rely on an external tool (hh.exe) to do it.

The way I see it is that a sidebar was developed so that the online/web browser version also has a sidebar just like the CHM version. It shouldn't have been necessary to change how the CHM version works since it already had a working sidebar.

[Ragnar-F]

It's a breaking change. The old method wouldn't work for newer help files the new method wouldn't work for older help files. CHM files are supposed to be openable directly within an application using the HTML Help API (which is what SciTE and Ahk2Exe use to open the help file).

Apparently only for these two programs. For example AutoHotkey.exe itself opens the Welcome page via hh.exe. The right-click menu item 'Help' or menu bar item 'User Manual' runs AutoHotkey.chm directly.

It shouldn't be necessary to rely on an external tool (hh.exe) to do it.

As far as I could check (Win XP/7/10), hh.exe is pre-installed on every windows version supported by AHK. Both methods, API or EXE, have the potential to be removed in future versions. In that case I think hh.exe would be easier to install than a Windows API to get it work again, if it's still necessary.

The way I see it is that a sidebar was developed so that the online/web browser version also has a sidebar just like the CHM version. It shouldn't have been necessary to change how the CHM version works since it already had a working sidebar.

The goal is to slowly get away from CHM. Microsoft has given up the CHM principle for years. It's just outdated. Currently CHM runs on IE11 thanks to the X-UA-compatible meta tag, otherwise it would be IE7 by default, which would cause some problems. But since they stopped developing IE11 and releasing MS Edge, it's only a matter of time before IE will be fully removed from the system; at the latest then we will lose CHM forever.

Roughly speaking, at some point the next step would be to abandon CHM and to bundle and present the documents in a different way (self-made browser or something like that, I have no idea).

[Ragnar-F]

The keyword search via HTML Help API works now, but with the side effect that the CHM file is around 47 KB larger.

[Lexikos]

I think you've done well, but like fincs (and despite having done work toward it myself), I'm not really sure that this was needed, or a net gain.

There is a small but noticeable delay between page loads which is not present in the original CHM. If this is to do with scripts, I imagine it will be more noticeable for users with slower systems. If the side bar is being reloaded each time, perhaps this can be avoided by using frames (at least for the CHM, where it's not necessary for the overall document "location" to accurately reflect its content).

In Search, the first time I press the Down key after focusing the search box, it scrolls down, putting the selected item out of view. If the result list is focused with the keyboard, there's a focus rectangle around the first item which does not follow the highlight.

Why did you change the code box style? The "Select code" and "Download code" links are unimportant; having them left-aligned adds noise to the document. Having reserved (white) space at the top pushes the content away from the text above, which is often describing the code. I dislike the "hard" black (or dark grey) borders, though that's probably just personal preference.

I don't think the "Select code" link is really useful for the syntax blocks. Is it that hard to select (usually) one line of code? Having it at the top especially calls out "this is code!", but it often isn't valid code; it is pseudo-code showing the syntax.

The index seems to work better than before, retaining its state between page loads. (y)

It probably doesn't make much sense to show the anchors on each heading (or treat each heading as a link to itself) within the CHM (but having it in local HTML can be useful for me).

If I do a search, it forever wants to highlight that phrase on every page I load, even after clearing the search box. I generally don't ever want words highlighted, but I can live with it on the initial navigation via the search sidebar (as per the original behaviour) if others find it useful.

Maybe it's just me, but I think the toolbar stands out too much, especially in contrast with the typically white window menu (and in my case, white title bar) and white page background.

It shouldn't have been necessary [...]

Since when was our target just the necessities?

Personally, my only issue with the standard side bar is that Ctrl+F doesn't work (you have to focus the page first); but that's easily fixed with a hotkey. I don't like the way the old search works, so I don't use it - I find the index to be much more efficient - but I might use the new search.

[Ragnar-F]

There is a small but noticeable delay between page loads which is not present in the original CHM. [...] perhaps this can be avoided by using frames [...]

I've changed the CHM to use a frame. I've also optimized the code to improve the JavaScript processing performance even further. There should be a significant improvement in load time when opening the sites (at least most of them).

If I could, I would also use these frames for the online help, but there're too many restrictions like the cross domain violation on local use in some browsers or the missing location change in the address bar as you mentioned already.

In Search, the first time I press the Down key after focusing the search box, it scrolls down, putting the selected item out of view. [...]

Should be fixed.

Why did you change the code box style? [...]

As I mentioned before, to adjust them similar to the ones of the forum. I wasn't satisfied with this either ... nor with the old ones with the old-fashioned 3D border or the yellowed gray background (like a case of an old PC). So I've removed it, applied a "more modern" gray and changed the select and download buttons to show on mouseover (plus icons instead of text). In this case, the select button in the syntax code box shouldn't disturb anyone any more.

It probably doesn't make much sense to show the anchors on each heading [...] within the CHM [...]

You're right. I missed that while changing the code structure. Should be fixed.

If I do a search, it forever wants to highlight that phrase on every page I load [...] but I can live with it on the initial navigation via the search sidebar [...]

Took me a long time to understand what the hell do you want from me 😁 but the search highlighting should now behave like the one in the old CHM. Only links opened from the search listbox will receive keyword highlighting.

Maybe it's just me, but I think the toolbar stands out too much, especially in contrast with the typically white window menu (and in my case, white title bar) and white page background.

The one thing I have not changed. I've styled the navigation components for modern browsers, and in favor of the forum theme (as far as possible) and mobile devices. In this case, CHM is low priority. Furthermore, on Windows XP the window menu is gray - just for the record. In short: I like it at the moment. Maybe I'll change it in the future for the CHM, but I've no idea, which color would be suitable then.

The links at the top contain these new changes.

[Ragnar-F]

I've added shortcut keys with the same functionality like ALT+C/N/S in the CHM file (the german site uses ALT+I/N/S). Scripts which send keys to navigate inside the CHM work now (for example the "Context Sensitive Help in Any Editor" on the script showcase site).

Also I've added the possibility to search via URL parameter in the format docs/search.htm?q=query&m=mode, where query is the search string (case insensitive) and mode the number 1 for searching via index tab and the number 2 for searching via search tab. After then the matching site will be opened. &m=mode is optional and defaults to mode 1 (index).

[Lexikos]

I will be deferring this until the next feature update (at the earliest).

One thing this lacks that the CHM viewer normally provides is the ability to resize the side pane. I don't know how important it is to users; I only noticed because some of the index entries are now too long for the side pane on my system (125% DPI). It could no doubt be done in script, but I'm not aware of any way of saving information between sessions. The CHM viewer normally saves the size of the default side pane.

[Lexikos]

Is there some way to open help with a specific side pane focused (for use from hotkeys)?

[Ragnar-F]

I've added the possibility to change the width of the sidebar via mouse.

[...] I'm not aware of any way of saving information between sessions. [...]

Normally the CHM viewer saves the information in C:\Users\<UserName>\AppData\Roaming\Microsoft\HTML Help\hh.dat.

I've found a (maybe the only) way, which works surprisingly. The CHM viewer can read (but not write) js files outside of itself. So we can provide the possibility to use a config file on the same location as the CHM file to overwrite the initial default values. However, in comparison to before, the user friendliness is reduced, since the user needs knowledge about objects and the settings, which have to be changed manually. I've not implemented this yet, because I need to know if it's worth it.

At the moment, in my current test scenario, the user can create a file called "config.js" next to the CHM file which contains:

var config = {
  fontSize: 1.0,
  clickTab: 0,
  displaySidebar: true,
  sidebarWidth: 255
};

Is there some way to open help with a specific side pane focused (for use from hotkeys)?

Only with the method above then. clickTab would set the initial selected tab (0 is content, 1 is index, 2 is search).

[Ragnar-F]

As requested in #192, I've added a button for editing the current page on GitHub.

[joedf]

Wow. Just saw the ahkde demo. Everything is there, ahk-ish colours. Love it! works great. 👍 ❤️

[Grass-H0PEr]

Perhaps I'm missing something,

but I cannot find a navigation / menu item
to provide a way back to the v1 docs from the v2 page.

Steps :

1. https://ahkde.github.io/docs/AutoHotkey.htm
2. click V1 at the top
3. click "V2" in V1 -> V2
4. takes you to https://ahkde.github.io/v2/docs/AutoHotkey.htm

Missing the menu button
to go back to V1
eg:
V1 <- V2

---

This looks fantastic though,

excellent job!

[Ragnar-F]

That's because the v2 docs doesn't have the new sidebar layout yet. First of all, this pull request must be merged before the v2 docs gets the new layout.

[Ragnar-F]

Thanks.

[derz00]

Uhh, is everything working correctly? 😕 This clip includes all the top and left side.

[Ragnar-F]

The sidebar of the official documentation works, but it is still displayed in the old design. Check if JavaScript is enabled in your browser.

Lexikos mentioned in #192 that the script which pulls the content across to autohotkey.com appears to be not working at the moment.

I have no access to this script. Maybe an admin/mod like @joedf (?) who has access to it should check what's wrong here, if possible.

[joedf]

I think i've found the culprit? The content.js file has not been updated.
The one on autohotkey.com only has this in the file:

tocData = [["Quick Reference", "AutoHotkey.htm"], ["Usag .... "];
indexData = [["#AllowSameLineComments", "commands/_Allo ... "];
translateData = {
    "Content": true,
    "Index": true,
    "Type in the keyword to find:": true,
    "Search": true,
    "Type in the word(s) to search for:": true,
    "Hide/Show sidebar": true,
    "Home page": true,
    "en": true,
    "Change language": true,
    "v1": true,
    "Change AHK version": true,
    "https://lexikos.github.io/v2/docs/": true,
    "Edit page on GitHub": true,
    "https://github.com/Lexikos/AutoHotkey_L-Docs/edit/master/docs/": true,
    "Go back": true,
    "Go forward": true,
    "Change font size": true,
    "Print current document": true,
    "C": true,
    "N": true,
    "S": true,
    "Select code": true,
    "Download code": true,
    "Applies to:\nAutoHotkey_L Revision {0} and later\nAutoHotkey v1.0.90.00 and later": true,
    "Applies to AutoHotkey {0} and later": true
};

*shorten the arrays to display clearer, all the special functions, code, etc is missing :b
AutoHotkey.com : https://autohotkey.com/docs/static/content.js
Ragnar's : https://ahkde.github.io/docs/static/content.js

TLDR; Either the content.js did not get uploaded and replaced or another reason could be cloudflare cache not refreshing. I've found this quite annoying when I was updating the homepage's css. I had to reference say style0.css instead of style.css to force it. :/

I don't Lexikos would have forgotten or missed this file. So, I am guessing the Cloudflare cache is the culprit (they take so long to update it).

I don't have access now, but I will check this out later today.

[joedf]

Ok, finally got access... Turns it out, it was both cases... :b
I've pulled the content.js from ragnar's website to replace the one we had (we had the older version, kept it as a backup for now), that didn't change because of the couldflare cache.
So i made a test copy that refers to it: https://autohotkey.com/docs/AutoHotkey0.htm

I don't have access to the cloudflare panel to purge the cache... @ttnnkkrr would need to purge it.

[Ragnar-F]

I think i've found the culprit? The content.js file has not been updated.
The one on autohotkey.com only has this in the file:

Thanks for your effort, but as far as I can see, content.js has been updated. This can easily be recognized by the fact that for example tocData = instead of the former toc = is included. The only problem is that tocData, indexData etc. should not be in content.js!

It looks like data_toc.js, data_index.js, data_translate. js and content.js have been merged, which is no longer necessary for the new sidebar.

Therefore, I suppose there must be a script mentioned by Lexikos somewhere that does exactly that merging and needs to be adjusted accordingly. Did you find a script like that?

How did you manage that when Lexikos released a new version and updated the documentation? Do you have to purge the Cloudflare cache every time in this case? It seemed to me that such changes were quite quickly visible on the website...

[joedf]

Really?
For me, these two are still different for me.
https://autohotkey.com/docs/AutoHotkey.htm
https://autohotkey.com/docs/AutoHotkey0.htm

maybe it's different for regions with cloudflare? I am not sure... 😕

[Ragnar-F]

I see the same. They are different. You didn't do anything wrong. 😉

If the Cloudflare cache is purged, it should work for now (hopefully).

My main problem at the moment is the content of content.js, which you posted first in the code block.
This represents the new content.js after it has been processed in some way with the script mentioned by Lexikos in #192. This script must be adjusted to the new sidebar, so that the documentation will continue to work in the future.

[derz00]

it should work for now (hopefully).

For me, only https://autohotkey.com/docs/AutoHotkey0.htm shows the new changes. Clicking on any other docs pages shows without top or side bar. Maybe that's assumed... 🤷‍♂️

[joedf]

@Ragnar-F
Ahhh I see... That is a problem 😟 ...

@derz00 Yes, the second one is the new one, but the other is still on the old cache version. I only modified this one page to preview the changes. However, the true solution is like @Ragnar-F mentioned: fix the 'processor' script and purge the cloudflare cache.

[joedf]

Tank purged the cache. :)

[Ragnar-F]

I've noticed it. Thanks.

[Lexikos]

Therefore, I suppose there must be a script mentioned by Lexikos somewhere that does exactly that merging and needs to be adjusted accordingly.

That is correct. Keep in mind that the web server does not run AutoHotkey scripts. Any changes you make to CreateFiles4Help.ahk (or compile_chm.ahk if intended to affect the online docs) must be reflected in the server-side script which is triggered by GitHub's web hook.

Similarly, if the search index is built by an AutoHotkey script, either someone must run that script and upload the index each time the documentation is changed, or an equivalent script must be written to work on the server.

For now, I have merely disabled the part of the script that combines the js scripts and overwrites content.js. Now it just syncs with GitHub. I'm not inclined to spend more time on this at the moment.

[joedf]

I see.
Also, https://autohotkey.com/docs_1.0/Hotstrings.htm : logo is broken since this is missing
https://autohotkey.com/docs/images/AutoHotkey_logo_no_text.gif

Should we keep a copy in the new docs or run a replace thought all the docs_1.0/ files?

[Ragnar-F]

Wow, I didn't know this even exist 😮

AutoHotkey_logo_no_text.gif was never included in this repo. Maybe just on your server and someone deleted it. Currently, there is only AutoHotkey_logo_no_text.png.

I recommend you to create a separate images folder in docs_1.0/ and modify the links accordingly. You can find the the old images on https://web.archive.org/web/20150607030723/http://www.autohotkey.com:80/docs/. By the way, the flags are missing, too.

[joedf]

Oh shoots! Thanks. 👍

[wyagd001]

for CHM file the URL can't pass，in other words can't Locate to Specified page
for example

1. I use IE open mk:@MSITStore:N:\autohotkey\AutoHotkey.chm::/docs/Tutorial.htm
   at first time can open Tutorial.htm without sidebar, but open again or Refresh it will Auto jump to mk:@MSITStore:N:\autohotkey\AutoHotkey.chm::/docs/iframe.htm with the content is AutoHotkey.htm
   but I want Locate to mk:@MSITStore:N:\autohotkey\AutoHotkey.chm::/docs/Tutorial.htm
2. open the chm file Jump to URL mk:@MSITStore:N:\autohotkey\AutoHotkey.chm::/docs/Tutorial.htm
   it Auto jump to mk:@MSITStore:N:\autohotkey\AutoHotkey.chm::/docs/iframe.htm with the content is AutoHotkey.htm can't Locate to /docs/Tutorial.htm

[Ragnar-F]

#208 will fix this.

... at first time can open Tutorial.htm without sidebar ...

I can't do anything about the fact that IE loads a CHM page for the first time without sidebar - IE in conjunction with CHM seems to have the quirky behavior of ignoring any JavaScript at first startup.

[joedf]

Hi there, really late reply on this, but I've fixed the images on the v1.0 Docs
https://www.autohotkey.com/docs_1.0/

Turns out the images files were there. They were just not referenced (were using absolute paths instead of relative) correctly.

[Ragnar-F]

Thanks, better late than never 😉