/ tutorial

In lit, a code file is separted into labeled chunks. As an author of a lit program, chunks may be placed in any order (best fit for explanation). However, an index must exist to define the proper order for lit to reconstruct the code file.

This is the label for a code chunk, << some name >>=. Everything sharing the same indent is the code that it contains. Otherwise, it's considered part of the narrative. An example chunk:

    << a comment >>=
    // I happen to be a JavaScript comment

Chunks can be surrounded with narrative.

This is a great place to explain the complexity
of print statements in Javascript.
    << say hello >>=
    console.log("Hello World!);

The code contained in a chunk can be referred to later in the program, through a chunk's label.

For the smallest example of a complete lit program we need to specify the index. The index represents the instructions for building the code file. In lit, the index is just another lit macro with an arbitrary name, it's the << * >>= macro. Because it's just another macro it can contain Javascript or the macros we defined earlier.

Note: If lit cannot find a macro with the name * it assumes the first macro is the index.

A complete example.

Here's a general overview of hello world in Javascript
    << * >>=
    << a comment >>
    << say hello >>

Its perfectly valid to write a sentence here.
    << a comment >>=
    // I happen to be a JavaScript comment

This is a great place to explain the complexity
of print statements in Javascript.
    << say hello >>=
    console.log("Hello World!);

With this file several things can be accomplished.

• A lengthy piece of code can be broken into pieces and explained at a high-level with narrative.
• The code can be extracted
• Really nice documentation can be generated

Extract the code

lit --code helloWorld.js.lit

lit generates helloWorld.js

// I happen to be a JavaScript comment
console.log("Hello World!);

Nice documenation

Although the examples above relied on plain text, markdown can be used for the narrative. This allows for very presentable documentation. To read the documentation for lit applied to its own source follow here.