<div dir="ltr"><div>Archive pointer to 2013 FRIAM thread on literate programming:<br>  <a href="http://friam.471366.n2.nabble.com/Literate-CoffeeScript-td7581862.html">http://friam.471366.n2.nabble.com/Literate-CoffeeScript-td7581862.html</a><br><br>Owen gave a nice WedTech talk sometime around then, too.</div><div><br></div><div>-Stephen</div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Sun, Feb 21, 2021 at 8:24 PM Russell Standish <<a href="mailto:lists@hpcoders.com.au">lists@hpcoders.com.au</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On Wed, Jan 27, 2021 at 11:45:46AM -0700, Prof David West wrote:<br>
> <br>
> But — a program has two audiences: the machine (no communication here) and<br>
> other programmers (tons of miscommunication here). This is what the reference<br>
> from Eric Smith talks about. There is an entire, usually ignored, paradigm in<br>
> computer science called "literate programming"  — the most prominent advocate,<br>
> Donald Knuth.<br>
> <br>
> If one were skilled at literate programming, one would be communicating to<br>
> another programmer (or herself at a later point in time) all the knowledge and<br>
> meaning necessary for the latter to understand, modify, enhance, or correct the<br>
> program as needs be. If possible this would be a communication skill worth<br>
> developing — might lead to more precise and accurate communication outside the<br>
> world of the computer.<br>
<br>
Literate programming is alive and well in modern software engineering<br>
- it just isn't called that. Knuth's tools which involved a special<br>
input language, a tool for converting that to compileable Pascal and<br>
Latex for producing humane readable printouts of the code were<br>
fantastic for the 1980s, but are rather dated for current software<br>
development requirements.<br>
<br>
In C++, one uses a tool called Doxygen, which parses standard C++<br>
code, and produces HTML, Latex and other possibilities. The "dot"<br>
network graphics tool is used to produce interactive UML diagrams of<br>
the class structures, and source code is annotate with hyperlinks<br>
allowing you to click on (say) a variable name, to find out what type<br>
it is, where it is defined and so on. Plus, there is a huge amount of<br>
doxygen markup features available, allowing things like embedded LaTeX<br>
equations, or adding in crafted HTML links and so on. In short it does<br>
everything Knuth's web tool did, and more, without the need to write<br>
in an idiosyncratic source language.<br>
<br>
When I come across a piece of unfamiliar code, the _first_ thing I do<br>
is run doxygen on it, and then start reading the code using a web<br>
browser. People are sometimes amazed at how quickly I find my way<br>
around a new code base - when that happens, I let them in on my<br>
superpower, ie doxygen.<br>
<br>
Doxygen handles a number of programming environments, Java, C#,<br>
Fortran even, though not Python nor Javascript alas. Other<br>
environments have similar tools, of greater or lesser power: eg Java<br>
has Javadoc (which is broadly compatible with Doxygen, in fact).<br>
<br>
Knuth should be commended for being 30 years ahead of his time with<br>
literate programming, and should be glad the industry does finally<br>
"get it", even if his contribution is largely forgotten, and not<br>
acknowledged by the hordes of software engineers currently practising.<br>
<br>
<br>
-- <br>
<br>
----------------------------------------------------------------------------<br>
Dr Russell Standish                    Phone 0425 253119 (mobile)<br>
Principal, High Performance Coders     <a href="mailto:hpcoder@hpcoders.com.au" target="_blank">hpcoder@hpcoders.com.au</a><br>
                      <a href="http://www.hpcoders.com.au" rel="noreferrer" target="_blank">http://www.hpcoders.com.au</a><br>
----------------------------------------------------------------------------<br>
<br>
- .... . -..-. . -. -.. -..-. .. ... -..-. .... . .-. .<br>
FRIAM Applied Complexity Group listserv<br>
Zoom Fridays 9:30a-12p Mtn GMT-6  <a href="http://bit.ly/virtualfriam" rel="noreferrer" target="_blank">bit.ly/virtualfriam</a><br>
un/subscribe <a href="http://redfish.com/mailman/listinfo/friam_redfish.com" rel="noreferrer" target="_blank">http://redfish.com/mailman/listinfo/friam_redfish.com</a><br>
FRIAM-COMIC <a href="http://friam-comic.blogspot.com/" rel="noreferrer" target="_blank">http://friam-comic.blogspot.com/</a><br>
archives: <a href="http://friam.471366.n2.nabble.com/" rel="noreferrer" target="_blank">http://friam.471366.n2.nabble.com/</a><br>
</blockquote></div></div>