Literati

Literati is a new take on literate programming (LP) and tries to make a little more human friendly.
I find it funny that LP is intended to help programmers write programs that are intended for humans to read, and yet some of the syntax looks like a jumble of random symbols.

Literati is less functional, but as a result, less complicated.

Status

Right now it would probably still be classified as experimental, but you’re welcome to try it.

Syntax

The syntax for Literati is pretty straightforward, and you could probably pick it from checking
the examples provided with the source (in fact this is what I recommend), but for those that want an explanation:

Literati functions on the concept of blocks of Literati code.
There are 2 types of block, a code block and a program block.

Each block of code consists of:
- A title – identifies the block to other parts of Literati code, used in referencing.
- An optional comment – this gets weaved into documentation
- An optional block of application code – this gets tangled into programs. It’s optional because you can have comment only blocks.

The syntax for a block is:

== The title ==

This is the optional comment for the block of code.

-

def the_code

  #here is some demo ruby code. note the code start and end markers (-)

end

-

There is only one program block per Literati file, and it describes the way the file is put together. It uses referencing, which will be discussed next.

A program block consists of:
- A title – identifies the filename or path to be written out
- A number of references – references to code blocks that are replaced with tangled code.

The syntax for a program block is:

== @path/to/program.rb ==

The title.

Referencing

You can reference blocks from other blocks. This is in my opinion where the real magic of Literati kicks in. By referencing blocks from other blocks, or from the program block, you can write programs in a way that is more logical. You can narratively write programs in the order that makes sense, which isn’t necessarily the order it needs to be coded in.

The syntax for a reference is simply the title of the block you want to reference, followed by a period.

Example:

== Example Block ==

This is an example block.

-

puts “Hello world!”

-

== Referencing Block ==

This references the example.

-

def hello_world

  Example Block.

end

-

This will tangle into:

def hello_world

  puts “Hello world!”

end

Usage

By default, literati will tangle all the literati files it finds in the current directory, recursively.

The simplest way to get started would be to clone this repo, chmod literati.rb to be executable, then run:

./literati.rb tangle

or

./literati.rb weave

.

Or you can write your own Literati document, or use one of the examples provided with this codebase, and tangle or weave an individual file.
On a command line, run the following command:

./literati.rb [tangle|weave] [examples/calculator.py.lit]

replacing the path to the file you want to tangle.