Another case for external help topics

I’m not sure why these days keep ending up so late, so please excuse the potential curtness of this devlog entry (I always think they’re going to be short but I can’t help but be verbose, even when I’m describing how I am verbose when I think I’m not going to be; sad, really). Tonight’s achievement is the inclusion of the ability to open external files and web URL’s from within a hyperhelp help document.

There is a nifty animated GIF after the fold that shows this off and everything (remember to click to view).

Opening external help sources

Opening external help sources

In order to pull this off, the core is able to detect when the help file associated with a particular topic is a web URL or a package file specification, and if so it handles them directly instead of allowing the help loading code to try and open the file as a help file.

In order to make this operation speedy at run time and to constrain error detection to just at index load time, the index loader has a new dedicated section in the help index for defining external help references. When the index is parsed, the two sets of topics are merged together, but all of the logic of ensuring that the external resource is in an appropriate format happens only once.

Additionally when the index data is loaded, the unique set of each kind of external resource is cached in a list so that at runtime the determination of the type of the list is as simple as checking if an item is in a list or not. That way there are not a bunch of regular expression tests being done for potentially no reason every time a link is followed, for example.

The code still needs a little bit of cleaning up, though. For example it’s currently using a list for the unique external resources when it should probably be using a set to save the hassle of checking if the item is in the list or not. While I was working on this I discovered a little bug in which the topics that are inserted into the global topic list aren’t properly case folded, although topic lookups are case folded.

As a result the case of the link text in the help document doesn’t matter, but if you happen to make a topic with any upper case letters in the index, the system can’t find it. That had me confused for a little bit until I realized that the only link that this was failing for happened to be one that had an upper case topic in the index.

Finding and fixing that took up the remainder of the development time I allotted for tonight, plus a bit more because it’s currently about an hour past my bed time.

One last big feature to try and put into place is being able to navigate through the history of topics that you have visited. That will be the task for the next couple of days, which I think brings all of the major items to the table with regard to features in the core that I originally planned on creating. Once that is finished I can move into some code cleanup and documentation again.