
Literate programming: Two beefs with the classic version (2014) - kiyanwang
http://akkartik.name/post/literate-programming
======
lisper
#includes are a totally broken idea. They are the canonical violation of the
DRY (Don't Repeat Yourself) principle. With #includes, whenever you want to
make a change in the signature of a C function you have to do it in two
places. The only reason we have them at all is because early C compilers were
one-pass compilers, and so they needed to have declarations spoon-fed to them
in the right order so that they could run in the 64k or so of RAM that was
available on the PDP-8. There is no good reason to have includes today except
that the C legacy is so strong and the idea is so deeply entrenched in
people's minds and in the structure of C that they are nearly impossible to
get rid of.

~~~
aab0
Isn't the problem here imports in general? Imagine these examples written in a
literate Haskell file .lhs: 'Let us discuss graph search... > import
Control.Monad'

~~~
dllthomas
Note that in Knuth's formulation of literate programming, you could freely
reorder the program source. So those imports needn't be at the start of the
literate program - they could be off in a parenthetical appendix.

~~~
feklar
Which basically nulls one half of the beef this blog post has re canonizing
typesetting over organization.

~~~
akkartik
Hey, give me some credit here. My beef wasn't that CWeb doesn't let you
reorder code. I was talking about policy rather than mechanism, that the
ability of CWeb wasn't being put to best use.

~~~
feklar
Can't blame me for misunderstanding when you have clearly written:

>These are systems that focus on generating beautifully typeset documentation
without allowing the author to arbitrarily order code.

As CWEB does allow the author to arbitrarily order code.

There's also this statement:

>I speculate that nobody has actually read anybody else's literate programs in
any sort of detail.

Which suggests you yourself have never read any literate programs in detail.
Thankfully this statement is provably false as the MMIX Group at MUAS exist? =
true so I can merely comment that buggy line out and read the second half of
your argument without it being entirely invalidated.

~~~
akkartik
> "These are systems that focus on generating beautifully typeset
> documentation without allowing the author to arbitrarily order code."

The previous sentence was: "When I look around at the legacy of literate
programming, systems to do so-called semi- or quasi-literate programming
dominate." Semi- or quasi- being intended to distinguish with classic literate
programming as in CWeb.

I usually try to go out of my way to assume that if someone misunderstands me
it's a failure of my writing, but in this case my post is filled with Knuth's
original CWeb programs. It didn't seem realistic that you missed them all, or
that you thought I missed that CWeb permits reordering in spite of having read
so many CWeb programs.

And then you make this new jab about me not having read any literate programs,
in spite of me showing repeatedly in the article that I went all the way down
the list at [http://www-cs-
faculty.stanford.edu/~uno/programs.html](http://www-cs-
faculty.stanford.edu/~uno/programs.html). Are you sure _you_ read _my_ post?

\---

Thanks for the pointer to
[http://mmix.cs.hm.edu/local](http://mmix.cs.hm.edu/local). Not immediately
obvious that it cares about literate programming, but I'll take your word for
it. I'd appreciate intros to anybody in that group with experience reading
literate programs (email address in profile).

~~~
feklar
A noweb file is a sequence of chunks, which may appear in any order. Nuweb
allows the programmer to present elements of the program in any desired order.
Babel/org-mode allows for arbitrary order as well. Here's an example of Babel:
[http://www.howardism.org/Technical/LP/introduction.html](http://www.howardism.org/Technical/LP/introduction.html)

I'm not sure what LP implementations you have looked at it would have again
helped any misunderstanding on my part if you had named said implementations
that supposedly "dominate" the legacy of LP.

The jab was to point out how your argument returns false with such statements
as "I speculate nobody as ever read a literate program in detail", and
"(typeset) can't render inside just about any actual programming environment
(editor or IDE) on this planet, and so we can't make changes to it while we
work on the codebase" yet emacs exists and can render typeset in a split
screen buffer. DrRacket also renders tex and any other typeset you want
[http://lists.racket-
lang.org/users/archive/attachments/20120...](http://lists.racket-
lang.org/users/archive/attachments/20120311/77279964/attachment-0001.png)

~~~
dllthomas
In my experience, when you say "literate programming", most people think perl
POD or literate Haskell before CWEB and similar. This was certainly the case
for me before making a point of reading what Knuth had actually written (some
many years back). I think that's unfortunate, and I think it's valuable to
educate people that there's more ideas there than present in some of these
systems, and that there are systems supporting more. But I think there are
more constructive ways than ascribing malfeasance or incompetence to what
seems itself a useful (if not maximally useful) piece of education.

~~~
akkartik
Yeah, it's a couple of years old, and I too am a bit embarrassed when I read
it now. It was a rant, read it as such. I find Literate Programming to be
strictly an improvement over conventional programming. But "quasi-literate"
systems to beautify programs aren't really Literate Programming, and their
benefits are more questionable, since they pollute what the term means and
keep people from realizing what Literate Programming can be. That's my
frustration.

------
joshmarinacci
The problem of literate programming, as with many of these systems, is that
they presuppose a text file on disk with a parsing order. Fundamentally code
is a graph, we've just badly flattened it to a poor on disk format.

If we could work, and annotate, at the graph level we'd see far more literate
programming.

~~~
DominikD
That's true, code is rarely linear. But the whole idea of encapsulation,
separation of concerns and many, many other practices is to increase locality
of a code. In that sense a well written and structured code has local, mostly
linear systems that you can analyze in isolation to get insight into the
larger system.

With this in mind it doesn't matter that the overarching structure is much
more complex. Translation unit you're analyzing is (or should) be mostly
human-parsable in a linear fashion.

What I found eye-opening in this article is that it challenged my concept of
well structured code file. I was like "what?! this is blasphemy!" from the
very beginning but at the end I was like "huh, I finally understand why
sometimes #define's feel better in the center of a file than they feel at the
top"[1]. It's rare for a blog entry to stir me like this. :)

[1] amongst other things that came though my head

~~~
akkartik
Thanks for the kind words!

------
johnwatson11218
Anytime I hear about literate programming I think about how mathematicians
worked for centuries to encode math symbolically. If you look at the ancient
math texts it was all word problems and it was just awful. One of the coolest
things about math is how the symbolic representation of the problem allows
your mind to work out solutions with less effort. I think the future of
programming looks more like math than english.

~~~
dllthomas
Let's look at some actual math.

The first article from the most recent issue of the first journal listed on
the AMS page is here:
[http://www.ams.org/journals/ecgd/2016-20-01/S1088-4173-2016-...](http://www.ams.org/journals/ecgd/2016-20-01/S1088-4173-2016-00288-5/S1088-4173-2016-00288-5.pdf)

To me that looks like quite a bit of English, organized for humans. It is true
that there are also quite a few symbols, but I contend it looks a whole lot
more like the CWEB implementation of wc than it does like the C
implementation.

------
Ericson2314
Ah, finally a break from pure Knuth worship for something objective.

[http://unisonweb.org/](http://unisonweb.org/) doesn't espouse the
term"literate programming" itself, but its ideals are comparable. Oh, and, no
imports whatsoever :).

------
PaulHoule
Lately I have been working on "hyper hypertext" which involves mashing up code
with supporting documentation, making the most of things like Javadoc, etc.

------
fibo
I disagree with the Author: literate programming is Great but it is true that
gives a better result For small codebases. I have few tiny projects that are
just a README.md which contains code and docs, and I am really glad about this
Solution I called KISS Literate Programming: as an example, see
[http://g14n.info/bb-clone/](http://g14n.info/bb-clone/)

~~~
e12e
I found this talk about re-structuring and bringing back to life a 1.2 MLOC
lisp codebase with classical LP interesting (it's a bit meandering, but INHO
well worth a watch):

"Literate Programming in the Large":
[https://www.youtube.com/watch?v=Av0PQDVTP4A](https://www.youtube.com/watch?v=Av0PQDVTP4A)

The reorganization is still ongoing, as can been seen at: [http://www.axiom-
developer.org/axiom-website/currentstate.ht...](http://www.axiom-
developer.org/axiom-website/currentstate.html)

