https://github.com/mmontone/erudite
:green_book: Literate Programming System for Common Lisp
https://github.com/mmontone/erudite
common-lisp lisp literate-programming
Last synced: 3 months ago
JSON representation
:green_book: Literate Programming System for Common Lisp
- Host: GitHub
- URL: https://github.com/mmontone/erudite
- Owner: mmontone
- License: mit
- Created: 2015-04-04T16:54:32.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2023-12-27T12:20:35.000Z (over 1 year ago)
- Last Synced: 2024-11-16T17:41:13.330Z (7 months ago)
- Topics: common-lisp, lisp, literate-programming
- Language: Common Lisp
- Homepage: http://mmontone.github.io/erudite
- Size: 2.81 MB
- Stars: 78
- Watchers: 7
- Forks: 11
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ERUDITE
[](http://quickdocs.org/erudite/)
[](./LICENSE)
## Introduction
Erudite is a [Literate Programming](http://en.wikipedia.org/wiki/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](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
```lisp
(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](http://en.wikipedia.org/wiki/Literate_programming)
* [Literate Programming in the Large](https://youtu.be/Av0PQDVTP4A)
* [Erudite: a tool for Literate Programming in Common Lisp](http://mmontone-programming.blogspot.com.ar/2015/05/literate-programming-in-common-lisp.html)