At the end of this first day of Devember some code and syntax files have been written, and I’m reminded (not for the first time) that I should really stop working on coding a bit sooner because I always forget to leave time for the development log part.

In any case, as this is the first day of Devember this log should probably start off by explaining the project goals a little more.

The idea behind the hyperhelp project is to create a minimalistic system by which Sublime Text package authors (or at least myself) can easily implement context sensitive help for their packages directly from within Sublime itself. The idea came about while working on my own package (OverrideAudit), where I really wanted to be able to have a simple key binding or command that you could invoke to get more detailed information about what you’re currently looking at.

Although the ability to load up text and display it is inherently very easy in Sublime (it is a text editor after all), it seems like that would be useful for other packages as well and duplicated code is somewhat abhorrent to me. So it seemed like a good idea to write it once and just use it in multiple places, and the original idea was born.

Another important aspect of hyperhelp is that the help should be (as much as possible) purely text based and as minimal as possible. Although Sublime supports the display of HTML in some places (phantoms, popups), that is less than stellar when it comes to help text because you can’t search within it or copy and paste the text out if you need to.

The key aspects of help that I’m shooting for here are:

• The ability to mark specific portions of the help as an interesting navigation point, such as the destination of a link or just for quickly skipping through topics in a single help file until you find the one you want
• The ability to follow a link from one help location to another, either within the same help file or by jumping out into a new help file altogether
• Navigation history, allowing you to go forward and backward through the list of help locations and topics
• Table of contents for a help package as well as an index of topics to find what you need quickly
• Simple markup that doesn’t get in your way (i.e. people should be reading your text, not parsing markup in their head)
• Simple ease of integration by package authors (such as myself)

With that in mind, here is a representative sample of what has been done so far:

The two main concepts at play are the idea of anchors and links. An anchor is any location in the buffer that is interesting enough that someone might want to jump there, while a link is just a means of getting to an anchor from the current location. The ultimate destination of most links would be an anchor (although they can also open files and web pages as well), but anchors are useful for navigation in general such as skipping between headings in a document.

For the first day, a simple syntax is in place to provide these two key concepts, along with the ability to actually display some help. Although the syntax will be enhanced as the project moves forward, this small portion is essential so that the glue code that will work with the help is able to properly detect the structure of the document.

I will discuss how that works in future blog posts as features are developed. For now I think the code and syntax will speak for themselves as simple examples of what’s going on. There is nothing earth shattering going on, but even the most exciting things have humble beginnings.

One last thing to note before I slink off to bed (well past my bed time) is that the layout of the files in the repository is currently a bit loose in order to better support more rapid development. Sublime only automatically loads plugin files from the top level of a package folder, so while there is a lot of development going on it seems like a good idea to keep the structure as flat as possible.

I say that with apologies to people that look at the plugin files laying in the top level directory and automatically cringe. I assure you, I’m one of them.