All of the late nights are catching up to me, so in an effort to get to bed before midnight for the first time this month, I’m going to endeavour to make this a shorter development log entry. Saying that hardly ever works, but I’m throwing caution to the windows and immediately jumping to this exciting animated GIF of the major excitement for the day.
The culmination of a bunch of furious coding as well as semi-furious back of a napkin API design is the outward ability to do what we used to be able to do before, only now the command to follow a link is capable of looking up the destination anchor from within the help index instead of assuming it exists inside of the current help file. Arguably this makes the whole thing at least 100% more exciting because there are now 100% more sample help files than there used to be.
I started off with a clear idea of the API that I wanted to implement (namely the ability to load and reload help index files, help content files and search for an anchor in an index) but spent a bunch of time trying to think of a good way to lay everything out. I’m not really there, but I decided to leave things as they sat so as to get on with actually accomplishing something for the day.
Mainly my idea is that there is a set of internal functions that are not really meant to be touched by the outside world and then a core set of exposed “public” API calls that do everything that is needed (hopefully).
At some level the module layout that would be best for this (as far as external code is concerned) is not quite possible currently because I’m holding off on including submodule folders in the package for as long as possible. So currently a fair portion is basically an external wrapper around an internal function of a similar name.
Part of the issue is trying to lay out the source files so that they don’t have circular dependencies between each other, a situation which causes some minor headaches. Another is trying to not end up with only a couple of monolithic, large source files and instead trying to lay things out in a few more tightly focused files instead.
The clean up of the structure of the code (shifting existing code between files) is likely something that will happen as things progress and the final destination seems a little bit more clear, but for now I’m relatively happy with it.
Internaly the API is meant to cover two main areas. First is that hyperhelp itself needs the API to perform all of the tasks necessary to operate the help system, such as finding what packages have help indexes, loading and reloading them, displaying and re-displaying help content and navigation The second is the public facing part.
Here the idea is to try and come up with a rich enough subset of the internal code that covers everything that something outside of the core might want to do without exposing so much that it’s harder to change things up in the future. In particular although technically speaking you could argue that either nothing is required to be public or just commands for displaying help should be available, there are third party packages to think of.
The most important of those would be the help authoring tools, which need to be able to work with the internals enough to be able to helpfully allow you to edit and work without needing the core to do any heavy lifting for them. For example, there is an API function for getting the global list of cached help index information that the core is using, but functions are also available for ad-hoc loading of resources as well as being able to maintain a separate list of loaded packages if desired.
This sort of design consideration frees up the core to say “these are the things that I’m going to do by default, but here are some extra lego bricks in case you need to build on this for your own external needs”. This is a sort of tight rope walk in that until you get into the bowels of actually writing a third party tool to manipulate things it’s hard to predict what might be needed, not to mention being able to draw the line where that’s just not a feature you can have.
I’m not fully sure yet what the weekend is going to hold as far as coding is concerned, since those are typically fairly busy days. I’m thinking that some work in displaying the table of contents and overall help browsing would be nice, as well as actually implementing some commands for the package in general. I’ll definitely get time put in, although it might be code cleanup or features that have no immediate external visibility right away.