Andy Wingo, lead Hoot engineer, just published a very entertaining new blog post about getting the Hoot project booted. I couldn’t help but laugh as I read it!
4 Likes
I tried to write a comment in his blog post but I kept getting an error about invalid Markdown or whatnot. Anyway, here’s my response:
Although I’m not well-versed into compilation or WASM, I think I grasped from your post that dynamic bindings were causing a problem for your task.
I recently had the same issue from a different problem: I was trying to figure out how to document Guile code. I disliked the ;;; Commentary nonsense, and I disliked texinfo (because texinfo, as far as I know, does not have the features I expect for code documentation.) I wanted the following:
- Document everything, not just procedures (lambdas)
- Documentation can refer to intra/cross items, e.g. procedure parameters, etc.
- Markup for features such as code blocks, doctests (unit testing in documentation), etc.
- HTML extraction
Now, I get it, lisp is lisp, not Rust (rustdoc), or Haskell (haddock), or Python (sphinx, etc), or C/Java/other target of Doxygen. Those languages have a different purpose, and lisp is good for REPL-driven programming. Maybe you don’t need doctests for that, since you’d spend more time quickly changing definitions (but when they crystalize, don’t you want to write some tests to … perfect them?)
I started writing a documentation tool that would work with org-mode (eventually I realized I needed to come up with my own #+BLOCK_COMMANDs, and that org-mode unfortunately requires an Emacs binary to be extracted to HTML (parsing might be possible with some treesitter stuff.))
But the problem I quickly run into is this, there’s no way to know what the value of a symbol is by static inspection of the code, it’s undecidable like the halting problem. My conclusion was that I needed to rewrite use-module, define-module, define, and so on, to disallow redefining a symbol once introduced. This would limit my documentation program to my redefined Guile API. It would be fine for my own personal use, but I wasn’t about to put all this effort to create something so esoteric.
Who cares for mutable on-line documentation anyway? Lisp keeps pretending the entire userbase is ssh’d into a single Symbolics machine. There needs to be an amelioration to this, and I think you’ve come up with a good idea with #:pure. At least, if I’ve understood correctly what you’ve written in this blog post. I hope I didn’t type all this stuff just to vent on some unrelated thing.
So yes, side note: you might’ve finally fixed Guile’s documentation problem.