ERUDITE

Introduction

Erudite is a Literate Programming System for Common Lisp

Features

• Interactive development. No tangling phase in which code is extracted from documentation. Documentation is written in Common Lisp comments. This allows for incremental development: you can load your code, work from SLIME, etc, directly, as in any other Lisp project.

• Multiple syntaxes. Multiple type of literate syntax are supported. It is possible to choose from the default Erudite syntax, or use plain Latex or Sphinx syntax, and potentially others.

• Multiple outputs. Like Latex, Sphinx, Markdown, HTML, etc.

• Automatic indexing and cross-references.

• A command line interface.

• It is portable. You can compile and use in several CL systems (has been tested on SBCL, CCL, CLISP, ECL, so far)

Quickstart

Write your embedded documentation in lisp comments (;; and #| … |# are supported). Use either erudite, latex or sphinx syntax, and produce output to one of them or markdown.

Example in the built-in erudite syntax:

#|
@title Erudite
@subtitle Literate Programming System for Common Lisp

@author Mariano Montone
@syntax erudite

@section Introduction

@ignore
|#
(in-package #:erudite)

#|
@end ignore

For a full example, see erudite.lisp.

Run make to build erudite command line if you want to run it from there, and then sudo make install to install.

Usage: erudite [-hvd] [+vd] [OPTIONS] FILES...

Erudite is a Literate Programming System for Common Lisp
  -h, --help                  Print this help and exit.
  --version                   Print Erudite version
  -(+)v, --verbose[=yes/no]   Run in verbose mode
                              Fallback: yes
                              Default: no
                              Environment: VERBOSE
  -(+)d, --debug[=on/off]     Turn debugging on or off.
                              Fallback: on
                              Default: off
                              Environment: DEBUG
  -(+)id, --implicit-doc[=yes/no] Treat all comments as documentation
                              Fallback: yes
                              Default: yes
  -(+)ic, --implicit-code[=yes/no] Include all code in documentation
                              Fallback: yes
                              Default: yes
  -o, --output=OUTPUT         The output file. If none is used, result is 
                              printed to stdout
  --output-type=OUTPUT-TYPE   The output type. One of 'latex', 
                              'sphinx','markdown'
                              Default: latex
  --syntax=SYNTAX             The syntax used in source files. One of 'erudite',
                              'latex', 'sphinx', 'markdown'
                              Default: erudite
  --author=AUTHOR             The author to appear in the document
  --title=TITLE               The document title

Or run it from lisp, using the erudite function described below.

To build erudite own documentation, run make under the doc directory:

make pdf
make sphinx-pdf
make sphinx-html
make markdown

Look at the doc directory for output examples.

Functions

erudite

(pathname files &rest args &key (output-type *output-type*)
          (syntax *syntax*) &allow-other-keys)

Processes literate lisp files and creates a document.

• pathname: Pathname of the file to generate. If nil, output to a string. If t, print to standard output.
• files: Literate lisp files to compile
• args: All sort of options passed to the generation functions
• output-type: The kind of document to generate. One of :latex, :sphinx, :markdown Default: :latex
• syntax: The kind of syntax used in the literate source files. One of: :erudite, :latex, :sphinx, :markdown. Default: :erudite

References

• Literate Programming
• Literate Programming in the Large
• Erudite: a tool for Literate Programming in Common Lisp