Take this as Literate
1 Order, order
Most programs begin with boring stuff. Declarations, copyright notices and definitions of lots of things the reader doesn't understand yet.
Literate Programming tries to solve this by writing your source-document (remember, this is code and documentation) in the order which is natural: top-down. The generated code can be in any order you like, or better: the order your compiler likes it.
For the interested reader of your application (or the one who needs to maintain it), the top-down approach is far more natural.
2 An example
Let's say we write an application for transforming HTML-files into other HTML-files, but then with some extra decoration inside the new HTML-file.
The approach would be to write a shell-script which does the trick:
[ -r ~/.profile ] && . ~/.profile # this file comes from repo git@gitlab.com:joereg/html-transformation.git [ "$1" = "" ] && echo "$0 need at least one argument" && exit 1 [ ! -r "$1" ] && echo "$0 needs a readable file as input, [$1] is not" && exit 1 exec xsltproc mysheet.xsl "$1"
Wow, what a load of uninteresting lines at the beginning of this script. Also, if your application has multiple files, there is a chance of duplication of vital information, e.g. the repo-name.
In Literate Programming one would go top-down:
2.1 The application
We need to transform a XHTML-document to another HTML-document with the use of a XSL-stylesheet. The stylesheet is a given file:
/usr/local/stylesheets/xhtml2decorated.xsl
The program xsltproc will do the transformation:
xsltproc <<name of stylesheet>> "$1"
Some say listing 1 and 2 should be the other way around for a proper top-down narrative.
The script will look like:
<<shell-prelude>> #<<reponame>> <<test param validity>> <<transform>>
Which leaves us defining shell-prelude, reponame and test
param validity. These can be defined seperately and even come from
an include-file!
3 about this title
The document to generate the scripts has the same source as the document you are reading now.
Most scripts are bare bone, the amount of fancy stuff is kept to an absolute minimum in order to present only the concepts at hand and only that.
This title was written between 15th and 17th of July 2017