As much as I would like to put this off for just one more day, today I finally got into some serious usage of the package and tools that I’ve been working on the last couple of weeks (or longer if you count that this is a re-working of a previous re-working of an initial prototype) to get a better sense for what needs to be added apart from the things that I already know are missing.

This being Devember, I had to squeeze a little actual development into the mix to fulfill my quota for the day, and so in that regard I have reworked the code from last night to be less brittle.

The code in question is regarding being able to immediately load and open a new help index once it has been created. I really didn’t sit right with me that there was a time delay in place just to make the index load work as expected, even temporarily. While I was out on my morning walk a fairly simple fix occured to me.

The real underlying problem is that it takes Sublime some non-zero amount of time to notice that new package resources are available, and so immediately after creating a new index the existing code for reloading the indexes can’t work because it can’t see the new file yet. However just because the file isn’t something that Sublime knows about doesn’t mean that it’s not actually there.

I set out to make some quick modifications to the code so that help indexes and help contents can be loaded from a file in the package folder as well as via a resource specification, allowing the help loading code to bypass the Sublime resource mechanism entirely and just get at the content of the file. Normally you don’t want to do that because your package could be packed, but in this case we know that this is not going to be a problem.

This change is fairly easy if you include the restriction that in order to load a local file such as this, the file needs to be an absolute file path that points directly at a file inside of the Sublime Packages directory. That way you can very easily throw most of the file name away and end up with the resource specification that the file would otherwise have, which makes the whole thing transparent.

I started with making this modification for loading the index file, since at the very least the core should recognize that there is a new help package available. An optimization here is that once the new stub is created, instead of calling the reload function to re-scan and reload all help indexes, the command instead directly loads just the newly created help index, followed by manually inserting it into the global package list. From this point forward, hyperhelp now knows that the packaged help exists and can’t tell that it was done any differently.

I was going to implement similar code for loading the actual help content itself, but I ended up spending a fair amount of time investigating and discovering that Sublime seems to load a resource that you tell it to load even if it doesn’t yet know it’s there. Logically that makes sense; why would the loading code first check to see if the file exists in some internal structure, when it could just see what happens?

I’m not completely sure that this is expected behaviour, but for the time being I’m willing to run with it because the fix will be just as easy as it was for the index file, and this gets rid of the kludgy timeout value. There is also a fair amount of refactoring and clean up that could go into the authoring code anyway, so this can wait until that happens.

The remaining changes for the day are all related to documenting what’s been done so far in the internal help for the package itself. As such I’m not going to go into any further detail on that; if you’re interested you can go ahead and just look at the help files in the repository. I will however say that I made quite a few notes on things about the authoring process that could be tweaked, fixed or added.

While some of the items where things already in the works, I also thought of some extra enhancements for a few and located a few places where things are not working quite as well as they could. In the spirit of actually writing help, I left those sorts of changes alone to just focus on writing.

Tomorrow will likely be more help work, although I also have a few fairly simple code additions for some new features that have been waiting on there being more substantial help in place.