Welcome to Literable

Literable generates your software from a pool of Markdown-based articles and creates:

1. Sources.
2. Documentation.

By creating all your main deliverables from a single source, hopefully your software is built more intelligently. Don't let your knowledge leak into the depths of your email program. Keep it up to date with the code. And don't forget that your documentation is part of your software system! It's not just code.

What is Literable?

It is a series of tools that form a system of managing your software in different stages. It's biased towards Scala and Java based projects. Your software is maintained in multiple places:

1. Literate sources.
2. Source code, kept in a Maven-style directory layout.
3. Static HTML documentation.

As the system develops, more options will be added.

Why Literable?

It's inspired by literate programming, however, being a simpler system, may not officially qualify as a literate programming tool. Regardless of terminology, the inspiration of Literable is that your code should be organized around your thoughts expressed in writing. Avoid peppering your code with thoughts broken into comments.

Other Benefits

Mix Multiple Languages

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.

Source Patching

Unlike many other literate programming tools, you can edit the source files directly, then "source patch" them into the markdown source. It's a "real world" workflow.

Language Support

Since, in the end, it's really just a macro processor, Literate theoretically supports everything. But this isn't completely the truth. I'd grade language support in three levels.

• First level - Most commonly used programming tools give back references to the source markdown files.
• Second Level - Your language's tools are relatively easy to use out of the box, maybe there's "some assembly" required.
• Third Level - Literate will spit out source files for your language, the rest is up to you.

So, here's how I'd grade things now:

1. First level: None
2. Second level: Scala, Java (using sbt)
3. Third level: Everything else

I've found in practice that most LP systems like noweb treat everything like a third level language. Literable, then, is just more focused on the needs of the JVM developer ... for the moment.

Recent Updates

0.5.12-23 Jan 22, 2010

• Creating the literate parent directory when needed.
• Added the 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, 2010

• Intermediate source files are part of the static HTML documentation site.
• Added the ability to add markdown headers and footers via the headerContent and footerContent methods of WebDocuments.
• Files that are likely web resources, like CSS or javaScript, are now considered the Resource language and are stored there.
• The default web resources are loaded as resources instead of inlined into the scala code.
• Altering the default style to not use a grey box, but just borders.
• Removing the literable-plugin-base project, as it's probably not needed.
• The default path in the literable-plugin project attempts to define itself from path("."). This should generally work in parent-child projects.
• Documentation is now written to doc instead of src/main/doc.
• Experimental integration with the scala browse project via the BasicLiterableScalaProject trait in the plugin.

0.5.10-22 Dec 22, 2009

• Fixed the patch method to properly set 'test' versus 'main' (default) code in the "In" statements.
• Added filter to only check things in src/main or src/test directories.
• Set up the lit-src to only create the source files.
• Added some performance logging which currenly only can be enabled for example project analysis.
• Reorganized project code to have the base directory contain all source for the base project.

0.5.9-17 Dec 15, 2009

• Adding extra check to simply punt when the src directory doesn't exist.
• Changed message on diff output when the file isn't found to just include the relative path below src.
• Solved problem where multiple diffs in content would break the sourceOffset for the LineParts.