A little bit of history (repeating)

Terrible Propellerheads puns notwithstanding, today’s changes are some visual tweaks to the menu items that appear for hyperhelp along with a few small structural changes and a bug fix. These changes encompass a little over an hour and a bit of work overall as I contemplated how exactly I wanted to structure things. I was going to do a bit more including some refactoring, but I forgot that this evening was a building party in my gated community, so time was at more of a premium than I had anticipated.

The first thing done was to remedy a bug that I noticed back when I was authoring help but didn’t bother to do anything about until now, since I was in the vicinity and it was a handy thing to strike off of the official task list.

The code for double clicking on a link to follow it works by using an event handler to see if the command for selecting text by words is being executed, since that is what happens when you double click on text. If that’s the case, it checks to see if the cursor is on a link in a help file, and if so it follows the link and then blocks the selection event.

An issue with this is that the navigation command is smart enough to only execute if it’s run in the help view, and otherwise it disables itself. By itself that’s not a big problem since you don’t want to try and follow links in non-help documents anyway. However the test for checking if the double click is a link on a help file triggers not only in an actual help file being viewed, but also in a help file while you’re authoring it.

That means that while you’re editing help text, if you try to double click to select link text, nothing happens; the command gets turned into a link navigation command that does nothing because it’s not enabled.

The fix to that is simply to perform the same check as the key context does to know if you’re pressing the key in a help file that’s not being authored, which is currently to check if the buffer is read only or not. With that check in place, double clicking on links in help files that are being edited no longer trigger the link navigation and all works as it’s supposed to.

The other big change is that the variant of the navigation command that is used to follow history is now presented in the menu, and it has a description method that causes it to tell you what direction it’s moving in and what topic it would go to in that direction (if any). Since the command is in the menu without an explicit caption, the menu text comes from the description, which means that the items will not only perform the navigation but also tell you where they’re going, which is nice.

An issue with this is that the navigation command was defined as a TextCommand, which means that it gets invoked on a view by view basis. For the purposes of navigation by key bindings, that’s exactly what you want. However for having the menu item in the menu, it’s less desirable. The check that the command does to enable or disable itself was based on the view it was invoked in being a help view or not.

If the command is in the menu, it’s visible even when the current view isn’t a help view, which means that unless you’re in the help view the help navigation items will be disabled. Technically that’s fine, but I see no reason why someone might not want to navigate the history of their window even if the help window doesn’t have the focus.

One way to fix this would be to have the command enable and disable itself based on the presence of a help view instead of checking it’s own view. While doable, that requires the command to also execute itself on the help view and not on itself, and in that case it makes no sense for it to be a TextCommand when it could be a WindowCommand instead.

I made that change to the code, and also added in something experimental so I can see how it grows on me. The history commands were displaying themselves with a caption that tells you the package that they are going to navigate to, but other commands like table of contents and index do not.

As a test I created a command that is always disabled and whose caption tells you what package the current help file is contained in. With that command in place and added to the menu, all of the items implicitly tell you what package they’re working with.

I’ll have to play with that a bit and see how annoying and wrong it strikes me for there to be a permanently disabled command in the menu. Also there needs to be a bit of a change to the history captions, since they should also probably tell you when the history is going to navigate out of the current help package.

That’s something to play around with tomorrow, though.