3 ms·
But literate programming permits reordering code. The tangle step is where code gets ordered into a structure suitable for the compiler. With most literate prog
by Jtsummers 5y ago
But literate programming permits reordering code. The tangle step is where code gets ordered into a structure suitable for the compiler. With most literate programming tools (my experience is with org and org-babel) you can do something like this (a lot of stuff elided for space):
# Chapter 1: The program
The main function is a simple infinite loop, repeatedly performing gather,
filter, and report tasks.
#+NAME: main
#+BEGIN_SRC c :tangle src/main.c :noweb yes
<<main_includes>>
int main() {
while(true) {
gather();
filter();
report();
}
}
#END_SRC
...
# Appendix A:
#+NAME: main_includes
#+BEGIN_SRC c
#include<gather.h>
#include<filter.h>
#include<report.h>
#+END_SRC
The reason to separate them is when the includes communicate nothing of great importance at a particular point in time. The structure of main, as trivial as it is, is probably more important to the reader than the includes. And since cross references and hyperlinks can be attached to the code block, it's straightforward to find where the noweb reference is. The same thing can be used to pull various other pieces out so that the presentation makes more sense (the output is meant to be read, so order becomes important in what and how you communicate).
Using a sketch of a numerical simulation program, you may have this code structure:
-includes
-parse data
-simulation loop
-report result
For reasons the parsing happens first. But that may be the least interesting bit (the data is just be a straightforward series of lines each containing some number of space separated floating point numbers). Why present it earlier when the simulation loop is really the heart of the program? Or in the simulation, the complex bit may be some novel numerical algorithm at the core, and the rest is bog standard loops and data munging. Pull that algorithm to the front, and then insert it (using something like a noweb reference) in the body of the loop.
In Foo22 a new algorithm is described, we have implemented it here:
.. code and prose
With this completed we can now write the simulation loop:
.. loop code people have seen 1000s of times before,
with a reference to the algorithm above