Checking the help belly button

A few changes were made today, but due to an early appointment with the blood letter in the morning, this devlog post will be short and sweet and more to the point than they usually are when I say they’re going to be short, but really they’re not.

That’s not a very auspicious start, but they say that an image is worth a thousand words, so here’s one showing the biggest change made today.

Simple Help Lint

Simple Help Lint

This shows that there is now a crude system in place for checking help for problems (i.e. “linting”). This is still fairly crude in that it works, but the code could be refactored and cleaned up. It’s more a proof of concept that will come in handy in the next little while.

Currently the only problem that it can find is links in help files that refer to anchors that aren’t found in the help index for the package. Later this can be extended to other situations, such as being able to tell you if the index and the list of help files in the document root doesn’t agree with each other, or possibly if there are things that look like links but aren’t because you used a space instead of a tab.

In use the command can be triggered either on a help file or on a help index, as long as the file is rooted in the Packages folder and the package itself is contained in the help index. When used on a help file, it will check just that file, while on an index it will check all of the files that exist in the help index for that package.

When I’m working on help, I often generate links to topics that don’t exist yet as a reminder to myself that they should be added, so this will allow a help author to do that and then later on find out which links don’t have anchors yet, which can help you fix problems as well as guide you along what else you need to add to your help.

Apart from the linting there is also a hover popup that triggers when you hover the mouse over a link in the currently displayed help file. The popup will tell you the caption on the topic that is being linked to and will also tell you what the link does: navigate to a help file, open a url, or open a package folder. There is also another popup that is used if the link isn’t known in the index.

Like the linting code, this is still pretty crude since the idea is to have the functionality first, decide what it should contain, then worry about making it look pretty. As a back end kind of guy, making things look pretty is not my strong suit.

Speaking of which, the last of the changes made is to the command palette and menu, where the authoring tools are now stored under Tools > HyperHelpAuthor and the top level HyperHelp menu has been replaced with Help > HyperHelp instead. The more I worked with this and thought of it, the more it seemed like it was obnoxiously in the way and would probably be annoying to people that only have a couple of packages installed that support help.

Well, that worked out to be pretty short indeed. Impressive.