3 ms·
The literate programming solution to this problem should be transclusion. Commentary in the 'code' proper should be in the service of understanding the code.
by samatman 6y ago
The literate programming solution to this problem should be transclusion.
Commentary in the 'code' proper should be in the service of understanding the code. Detailed dives should contain a transcluded block of the relevant code section, which updates automatically when that code changes, and with some way of finding all transclusions of a block, so that it's possible to navigate in both directions.
Or in other cases, we want a true hyperlink: one that travels in both directions, so that it's possible to navigate to anywhere in the literate codebase that references a section, from that section.
- kevin_thibedeau 6y agoTransclusion destroys readability of the code. It's nice when you're a professor writing numeric heavy code and want it to flow like an academic paper. Not so nice when someone else has to understand the code and inner scopes are scattered on the wind for expository purposes.
- PaulHoule 6y agoWith current technology it does. Transclusion will become a useful technology when somebody finds a way to do it where the cure is worth the disease. That's a real "millennium problem" in my book.
- samatman 6y agoI think you're confusing macroexpansion, where a marker in the source is expanded into a different piece of code in the 'tangle' and 'weave', with transclusion, where the source contains a full copy of the code in both places, and the compiler takes care of keeping them in sync. What I want is the ability to link a particular piece of code into an issue discussing it, such that this particular copy stays in sync. Since I can already copy-paste such that they don't stay in sync, we now have both options, perhaps even simultaneously. Edit to add: automatic sync should be one-way, with the compiler warning if there are changes in the copy but not the source. Being able to edit the source code inside an issue is a case where more power isn't better than less.