 I've been thinking about documentation lately. I'm writing all these notes on the permacomputing wiki about would be an ideal resilient software or hardware. And uxn roms most often than not will fail these checks. One thing that I hate is that, if you happen to loose the Noodle README, or never got it in the first place because you used a direct rom link. Then the application itself has no menu, and is not self documenting in any sort of way. 54 comments
So, I've been sketching an idea for a how the Hundred Rabbits programs can spit out their own documentation, so you don't need a guide alongside the program file. My plan is to automatically populate a graphical menu from those, route keyboard controls directly to the menu tree, and spit out a plain-text README directly into the console on launch. https://git.sr.ht/~rabbits/nasu/tree/main/item/src/manifest.tal I've implemented the app manifest in #uxn, which effectively blocks me from sneaking undocument features since the key handlers MUST go through the menu tree. Upon launching any app now, it will print the manual in the console, next step will be to draw the menu tree inside the application and make it navigable, a-la Macintosh. I was partly reticent to moving ahead with this thinking it would be a pretty big overhead, but in the end it simplifies controls-routing a lot, and for a very little overall cost. nasu.rom(before): 6586 bytes   @neauoire I'm meh on the printing readme to the console on launch part, but having the apps be learn-able just by exposing the controls visually is, I think, an excellent move. @tty it will go away once I figure out how to draw the menu inside the application. It'd be redundant to have both, especially since it's a graphical app :)
[DATA EXPUNGED]
[DATA EXPUNGED]
@bouncepaw I hope so! I'm trying to figure out how to handle passing the mouse vector to the menu and back to the app in a portable way. I should have a working graphical demo later today :) Started drawing the menu tree in the application interface! this whole thing is much easier than I expected it would be.
[DATA EXPUNGED]
@bouncepaw VMs I think, like Orca is an absolute delight to program, because every tiny change bring about massive variations and it's very rewarding to just change a line or two and have a totally different program.
[DATA EXPUNGED]
@protodrew I think it's largely due to having removed all the distraction and friction from the pipeline  @neauoire That's slick. Are there plans to add keyboard navigation to that? I'm thinking of the common GUI thing on Win/Lin/etc. where tapping Alt sends you to the menu bar, and then you can arrow key through the dropdowns (or use mnemonic shortcuts) @dualhammers you might not remember this but Ronin, Dotgrid, Orca, Left, Nasu, etc.. all had menus like this: https://hundredrabbits.github.io/Dotgrid It's actually the second time that I go through that same motion, it's why it's been so easy to do, I already knew where I was going ;) It's done. Now all that's left is to display the shortcuts to the right of the label names, make pretty and optimize. It'll be a 900-ish bytes library that I can include in each #uxn project and instantly get menus with self-documenting features. @neauoire nice! I appreciate that you're putting this into a reusable library too @tty I'll try to document it well enough so anyone can include an app manifest and have this supported. I've been thinking I should finish up the coverage of the other apps first. Orca will be interesting because it has all sorts of weird key combinations. @thefunnychannel Mhmm, that's a good question. Do you mean in term of finding happiness, or finding work? @thefunnychannel Well, one thing that I found to be really freeing, is to forget about the idea that programming is a specific thing, like a specific language, or a specific computer. A little while ago, someone told me that "all computers are virtual anyways, might as well use something you like" and I realized that you can basically programming in any sort of way that you want, if you learn things from first principles, you can shape computing in as exciting an adventure as you want. @thefunnychannel It might not mean anything to you right now, because if someone told me that 10 years ago, I wouldn't really have been able to understand what they meant. But instead of learning how to navigate around the hurdles of artifacts from history, build your own dream machines that allows you for thinking deeply about things. Languages, frameworks, engines, not of that stuff matters. @neauoire But one day I want to have everything I use to make things all built by me A lot can happen in 10 years and I'll remember what you've said throughout all of those years. @neauoire Doing the final touches to the menu navigation routines, so things like re-selecting a menu closes it, and so forth. The drawing of the shortcuts is working pretty well. Once I'm satisfied, it'll just be a matter of writing an app manifest for each other program, and include this one file. Then hopefully, with this, the application will be slightly more accessible.  @neauoire this is a completely alien perspective to me haha  @mcc I'm not sure, most of the applications I work on are effectively drawing/typography/animation applications, I haven't really thought too much about making them accessible to blind folks due to their nature, but it might make them more accessible to people with restricted mobility. @neauoire my favorite pattern for self-documenting software: standard toolbar (that is also keyboard navigable w/ alt) with keyboard shortcuts listed next to the menu entries. i believe blender does this (blender generally has a quite good ui, blender can be confusing but i don't think the ui is to blame). @binarycat yup, that's what I'm going to do :) It's also my favourite way to discover what an application can do. I've done it here, now it's a matter of doing it in assembly: https://hundredrabbits.github.io/Dotgrid  @calutron Well orca's help menu is that list of each operators, which is not going to change, but it will have an extra menu at the top of the application with dropdowns exposing everything that the application can do.  @neauoire @binarycat What I really like also on macOS was that we could fuzzy search in the Help menu and it would show us in which submenu the entry is hidden. Useful when you know what you're looking for, but you don't remember where it is. @narF @binarycat I won't be building apps that can do so many things that you need a find tool to locate the subsubsub-menu. @dualhammers the permacomputing wiki is not mine, it's a collaborative work from a few folks in the space, namely @viznut and @320x200 |
Gregory's Server
When I wrote my last Electron applications, I had this controls registry that I'd populate with everything that the application could do, with names, shortcuts and the routine to fire when it happened.
This auto-generated my READMEs, and it also generated a OSX-type navigation menu for each application automatically.
That's what I'll do now.