Today’s changes bring us closer to the goal of being able to more easily author help files for packages. This includes some syntax changes to make things look a little nicer as well as some changes to the presentation of help files in general and a fix for a bug that took a little more time to locate than it should have.

I didn’t get quite as much time to work tonight as I wanted to due to some other stuff going on, but on the plus side there is an image to show what the new changes look like, and it’s not animated (so maybe double plus)?

Something that makes authoring help files a pain in the butt is that they are a lot easier to edit if the syntax for the buffer is set correctly, as you then can visually see what the help looks like a little better. This is complicated by the syntax being hidden, requiring you to know how to manually set the syntax of the buffer via the console.

That’s great for me but not so helpful for a lot of people, and generally a giant annoyance for all. Generally one would assign the syntax based on the extension of the file, but since help files are supposed to be simple text, that seems like a bad idea in general. Instead we now rely on a first line match in the file to allow Sublime to detect that a text file is actually a help file automatically.

To do this, the first line of the file must start with the text %hyperhelp, which uniquely marks help files for what they are (unless you’re writing something really weird, I guess). The header line may also contain one or more key=”value” style pairs to pass meta information into the help system.

Since such headers would be ugly, there is now some post processing on the buffer that starts with detecting such a header line and replacing it with something nicer looking. To do this the parser looks for the special keys title and date, where title represents the title of the help document (generally what you set for it in the index, but it doesn’t have to be) and date being a YYYY-MM-DD style date which indicates when the last time was that the help file was modified. A future change will allow the authoring tools to update this automatically.

With the header parts parsed out, the first line is replaced by a header line that contains the name of the file as an anchor on the left, the date on the right and the title of the document centered between the two of them. The header is followed by a separator line to make it more visually distinct, and the syntax recognizes all of the parts and highlights them as appropriate.

The anchor being in the header allows you to create help links that open files by name if desired, along with providing contextual information as to your current whereabouts in the help system.  In order to facilitate this, the help index loader now ensures that a help file appears in the topic list under it’s own name so that it is always possible to open a help file by specifying it’s name as a target.

The date format in the header can be chosen by the user. There is a default value that is used if you don’t have a setting set, or you can change it to your preferred date format. The setting goes inside of your general user Preferences.sublime-settings file because eventually hyperhelp will be a dependency and not a package that you can easily configure.

I also fixed an inadvertent bug that I didn’t notice prior to now due to chance circumstance. The code for displaying a help file scans for all hidden anchors and hides them by making modifications to them, which requires changing the selection (cursor) location as it goes. Thus at the end the cursor is left wherever the last hidden anchor was.

In this case it used to be always at the top of the file, but with headers in place it leaves the cursor at the hidden anchor location. Generally this would not be noticeable because this would usually be followed by jumping the selection to somewhere else anyway (to navigate to a topic). That’s not the case when a help file is reloaded, though.

I must admit that it took me a bit longer than it should have to realize what was going there, which I’m going to ascribe to the lateness of the hour. In any case, it’s fixed now and so authoring enhancements can continue tomorrow evening unencumbered.