gilch
commented
1 year ago Diataxis has influenced my thinking about writing docs. I'm renaming some things. The tutorial is now the primer. I'm moving a lot of the Whirlwind Tour examples to the API docs where possible. Should be the last quarter or so. That means putting them in the source docstrings, which will have to get longer. The end of the Tour will then refer to those, perhaps using Python's help() builtin. Changing context like that isn't trivial. Parts may have to be rewritten/reformatted. It will take time.
I think at least some of the macro tutorial should be in a "cookbook" section (with the remainder perhaps renamed "macro primer"), along with some ideas from the old FAQ and the wiki, although I wonder if some of that wouldn't be a better fit for the discussions here on GitHub. Discussions are easier to get started, but harder to maintain as the language evolves. Probably outdated entries there will be marked outdated and abandoned rather than fixed. Maybe short ones start out in discussions, and important longer ones get moved to the cookbook.
Feels like it's about time again. Improvements since last time #144 are significant enough to warrant a new release.
Hissp has mostly stabilized. I rarely need to touch the .py files in the Hissp package proper. The bundled macros have had some recent volatility, but #154 and the associated wiki page has helped me to select and implement a set balanced between minimalism and utility.
Most of the recent volatility has been in the docs. Rather than adding anything new right now, I want what's already there to be as accurate as possible before the release, which means a lot of proofreading. That gets to be tedious, so it's taking time.
I'm not totally satisfied with how reader macros handle extras, but don't have a better idea right now. The release will have to happen before any deeper changes there. I might want to address some of the parsing quirks #149 though, at least where I have a clear idea of how it should work.
I don't think the next release can be the 1.0, although it feels like that's getting close now. Maybe the one after that. I may need to write some bigger applications in Hissp 0.4 to see where the pain points are. This would, of course, take time. More examples from the community would also be helpful here.