[HN Gopher] Writing about writing about programming
___________________________________________________________________
Writing about writing about programming
Author : codyd51
Score : 50 points
Date : 2023-07-04 15:32 UTC (7 hours ago)
(HTM) web link (axleos.com)
(TXT) w3m dump (axleos.com)
| legel wrote:
| Writing about writing about writing about programming
| abathur wrote:
| Interesting to see how the writer scratches this itch.
|
| I've been managing the same basic friction with multiple
| incremental copies of the source files, a little shell script to
| generate diffs/logs/artifacts, and some make-based tooling to re-
| run those when sources change (and sync the outputs to a gist so
| that I can optionally include an instruction for obtaining the
| source via git). It works, but it's obviously suboptimal if I
| goof something and then have to make the same fix several times.
| codyd51 wrote:
| Hi HN, author here!
|
| This post is ostensibly about some tooling I've written to help
| me write posts that contain lots of code, while ensuring that the
| code always produces a valid source tree which matches up with
| where we are in the prose. This is easy when a post is small, but
| can become really difficult to manage with a larger piece of
| work!
|
| The bulk of this post, though, is a proof-by-demonstration of the
| tooling. We implement a little 2048 clone, line by paragraph, and
| there's a bunch of checkpoints interspersed throughout the post -
| and now we've implemented input handling! and now we can slide
| tiles around!
|
| At each of these checkpoints, I've embedded some live
| visualizations of the code we've written so far. My hope is that
| the reader can really get a feel for what we've built so far,
| because they can see what works, and what doesn't work, running
| right in front of them in the browser. These little computers are
| taken from snapshots produced by the tooling, compiled to Wasm
| and executing in the browser.
|
| This is my first time providing this level of interactivity in
| one of my posts, so please do feel welcome to play around with
| it. I'd love any and all feedback on the experience. Thanks so
| much!
| abathur wrote:
| A few questions/notes from reading the post and looking at the
| repo:
|
| 1. Is the post trailing the repo, or vice-versa? This line in
| the README describes a different command format and seems to
| suggest that {{}} caused trouble?
| https://github.com/codyd51/penpal/blob/4ff061b045aa447ac8976...
|
| 2. Some of the code blocks, like the first `src/main.rs` block,
| link to divergent GH source. Is that coming from penpal in some
| way, or are you grafting that back on after somehow? (And if
| it's built in, is there a way to avoid/manage this divergence?)
|
| 3. The post and repo contradict on what `generate` does, and
| the post lets us dangle for a really long time before resolving
| it.
|
| The post says: "Let's generate an executable representing our
| (tiny!) source tree so far." (and then shows a single-line code
| block with `{{generate}}`)
|
| The repo says: "When the `generate` command is used, the
| current state of every snippet is rendered into a source code
| tree."
|
| The last section of the article finally clarifies, but it'd be
| kind to be clear that generate creates only the source tree and
| note that you're grafting on a compile step separately that's
| outside of penpal's scope.
| codyd51 wrote:
| You're right, thank you for the thoughtful feedback. It's
| true that the blog post skims over the meaning of `generate`
| when introducing it, and that I'm doing a bit of extra work
| under the covers in this post. I thought keeping things light
| and interactive would help easing into the details, but it's
| true that the reader has to wait quite a long time to see
| what the preprocessor is doing exactly, and it's not clear
| until the end what exactly is going on. I'll add something in
| to signpost this a bit better.
|
| To answer your questions, the post is trailing the repo. I've
| uploaded the full source comprising this post here:
| https://github.com/codyd51/penpal-blog-post-preprocessed.
|
| The code blocks link back to the Github source via a custom
| Hugo shortcode, and I currently need to maintain this by
| hand. While wrapping up this blog post, I added support for
| generating this shortcode via an extension to the `show`
| command.
|
| Here's what the penpal command to render a hotlinked code
| block looks like, in the source code of this blog post:
| https://github.com/codyd51/penpal-blog-post-
| preprocessed/blo...
|
| Here's what the shortcode generation for this looks like in
| penpal: https://github.com/codyd51/penpal/blob/release/penpal
| /render...
|
| I think it'd be really nice to maintain all of this
| automagically - it seems reasonable that the technical
| content being built up would frequently be hosted in a
| finished state somewhere!
| coastl wrote:
| This is great! I really enjoyed the interactivity of it all.
| I've been working on building similar, but much simpler, tools
| to help me blog and seeing this is inspiring.
|
| Good job!
___________________________________________________________________
(page generated 2023-07-04 23:02 UTC)