As promised yesterday, today’s update is chock full of a complete lack of any sort of stunning visual flair, since everything revolved around working with the code for loading up help index files, which is the first step in being able to jump to links in other files. Some of the development time was spent in hashing out the format of the help index that I want in order to be able to provide the data needed at run time.

Since the code is only a few dozen lines of code, this entry will talk a little bit about how the help system is going to tie together instead.

One of the main goals of hyperhelp is to easily allow packages to provide support for help by just including a few files in their packages (and going forward also including a simple script snippet to bootstrap the system, but that’s a topic for another discussion). Part of this will be the inclusion of a help index file that provides all of the meta information about the help in the package.

The general idea is that everything we might want to know about the help in any particular package should be contained in the help index, with the exclusion of the help text itself. That means that except for the loading of the help index, no run-time discovery should be needed to figure out what’s available and what’s not, since that could conceivably be a lot of processing if a package contains a lot of help files.

So the help index file contains meta information about the help from any particular package as well as a list of all of the files that make up the help there and what topics are available inside of those files. Currently such index files need to be hand created, but some authoring tools will be worked on later that will perform the heavy lifting of keeping the index up to date as help files are edited.

The meta information includes a description of the package itself for use in various display locations as well as a path inside of the package that the help files are stored in for ease of access. Also provided is a list of the topics in the help that should be presented as the table of contents should the user ask for it. The table of contents will default to a list of all possible topics if it’s not specified.

The actual help files themselves contain a textual name that describes them (similar to the overall package description) and then a list of all of the help topics (i.e. anchor names) that they contain, along with a caption that describes what the help topic is about.

For simplicity, the index file needs to be named hyperhelp.json and can appear anywhere inside of the package. Using the sublime.find_resources() api function, it’s a simple matter to find all of the resources with this name and load and decode them, providing us with a quick list of all of the available packages that include help.

Currently just the code for loading a specific index file is implemented, although extending this to all index files is a fairly simple process. The loading code verifies that the structure of the help data is what we expect it to be so that code further down the line can work with the help index data without having to worry about things.

Still missing is the ability to load and validate the table of contents, as this uses a special shorthand notation that is mostly similar to the overall help data index. The difference is that the table of contents information can include a hierarchy that the user can browse through, allowing you to specify as simple or as complex a topic layout as you see fit.

Once the index fully loaded, following a link changes from looking in the current buffer for an anchor that matches the link text to querying the index to see if an anchor exists somewhere. If it does, the lookup implicitly tells us what help file the topic is in, allowing us to load that help file and then jump to the appropriate location. This is why our help display code silently does nothing if you tell it to display a help file that it’s already displaying.

As of right now the index loading code is almost complete. Once it’s done work can commence on some new API functions for looking up where a help topic is defined (if any) and then following it if needed.