Raising the Anchor

Today’s bit of coding was fruitful despite my dreading it all throughout the day. Going to bed extremely late for the last two days (coupled by getting up early both times) and setting up Christmas decorations made me want to curl up in a little ball under the table with Walter and go to sleep. However, I virtually signed a probably not legally binding contract, and so coding will (and did) happen.

The changes for this evening include some extra code for helping during testing as well as adding in the ability to navigate between anchors in the current help document. This time around, lets show what’s new first and then talk about it second.

Sample Anchor Navigation

Sample Anchor Navigation (Animated GIF)

What we see here is first the source help file, showing where all of the hidden anchors are located, followed by switching to the visualized help file and navigating through all of the anchors in the document. As seen here, the cursor jumps to the next or previous anchor in the document regardless of it’s status depending on which key you press. Note that this is an animated GIF, so you may need to click on it to see it animate.

In order to get this working I also slightly revamped the post processing for anchors as well. The first thing you might notice is that the hidden anchors are no longer visualized for debug reasons, since it’s now possible to see them by navigating to them. The other major change is that it now also preproesses standard anchors as well.

In particular, the original version would capture all of the hidden anchors along with their locations since it would be impossible to find them later. The new version still does that, but the list of regular anchors is also added to the setting as well (and the list is sorted into document order), and the setting name is changed to reflect that it is now just navigation items in general and not invisible navigation.

This simplifies the logic for determining where the next closest anchor position is from the current cursor location, since it can just look at a single list of items and not have to find the closest item in two of them and then check to see which one is closer. Something like that will have to happen in the future for determining if a link or anchor is closer when jumping between those items, but I like the clarity of having all of the anchors available in one place anyway.

Something you might not notice at first glance is that there are now some syntax specific view settings bundled in that turn off various aspects of Sublime in order to make the help viewing more generally useful. This includes things like ensuring that the fold icons are not visible and that selecting text doesn’t show you other places in the buffer that contain the same text, since those tend to clutter up the view when reading help.

One last bit of new business is that for the purposes of testing, it’s very helpful to reload the help buffer on code changes to see what effect the changes had. As a result there is now a new command for reloading the current help file. The smartness of the help display code not reloading a file that it’s already showing you gets in the way here a little bit.  The easiest way to get around this is to have the command that does the reload first alter the settings in the help view that tell it what file it’s currently viewing to “trick” it into loading the same file again.

Something important to note here, both for the key binding on this command and also on the new command for navigating inside the help file, is that if you’re in the process of editing a text file, the key bindings that you have applied will also apply to the view you’re editing. That means for example that the Tab key doesn’t do what you think it does while you’re editing help text.

The answer to this is to include an on_query_context() event listener to provide some custom key bind contexts that our key bindings can use to determine the exact state of things. In this case there is a single new context that can tell you if a view represents a visualized help file or a help file that’s being edited, so that you can tailor bindings to when you’re editing help or viewing it.

That is a bit of cross over between the core help code and the authoring tools that will eventually be created, but although those will be eventually separate code bases, some support for that has to be shipped in the help code itself.

That brings this third day of Devember to a close. The next set of code changes will introduce the code that lets you actually follow a link to another location in the document before we skip ahead into handling the overall help index that tells the system what help files exist and what they contain.