Literate programming is a way of writing software that starts with documentation and embedding your code. Most of the time, the relationship is reversed. You write code, and then in comments, you use some markup system. And in most of my commercial work this makes the documentation a second-class citizen. And ubsequently, long-term technical communication also becomes a second-class citizen.
Why has literate programming not caught on? Not because the idea is terrible but the execution is hard. You don't just write code, you fix it. Things like compilers and debuggers often use line numbers to let you know where your problem is. But the problem is that these compilers and debuggers don't typically read the literate source files as input. They read the normal source files.
Literable attempts to fix this in a non-intrusive manner, by creating tools that act like "diff" and "patch" between your normal source and literate markdown. It does not sit on top of your tools, but is just a middleman.
In a nutshell, you can do three things with literable.
All you really need is a markdown editor that can switch to other kinds of syntax highlighting easily.
I use TextMate, which has a nice mode that also creates the document map in the
lower left hand corner. A quick key combination with Shift + Ctrl + Alt + a
starting letter of the language allows me snappy access to editing with a different
kind of syntax highlighting.
Earlier attempts started with literable making web sites, which ended up being a mistake. You will likely want to take your literate Markdown docs and make webpages or PDFs. That can be done by other programs.
Everything is written in markdown, but you can really easily switch to your language of choice, since getting to "your language of choice" means adding a few spaces to the file.
Thus, putting that javaScript right next to the HTML template fragment is a definite possibility.
Or, let's say you want to explore 5 different client language usages. Having all of these things in the same file can make navigation easy.
By lit-patching a directory tree (where you don't know the source code), you can get a bunch of documentation files that you might start to categorize. This sort of activity is a great technique for building up "mind maps" of software. You make a folder, drag and drop the files around (which are basically source files)
I'm going to assume you know how the basics of SBT.
You can include literate as a plugin in your SBT projects by having a
project/plugins/Plugins.scala file like the following:
import sbt._
class Plugins( info : ProjectInfo ) extends PluginDefinition(info) {
// Check out things my Nexus instance
val tristanhuntRepo = "tristanhunt nexus" at "http://tristanhunt.com:8081/content/groups/public"
val literablePlugin = "com.tristanhunt" %% "literable-plugin" % "VERSION"
}
Then adjust your project definition like so:
import com.tristanhunt.literable.plugin.LiterableProject
class MyProject( info : ProjectInfo ) extends DefaultProject( info ) with LiterableProject
This will add the following actions:
lit-src - Update source from literate markdown.
lit-patch - Update your literate markdown from changes in your source.
lit-diff - See the differences in your source to the literate markdown.
Literable source code is a bunch of markdown files organized under the literate/
directory in your project.
Say you create the following as literable/hello.markdown in your project:
Hello, Silly Project!
=====================
This is my very basic Java application:
// In my_package/Something.java
package my_package;
public class Something {
public static void main( String args[] ) {
System.out.println( "Hello, World!" );
}
}
I can tutorialize within tutorial pages in multiple languages!
// In SomethingElse.js
function somethingElse() {
alert("Hello, World!")
}
Then, run literable using sbt:
sbt lit-src
You should have now created the following files:
src/main/java/my_package/Something.java.
src/main/resources/SomethingElse.js.
doc/hello.html, which will have a few associated
stylesheets.
From here, the normal sbt workflow applies:
sbt compile test package ...
You could also just say sbt lit-src compile....
Now, say you've edited your javaScript file:
function somethingElse() {
alert("Oh mah gawd...")
}
If you want to see what you've edited, you run the lit-diff command:
sbt lit-diff
If you want to update the source, you run the lit-patch command:
sbt lit-patch
Literable is sill being tweaked by me, Tristan Juricek.
The project has no active mailing list, but The Literable Thread Google Wave has been started. Contact me if you are interested and if you need a wave invitation.
0.6.0-SNAPSHOT0.5.12-23 Jan 22, 2010literate parent directory when needed.
lit-compile command. This will both build the source files and then
do the first compiler run, reporting any errors back to the system.
0.5.11-22 Jan 3, 2010headerContent and
footerContent methods of WebDocuments.
literable-plugin-base project, as it's probably not needed.
literable-plugin project attempts to define itself from
path("."). This should generally work in parent-child projects.
doc instead of src/main/doc.
BasicLiterableScalaProject trait in the plugin.
0.5.10-22 Dec 22, 2009lit-src to only create the source files.
0.5.9-17 Dec 15, 2009src directory doesn't exist.
src.
sourceOffset
for the LineParts.