←back to thread

Noweb – A Simple, Extensible Tool for Literate Programming

(www.cs.tufts.edu)
140 points Tomte | 1 comments | 27 Feb 21 20:11 UTC | HN request time: 0.229s | source
Show context
gnuvince ◴[27 Feb 21 21:26 UTC] No.26288322[source]▶
Hijacking this topic to talk about something I've been thinking about lately: literate diffs.

I find that the order of diffs given by git is not optimized for helping a reviewer understand the change. Sometimes the order of files will not be in the most logical way; sometimes unrelated changes (e.g., a text editor removing blanks at the end of lines) create noise; etc.

I've been thinking that it would be interesting to have a tool where the author can take the diff of their commit(s), order them in a way that is conducive to understanding and explain each part of the diff. That'd be similar to having the author do a code walkthrough, but at the pace of the reader rather than the author.

replies(6): >>26288537 #>>26288793 #>>26288837 #>>26289067 #>>26289125 #>>26289821 #
1. shakna ◴[28 Feb 21 01:22 UTC] No.26289821[source]▶
If you're making use of something like git-send-email you can already do this easily.

The patch format explicitly allows it to ignore "junk" information at certain points, so you can edit in comments all over the place. The format also lets you break up a diff, rearranging it semantically, and it'll get rebuilt later.

Edit, to expand on the above:

> patch tries to skip any leading garbage, apply the diff, and then skip any trailing garbage. Thus you could feed an article or message containing a diff listing to patch, and it should work..... After removing indenting or encapsulation, lines beginning with # are ignored, as they are considered to be comments.

> With context diffs, and to a lesser extent with normal diffs, patch can detect when the line numbers mentioned in the patch are incorrect, and attempts to find the correct place to apply each hunk of the patch. As a first guess, it takes the line number mentioned for the hunk, plus or minus any offset used in applying the previous hunk. If that is not the correct place, patch scans both forwards and backwards for a set of lines matching the context given in the hunk.