4 ms·
Author here; the idea came from frustrations with the original Python roguelike tutorial on Roguebasin. Since the entire thing was written in one file, it was d
by TStand90 5y ago
Author here; the idea came from frustrations with the original Python roguelike tutorial on Roguebasin. Since the entire thing was written in one file, it was difficult sometimes (for me anyway) to tell what was going on.
While I'm happy with the way the diff style turned out, I will say there is one big downside for me: It's a huge pain to write. Not only did I do a "git diff" every time I made changes and documented it, but if you end up changing something later down the line, then I basically had to go back to the very beginning of the chapter, follow the tutorial along, and double check everything. Maybe there's a more efficient way to do this, but it was a bit tedious and time consuming.
Still worth the effort in the end though, I think.
- croes 5y agoSomeone has to struggle sometimes. Either the author or the readers.
- mysterydip 5y agoMaybe there's a way to programmatically update the diffs the page? have each section tagged as a build or something.
- distrill 5y agoyeah this sounds like kind of a fun problem tbh
- qart 5y agoThank you for making the effort to experiment with the diff style. Now that people are seeing this documentation and appreciating the output, maybe someone else will come up with a way to automate it for future authors.
- lozenge 5y agohttps://craftinginterpreters.com/ https://craftinginterpreters.com/ is a bigger project with automated tests at each stage making sure the diffs line up. I'm not sure it's open sourced though.
- munificent 5y agoThe content of the book isn't open source, but the code in it and the code for the build system is: https://github.com/munificent/craftinginterpreters https://github.com/munificent/craftinginterpreters
- munificent 5y agoMy book Crafting Interpreters has a similar snippet style where it shows you the surrounding context for inserted code so you can see where it goes. It doesn't show the deleted code (because that would probably get too noisy in most cases), but I could if I wanted to. I ended up writing a whole little custom build system to automatically generate the snippets and their surrounding context based on comments in the source code [1]. It was a fairly complex program to write, but it makes it completely automatic and error-free. I can't imagine trying to maintain it all manually. [1]: http://journal.stuffwithstuff.com/2020/04/05/crafting-crafting-interpreters/ http://journal.stuffwithstuff.com/2020/04/05/crafting-crafti...