Tim Gittos

I'm an Australian currently living in Austin, TX in the USA.

I currently earn a living programming, though I wouldn't call myself a programmer. If I had to attach a label to myself, I'd use the term autodidact.

I love learning, and my favorite things to learn about are programming, computer graphics, AI & machine learning, robotics, painting and creativity.

Literati - Ruby based literate programming library

Last updated on 15 Aug 2011

Description

One of the big issues with development is how fast code
documentation becomes out of date, when it is written at all.

While programs are executed by computers, we write them mostly
for the benefit of other programmers, hence the proliferation of
high level languages such as Ruby and Python.

Literate programming is an attempt to solve this problem by
tightly coupling the code to the documentation, and to help
programmers write clearer programs for each other first, and for
computers second.

Literate programming was pioneered by Donald Knuth, and while there
are a lot of software packages to tangle/weave literate programming
files, there’s a wide variety of syntaxes for writing documents.

Literati attempts to keep the literate programming syntax as
close to regular text as possible, so you don’t have to think
about how to format your programs and documentation.

Literati keeps out of your way so you can do what you do best: code.

Status

This is still very much a rough proof of concept.

At the moment, the library is contained in one file: literati.rb.
There are 2 sample programs that you can run through Literati and it
will produce a Ruby and a Python based calculator.

I’m in the middle of a rewrite of Literati, in Literati format.
This can be found in the lib directory, however it’s not functional.

Source

http://github.com/tgittos/literati

Syntax

I’ve tried to keep the literati syntax as simple as possible. You should be able
to pick it up by just reading through the two sample programs, however there
may be some finer points that aren’t obvious.

Each code block must have a header, in the form of
== Identifier ==
The identifier will uniquely identify that code block, and allow you to reference
it later in the document.

You can optionally put more documentation after the header. This documentation
can be any format you wish.
After your documentation, you can close the documentation section with
@api, doc
This tag tells literati which documentation types this documentation block belongs to.

Then your source code comes next. You can terminate your source code by starting a new block.

At the end, you need a program description block, which looks like
== @filename.rb ==
The @ in the header marks the name of the file, and below the header block are code section
references, as defined in the unique identifiers above.

I know none of this documentation makes any sense, but considering this is still in dev,
that’s to be expected.

I’ll rewrite the documentation when I finish refactoring the code.