It’s almost the half way point of this year’s Devember project and I think some significant progress is being made. Today’s coding session includes twelve commits and a useful enough set of help authoring commands to actually make editing help files not a chore. Of course, twelve commits is not really all that much in the grand scheme of things since I tend to commit like a mad fiend in order to better track changes that are in progress, but you can’t argue with progress.

For tonight, an overview of what is now possible with the integrated help authoring tools.

I’m going to start first be reiterating (for what, the 12th time I guess, since it’s December 12th?) that ultimately the code in this repository is going to be split apart into a core help package (hyperhelp, in this repository) and into an authoring package (HyperHelpAuthor, whose repository is currently private). For the purposes of developing things during this project, the code is mingling together in a single “Package”.

One of the things that happened today was to do some refactoring and splitting to end up with two unique resource directories, one which will be part of hyperhelp itself and one that will be a part of HyperHelpAuthor when the time comes. More work will have to be done on this later with regards to hyperhelp once it’s time to turn it from a package to a dependency, but I’m not sure if that will happen during Devember or not.

That aside, there are now some new authoring commands to go with the one that was created yesterday, which I tweaked a little bit today to flesh out what it should do a little better. Before getting to a list of the commands added, I’d like to first point out a common design pattern among all commands, with regards to arguments and how the commands generally function.

Since it’s possible that multiple packages will have help indexes, authoring commands need to know what package they’re supposed to be operating in. I went over a few design ideas about how this would be most seamless and what I came up with was the idea of the command taking an argument that tells it what package it should be operating in.

That argument can be the name of a package, in which case the command operates on that package directly. If the argument is None, then the command checks to see if there is a help view active in the current window. If there is, the package from the displayed help file is the one that’s used in the command. If there is still no package, then the command has no choice but to prompt you for the package to work in.

In addition, there is also an argument on these commands that tells it if it should always prompt you for a package no matter what, which defaults to False. If it’s set to True, the package that you pass to the command is ignored and you always get prompted for a package.

This seems like a pretty good mix because in all likelyhood you’re probably working on help for one package at a time (or one per window, anyway). So once you start working with help from a package (requiring the tools to ask you which you want to work with), all of the rest of the commands you use will just transparently start using the same package without having to ask you.

With that out of the way, here is the complete list of authoring commands that are currently available (including the one added yesterday and the couple that previously existed):

1. hyperhelp_author_update_header
   • If the current file is an editable help file that contains a %hyperhelp file header with a date key that specifies a date that is not today, this command will update the date in the key value with the current day’s date. An authoring tool setting can be turned on (on by default) which causes this command to trigger every time you save a help file, so that the date header is always up to date
2. hyperhelp_author_create_help
   • After selecting a package, this command prompts you to enter the name of a help file, then creates a new stub help file for you, set to save with the appropriate name inside the help directory for the given package. This makes sure that the help path exists, and uses a snippet on file creation to allow you to easily enter the title of the help file; the date defaults to today.
3. hyperhelp_author_edit_help
   • The analog to the above, after selecting a package you will be prompted via a quick panel to select one of the help files that are listed in the index of the help index (along with help file title), and the help file will be opened for editing.
4. hyperhelp_author_edit_index
   • This works similar to the above command, only after selecting a package the associated index file will be opened for you to edit.
5. hyperhelp_author_reload_help
   • When invoked from inside of the current help view, this reloads the help file currently in the window to pick up any changes that may have been made since the help view was first opened.
6. hyperhelp_author_reload_index
   • When invokes from inside a help index file, this causes the underlying help core to reload the help index for this package to pick up any new changes (such as if you added new files). If the help index is for a package that has not yet had it’s help index loaded, all package indexes will be scanned again to pick up the new index.

Note again that above where it says “selecting a package” this refers to the command trying to do it’s best to infer the appropriate package and only actually prompting you to pick one if it’s not sure.

Notably missing in this list is the ability to add a help index to a package that doesn’t already have one, which you might use to start creating help for your package. That requires a little more ground work so that it can prompt you with the list of packages that don’t already have help, and is less interesting  in the short term.

Additionally, some extra functionality like automatically updating the index when a new file is added or automatically populating the topics in the index by reading them from the help file are also on the road map but likely won’t happen during the Devember time frame.

One final note is that the above editing commands currently only work on help files and indexes that are present in the Packages/ folder (that is, not a part of a sublime-package file). That will be remedied in the future, but editing such a file would inherently create an overload of the package file, so a bit more thought and work has to go into making that work seamlessly.

I have a couple of other incidental changes to make tomorrow to enhance things a bit more, and then I will start actually documenting what’s currently possible and what is not. That will be the first real test of being able to use the authoring tools to successfully author something, so I’ll be able to tell what obvious omissions there are (apart from those mentioned above).