Sample output: http://backbonejs.org/docs/backbone.html
For languages that support file/line pragmas like C, literate programming works very well. Alternately, if the language supports goto and can sensibly unravel these statements, one can cobble a weave/tangle script to still have a 1-1 mapping between program and source line numbers.
Otherwise, I find that I need to program in a very functional style in order to force my tangled program to have the exact same line numbers as the literate source. This is possible, but it also negates the advantages of having natural language macro names, since they are essentially equivalent to the function names. In this case, tangle becomes an identity mapping.
The granularity will be for every macro defn, so there will be some ambiguity.
On the opposite side of things, I rather enjoy mucking about with the compiled code to diagnose it, and then recompiling to get rid of the diagnostic debris.
Question for the author: Are the spaces around `<<`, `>>`, and `>>=` mandatory?
That's reasonable, in a minimalist kind of way, but it's a bit unfortunate that Lit syntax winds up unmodified in the output document; I'd wind up having to put a paragraph at the top of each document explaining what Lit was and why all the "<< >>" tokens throughout the code weren't actually part of the code.
Also, the resulting HTML doesn't actually validate: http://validator.nu/?doc=https%3A%2F%2Fraw.githubusercontent...
Not sure what you mean by appearing twice. I debated removing the "<< >>" syntax in the generated html, but I don't think it's bad. It's essentially the syntax for macros, which aid in providing context. It's useful in html, because you can quickly refer to the defn of a macro by following the anchor.
lit only has two valid constructs: A macro definition: << ... >>= and a macro reference: << ... >>
...from my experience with other macro systems, I assumed that a "macro reference" would be replaced with the content of the macro definition, leading the code-block to appear at the top (under the star macro) and also in the macro definition. I'm pleased to see that's not the case.
I'd rather not have the "<< >>" syntax in the resulting HTML, because it's the syntax for Lit macros... if I'm writing a document in human language A to explain concept B in programming language C, that's already a lot of context, and requiring the reader to also be familiar with literate-programming-tool D is a drawback.
Linking to macro definitions is definitely a useful feature, but I'd rather those links were distinguished with a CSS class so that I could define their location and appearance in the stylesheet, rather than giving them specific text and markup.
Granted, I do feel I have a fair bit to learn in how to structure code for others to read. Myself included. I am learning the rather obvious point that keeping a narrative to the code is not easy. And, of course, in the couple of attempts I've done recently, I end with a fairly large dump of "and here is the boring stuff" at the end.[1]
Also, I can't recommend reading straight from Knuth's site heavily enough. His programs are rather interesting by modern aesthetics, but they are all still runnable.
The notion I am working towards is actually more of a literate-project. Something that can do all the grunt tasks, such as linting and testing code, importing data, etc. and weave together bits from multiple literate documents.
Many of these features are actually under the label "reproducible research" nowdays. There was a really good talk given on this at a pypy convention a couple of years ago.[1]
If you have the time, take a look at any of Knuth's programs[1]. Obviously, they are not all immediately approachable, but render them to pdf and give them a try. You'll hopefully be surprised just how much you do pick up.
The only downside, to me, is that I become less concerned with modern trends of long variable names and abstractions that "self document." These are still great, of course, but they don't go nearly as far as knowing the narrative of why a piece of code was written.
I would think for most programs there is a very direct sense of linearity in getting a task done. Sure, you will often have a lot of support methods. But seeing them just directly listed can be as much of a distraction as anything else.
Note, also, for nontrivial applications, you will likely have a collection of literate programs. Not just one giant literate program.
[1] https://github.com/axiomzen/Look-Alike/blob/master/coffee/kd...
<<"word"
>>
-define (bs(X), <<X
>>
bs("word")
I feel it's a design error to require the sections be listed at the top and named below. If I want to change a name below, then I have to remember to make the identical change above.
Unless there's something obvious I'm missing about how literate programming works, it seems like a "generate table of contents" macro would be vastly superior to having to maintain it by hand.
My first thought was to use emacs org-mode to manage these .lit files.
My second thought was to consider: do I want name.lang.org.lit or name.lang.lit.org? ... I am leaning towards the latter.
https://github.com/cdosborn/lit/blob/master/examples/lit.hs....
http://www.haskell.org/haskellwiki/Literate_programming http://www.haskell.org/haskellwiki/Haddock
In the README, the example shows a "literate" comment above a Haskell comment -- what's the point of having two kinds of comment?
So maybe I am missing something but sphinx / python seems as good a replacement as can be - although the easy mixing of real code and docs is nice
I know people often say LP is not just "good commenting". But, really, is above so different than LP?
In some cases LP won't provide a benefit over commenting. But the idea is that you step outside of the rules of the language (or more appropriately the interpreter/compiler) and write a story where the order is defined by the ease of explanation, not the order mandated by the machine.
You should also consider writing up some easy programming example such as FizzBuzz.
Bootstrapping your code into your own literate programming environment is a must to sit at the lit table :)
Even without literate programming, this is the harder part of the program to document, to me. To really give it credit here, I would split these out into different files. But, I have pretty low interest in really delving into some of the stuff there. Hence, "and this is the support code for the figures I did."
I'd previously played around with getting org to do stuff "on commit", via git hooks, but I didn't make much progress (and given the environment I was committing from, I was sure that I was going about it backwards anyway).
Org still doesn't have a universal character escape mechanism!
(info "Org")
And, ultimately, this is why I do a "this is the boring stuff" sections. Bugs in that area should be easy and obvious to both diagnose and to fix. Bugs in the other areas are often neither.