Or what if the editor supported such comments in the margin, like the LibreOffice or Word review comment features?
Or what if the editor supported such comments in the margin, like the LibreOffice or Word review comment features?
The other problem with using numeric footnotes is that any time you change the code, you have to laboriously renumber the comments.
That part really could be helped with better editor support. And if the generated documentation were, say, a rich HTML page, you could even have it so that mousing over a line of code would highlight the relevant point in the documentation (and vice versa).
But LP has been around a lot longer than I have been programming at all, and I find it hard to believe that after a month of dabbling, I have better insights into improving it than those who have been using it for decades.
That said, the more I read into LP, the more I feel like part of my problem may simply be that CoffeeScript's implementation of it is rather anæmic. Traditional LP is apparently supposed to have macros that are essentially section headers that double as language constructs. That's a lot more powerful than just stripping everything but the code blocks from a markdown file and executing the result.
Have you tried reading the examples at http://www.literateprogramming.com/ ?