readme

================================
lit: a literate programming tool
================================

lit creates a markdown or HTML document from a list of text and source
code files

it is intended to be used for presenting programs in the form of an e.g
technical article or tutorial

it is assumed that the input files are given in an order such that
the final document follows a logical narrative

as many source code comments will be extracted into the text content
of the final document, they should usually form a large part of that
narrative by explaining the program in detail

source code comments may also contain directives that prompt lit to
build and run programs with the output inlined into the document

usage:

    lit2md [-o <file>] <file1> [<file2> ...]

description:

    lit converts source code to markdown

    the output is written to <file> if given and to index.md
    in the current working directory otherwise

    plain text input files are assumed to contain markdown and
    are inlined into the final document

    lit is intended to be used as a literate programming tool
    by converting self contained programs with complete comments
    into documents designed for human review

directives:

    by default, lit will simply create markdown code blocks to
    format source code

    comments starting with these keywords are treated as directives
    that can improve on this default

    - lit text
    - lit skip
    - lit unskip
    - lit execute [<command-line>]

    the lit text directive causes lit to create a markdown paragraph
    from the following consecutive lines of comments

    the lit skip directive causes lit to stop generating output while
    reading subsequent lines of input, until a lit unskip directive
    is given (including output generated by the lit execute directive)

    the lit execute directive provides a shell command that will
    be executed in the same directory as the input file and have its
    output (if any) formatted as plain text in the final document

    when no command line is given, and an appropriate interpreter for
    the input file can be found (e.g. as given by a script's shebang),
    then lit will interpret the file up to that point and format any
    generated output as plain text in the final document

    subsequent lit execute directives with no command line will continue
    to use the same interpreter state, allowing for incremental script
    execution

    the directory of the input file is listed after each lit execute
    directive to check for changes to, or creation of, image files that
    will be copied to a sub directory alongside the output file and
    linked to in the document

    please see the tests directory of the lit repository for complete
    examples on how these directives may be used in practice