This is the erudite Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 16:21:58 2024 GMT+0.
erudite/erudite.asderudite/package.lisperudite/config.lisperudite/util.lisperudite/commands.lisperudite/syntax/erudite.lisperudite/syntax/latex.lisperudite/syntax/sphinx.lisperudite/syntax/markdown.lisperudite/syntax/org.lisperudite/erudite.lispThe main system appears first, followed by any subsystem dependency.
eruditeLiterate Programming System for Common Lisp
Mariano Montone <marianomontone@gmail.com>
MIT
# 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)
cl-fad (system).
cl-ppcre (system).
alexandria (system).
split-sequence (system).
cl-template (system).
log4cl (system).
swank-client (system).
package.lisp (file).
config.lisp (file).
util.lisp (file).
commands.lisp (file).
syntax (module).
erudite.lisp (file).
Modules are listed depth-first from the system components tree.
erudite/syntaxcommands.lisp (file).
erudite (system).
erudite.lisp (file).
latex.lisp (file).
sphinx.lisp (file).
markdown.lisp (file).
org.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
erudite/erudite.asderudite/package.lisperudite/config.lisperudite/util.lisperudite/commands.lisperudite/syntax/erudite.lisperudite/syntax/latex.lisperudite/syntax/sphinx.lisperudite/syntax/markdown.lisperudite/syntax/org.lisperudite/erudite.lisperudite/config.lisppackage.lisp (file).
erudite (system).
*catch-errors-p* (special variable).
*code-indexing* (special variable).
*debug* (special variable).
*erudite-package* (special variable).
*implicit-code* (special variable).
*implicit-doc* (special variable).
*output-type* (special variable).
*short-comments-prefix* (special variable).
*subtitle* (special variable).
*syntax* (special variable).
*title* (special variable).
*verbose* (special variable).
*author* (special variable).
*chunks* (special variable).
*current-path* (special variable).
erudite/util.lispconfig.lisp (file).
erudite (system).
append-to-end (function).
file-to-string (function).
erudite/commands.lisputil.lisp (file).
erudite (system).
*commands* (special variable).
*current-eval* (special variable).
*current-extract* (special variable).
*extracts* (special variable).
*ignore* (special variable).
*in-code-section* (special variable).
*output-condition* (special variable).
*swank-connection* (special variable).
*swank-host* (special variable).
*swank-port* (special variable).
define-command (macro).
find-chunk (function).
find-command (function).
find-extract (function).
find-matching-command (function).
match-command (generic function).
maybe-process-command (method).
process-command (generic function).
process-doc (method).
process-fragment (method).
erudite/syntax/erudite.lispsyntax (module).
*erudite-syntax* (special variable).
*latex-document-class* (special variable).
define-erudite-syntax (macro).
find-syntax (function).
format-syntax (function).
match-syntax (method).
match-syntax (method).
match-syntax (method).
match-syntax (method).
match-syntax (method).
match-syntax (method).
match-syntax (method).
match-syntax (method).
match-syntax (method).
match-syntax (method).
match-syntax (method).
match-syntax (method).
match-syntax (method).
match-syntax (method).
match-syntax (method).
match-syntax (method).
match-syntax (method).
match-syntax (method).
process-syntax (method).
process-syntax (method).
process-syntax (method).
process-syntax (method).
process-syntax (method).
process-syntax (method).
process-syntax (method).
process-syntax (method).
process-syntax (method).
process-syntax (method).
process-syntax (method).
process-syntax (method).
process-syntax (method).
process-syntax (method).
process-syntax (method).
process-syntax (method).
process-syntax (method).
process-syntax (method).
erudite/syntax/latex.lispsyntax (module).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
erudite/syntax/sphinx.lispsyntax (module).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
*sphinx-indent* (special variable).
write-doc-line (method).
erudite/syntax/markdown.lispsyntax (module).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
erudite/syntax/org.lispsyntax (module).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
%format-syntax (method).
erudite/erudite.lispsyntax (module).
erudite (system).
erudite (function).
*include-path* (special variable).
*latex-highlight-syntax* (special variable).
*parsing-doc* (special variable).
append-source-fragments (function).
call-with-destination (function).
call-with-error-handling (function).
escape-latex (function).
expand-includes (function).
extract-chunks (function).
extract-indexes (function).
gen-doc (generic function).
indent-code (function).
latex-label (function).
maybe-invoke-debugger (function).
maybe-process-command (method).
parse-code (function).
parse-definition-type (function).
parse-line (function).
parse-long-comment (function).
parse-long-comment-explicit (function).
parse-long-comment-implicit (function).
parse-short-comment (function).
parse-short-comment-explicit (function).
parse-short-comment-implicit (function).
post-process-output (function).
process-doc (method).
process-doc (method).
process-doc (method).
process-doc (method).
process-doc (method).
process-file-to-string (method).
process-file-to-string (method).
process-file-to-string (method).
process-file-to-string (method).
process-fragment (generic function).
process-fragments (function).
process-string (function).
split-file-source (function).
with-destination (macro).
with-error-handling (macro).
write-chunk (method).
write-chunk-name (method).
write-code (method).
write-code (method).
write-code (method).
write-code (method).
write-doc-line (method).
write-indexes (generic function).
Packages are listed by definition order.
eruditeErudite is a Literate Programming System for Common Lisp
cl-ppcre.
common-lisp.
*catch-errors-p* (special variable).
*code-indexing* (special variable).
*debug* (special variable).
*erudite-package* (special variable).
*implicit-code* (special variable).
*implicit-doc* (special variable).
*output-type* (special variable).
*short-comments-prefix* (special variable).
*subtitle* (special variable).
*syntax* (special variable).
*title* (special variable).
*verbose* (special variable).
erudite (function).
%format-syntax (generic function).
*author* (special variable).
*chunks* (special variable).
*commands* (special variable).
*current-eval* (special variable).
*current-extract* (special variable).
*current-path* (special variable).
*erudite-syntax* (special variable).
*extracts* (special variable).
*ignore* (special variable).
*in-code-section* (special variable).
*include-path* (special variable).
*latex-document-class* (special variable).
*latex-highlight-syntax* (special variable).
*output-condition* (special variable).
*parsing-doc* (special variable).
*sphinx-indent* (special variable).
*swank-connection* (special variable).
*swank-host* (special variable).
*swank-port* (special variable).
append-source-fragments (function).
append-to-end (function).
call-with-destination (function).
call-with-error-handling (function).
define-command (macro).
define-erudite-syntax (macro).
escape-latex (function).
expand-includes (function).
extract-chunks (function).
extract-indexes (function).
file-to-string (function).
find-chunk (function).
find-command (function).
find-extract (function).
find-matching-command (function).
find-syntax (function).
format-syntax (function).
gen-doc (generic function).
indent-code (function).
latex-label (function).
match-command (generic function).
match-syntax (generic function).
maybe-invoke-debugger (function).
maybe-process-command (generic function).
parse-code (function).
parse-definition-type (function).
parse-line (function).
parse-long-comment (function).
parse-long-comment-explicit (function).
parse-long-comment-implicit (function).
parse-short-comment (function).
parse-short-comment-explicit (function).
parse-short-comment-implicit (function).
post-process-output (function).
process-command (generic function).
process-doc (generic function).
process-file-to-string (generic function).
process-fragment (generic function).
process-fragments (function).
process-string (function).
process-syntax (generic function).
split-file-source (function).
with-destination (macro).
with-error-handling (macro).
write-chunk (generic function).
write-chunk-name (generic function).
write-code (generic function).
write-doc-line (generic function).
write-indexes (generic function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Processes literate lisp files and creates a document.
Args: - destination: If NIL, output is written to a string. If T, output is written to *standard-output*. If a pathname, then a file is created. Otherwise, a stream is expected.
- 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
Default: :latex
- syntax: The kind of syntax used in the literate source files.
One of: :erudite, :latex, :org, :markdown, :sphinx.
Default: :erudite
Highlight syntax using LaTeX minted package: https://ctan.org/pkg/minted
Append docs and code fragments
Expand include directives
Splits a file source in docs and code
Code in sphinx has to be indented
This function is called whenever a condition CONDITION is signaled in Erudite.
Parse a comment between #| and |#
Resolve chunk inserts and extract inserts after processing
Splits a file source in docs and code
(eql :org)) (selector (eql :index)) stream syntax) ¶(eql :org)) (selector (eql :ref)) stream syntax) ¶(eql :org)) (selector (eql :label)) stream syntax) ¶(eql :org)) (selector (eql :link)) stream syntax) ¶(eql :org)) (selector (eql :italics)) stream syntax) ¶(eql :org)) (selector (eql :bold)) stream syntax) ¶(eql :org)) (selector (eql :emph)) stream syntax) ¶(eql :org)) (selector (eql :list-item)) stream syntax) ¶(eql :org)) (selector (eql :end-list)) stream syntax) ¶(eql :org)) (selector (eql :begin-list)) stream syntax) ¶(eql :org)) (selector (eql :end-code)) stream syntax) ¶(eql :org)) (selector (eql :begin-code)) stream syntax) ¶(eql :org)) (selector (eql :inline-verbatim)) stream syntax) ¶(eql :org)) (selector (eql :end-verbatim)) stream syntax) ¶(eql :org)) (selector (eql :begin-verbatim)) stream syntax) ¶(eql :org)) (selector (eql :subsubsection)) stream syntax) ¶(eql :org)) (selector (eql :subsection)) stream syntax) ¶(eql :org)) (selector (eql :section)) stream syntax) ¶(eql :markdown)) (selector (eql :index)) stream syntax) ¶(eql :markdown)) (selector (eql :ref)) stream syntax) ¶(eql :markdown)) (selector (eql :label)) stream syntax) ¶(eql :markdown)) (selector (eql :link)) stream syntax) ¶(eql :markdown)) (selector (eql :italics)) stream syntax) ¶(eql :markdown)) (selector (eql :bold)) stream syntax) ¶(eql :markdown)) (selector (eql :emph)) stream syntax) ¶(eql :markdown)) (selector (eql :list-item)) stream syntax) ¶(eql :markdown)) (selector (eql :end-list)) stream syntax) ¶(eql :markdown)) (selector (eql :begin-list)) stream syntax) ¶(eql :markdown)) (selector (eql :end-code)) stream syntax) ¶(eql :markdown)) (selector (eql :begin-code)) stream syntax) ¶(eql :markdown)) (selector (eql :inline-verbatim)) stream syntax) ¶(eql :markdown)) (selector (eql :end-verbatim)) stream syntax) ¶(eql :markdown)) (selector (eql :begin-verbatim)) stream syntax) ¶(eql :markdown)) (selector (eql :subsubsection)) stream syntax) ¶(eql :markdown)) (selector (eql :subsection)) stream syntax) ¶(eql :markdown)) (selector (eql :section)) stream syntax) ¶(eql :sphinx)) (selector (eql :index)) stream syntax) ¶(eql :sphinx)) (selector (eql :ref)) stream syntax) ¶(eql :sphinx)) (selector (eql :label)) stream syntax) ¶(eql :sphinx)) (selector (eql :link)) stream syntax) ¶(eql :sphinx)) (selector (eql :italics)) stream syntax) ¶(eql :sphinx)) (selector (eql :bold)) stream syntax) ¶(eql :sphinx)) (selector (eql :emph)) stream syntax) ¶(eql :sphinx)) (selector (eql :list-item)) stream syntax) ¶(eql :sphinx)) (selector (eql :end-list)) stream syntax) ¶(eql :sphinx)) (selector (eql :begin-list)) stream syntax) ¶(eql :sphinx)) (selector (eql :end-code)) stream syntax) ¶(eql :sphinx)) (selector (eql :begin-code)) stream syntax) ¶(eql :sphinx)) (selector (eql :inline-verbatim)) stream syntax) ¶(eql :sphinx)) (selector (eql :end-verbatim)) stream syntax) ¶(eql :sphinx)) (selector (eql :begin-verbatim)) stream syntax) ¶(eql :sphinx)) (selector (eql :subsubsection)) stream syntax) ¶(eql :sphinx)) (selector (eql :subsection)) stream syntax) ¶(eql :sphinx)) (selector (eql :section)) stream syntax) ¶(eql :latex)) (selector (eql :index)) stream syntax) ¶(eql :latex)) (selector (eql :ref)) stream syntax) ¶(eql :latex)) (selector (eql :label)) stream syntax) ¶(eql :latex)) (selector (eql :link)) stream syntax) ¶(eql :latex)) (selector (eql :italics)) stream syntax) ¶(eql :latex)) (selector (eql :bold)) stream syntax) ¶(eql :latex)) (selector (eql :emph)) stream syntax) ¶(eql :latex)) (selector (eql :list-item)) stream syntax) ¶(eql :latex)) (selector (eql :end-list)) stream syntax) ¶(eql :latex)) (selector (eql :begin-list)) stream syntax) ¶(eql :latex)) (selector (eql :end-code)) stream syntax) ¶(eql :latex)) (selector (eql :begin-code)) stream syntax) ¶(eql :latex)) (selector (eql :inline-verbatim)) stream syntax) ¶(eql :latex)) (selector (eql :end-verbatim)) stream syntax) ¶(eql :latex)) (selector (eql :begin-verbatim)) stream syntax) ¶(eql :latex)) (selector (eql :subsubsection)) stream syntax) ¶(eql :latex)) (selector (eql :subsection)) stream syntax) ¶(eql :latex)) (selector (eql :section)) stream syntax) ¶(eql :org)) output files &key prelude postlude syntax title subtitle author &allow-other-keys) ¶Generates Emacs org-mode document.
Args: - output: The output stream.
- files: .lisp files to compile.
- prelude: String (or pathname) to append before the document.
- postlude: String (or pathname) to append after the document.
(eql :markdown)) output files &key prelude postlude syntax &allow-other-keys) ¶Generates Markdown document.
Args: - output: The output stream.
- files: .lisp files to compile.
- prelude: String (or pathname) to append before the document.
- postlude: String (or pathname) to append after the document.
(eql :sphinx)) output files &key prelude postlude syntax &allow-other-keys) ¶Generates Sphinx document.
Args: - output: The output stream.
- files: .lisp files to compile.
- prelude: String (or pathname) to append before the Sphinx document.
- postlude: String (or pathname) to append after the Sphinx document.
(eql :latex)) output files &key title subtitle author template-pathname syntax document-class highlight-syntax &allow-other-keys) ¶Generates a LaTeX document.
Args: - output: The output stream.
- files: The list of .lisp files to compile
- title: Document title.
- subtitle: Document subtitle.
- author: Author of the document
- template-pathname: A custom LaTeX template file. If none is specified, a default template is used.
(eql erudite::end-eval)) line) ¶(eql erudite::begin-eval)) line) ¶(eql erudite::end-code)) line) ¶(eql erudite::begin-code)) line) ¶(eql erudite::end-if)) line) ¶(eql erudite::else)) line) ¶(eql if)) line) ¶(eql erudite::end-when)) line) ¶(eql when)) line) ¶(eql erudite::end-ignore)) line) ¶(eql ignore)) line) ¶(eql erudite::insert)) line) ¶(eql erudite::end-extract)) line) ¶(eql erudite::extract)) line) ¶(eql erudite::insert-chunk)) line) ¶(eql erudite::short-comments-prefix)) line) ¶(eql erudite::author)) line) ¶(eql erudite::subtitle)) line) ¶(eql erudite::title)) line) ¶(eql package)) line) ¶(eql erudite::code-indexing)) line) ¶(eql erudite::output-type)) line) ¶(eql erudite::syntax)) line) ¶(eql erudite::reference)) line) ¶(eql erudite::index)) line) ¶(eql erudite::label)) line) ¶(eql erudite::link)) line) ¶(eql erudite::inline-verbatim)) line) ¶(eql erudite::italics)) line) ¶(eql erudite::bold)) line) ¶(eql erudite::emphasis)) line) ¶(eql erudite::list-item)) line) ¶(eql erudite::end-list)) line) ¶(eql erudite::begin-list)) line) ¶(eql erudite::end-code)) line) ¶(eql erudite::begin-code)) line) ¶(eql erudite::end-verbatim)) line) ¶(eql erudite::begin-verbatim)) line) ¶(eql erudite::subsubsection)) line) ¶(eql erudite::subsection)) line) ¶(eql erudite::section)) line) ¶(eql erudite::end-eval)) line input output cont) ¶(eql erudite::begin-eval)) line input output cont) ¶(eql erudite::end-code)) line input output cont) ¶(eql erudite::begin-code)) line input output cont) ¶(eql erudite::end-if)) line input output cont) ¶(eql erudite::else)) line input output cont) ¶(eql if)) line input output cont) ¶(eql erudite::end-when)) line input output cont) ¶(eql when)) line input output cont) ¶(eql erudite::end-ignore)) line input output cont) ¶(eql ignore)) line input output cont) ¶(eql erudite::insert)) line input output cont) ¶(eql erudite::end-extract)) line input output cont) ¶(eql erudite::extract)) line input output cont) ¶(eql erudite::insert-chunk)) line input output cont) ¶(eql erudite::short-comments-prefix)) line input output cont) ¶(eql erudite::author)) line input output cont) ¶(eql erudite::subtitle)) line input output cont) ¶(eql erudite::title)) line input output cont) ¶(eql package)) line input output cont) ¶(eql erudite::code-indexing)) line input output cont) ¶(eql erudite::output-type)) line input output cont) ¶(eql erudite::syntax)) line input output cont) ¶(eql :erudite)) output-type line stream cont) ¶(eql :markdown)) output-type line stream cont) ¶(eql :org)) output-type line stream cont) ¶(eql :sphinx)) output-type line stream cont) ¶(eql :latex)) output-type line stream cont) ¶(eql erudite::reference)) line output output-type) ¶(eql erudite::index)) line output output-type) ¶(eql erudite::label)) line output output-type) ¶(eql erudite::link)) line output output-type) ¶(eql erudite::inline-verbatim)) line output output-type) ¶(eql erudite::italics)) line output output-type) ¶(eql erudite::bold)) line output output-type) ¶(eql erudite::emphasis)) line output output-type) ¶(eql erudite::list-item)) line output output-type) ¶(eql erudite::end-list)) line output output-type) ¶(eql erudite::begin-list)) line output output-type) ¶(eql erudite::end-code)) line output output-type) ¶(eql erudite::begin-code)) line output output-type) ¶(eql erudite::end-verbatim)) line output output-type) ¶(eql erudite::begin-verbatim)) line output output-type) ¶(eql erudite::subsubsection)) line output output-type) ¶(eql erudite::subsection)) line output output-type) ¶(eql erudite::section)) line output output-type) ¶| Jump to: | %
A C D E F G I L M P S W |
|---|
| Jump to: | %
A C D E F G I L M P S W |
|---|
| Jump to: | *
S |
|---|
| Jump to: | *
S |
|---|
| Jump to: | C E F L M O P S U |
|---|
| Jump to: | C E F L M O P S U |
|---|