Package atdoc

This is the documentation of a fork of the package ATDOC which generates documentation for Common Lisp packages. ATDOC extracts documention strings written using a custom markup language and generates HTML pages. At this time the fork of ATDOC does not allow to generate TeX documents, and Info files. The original package ATDOC was written by David Lichteblau and is available under an X11-style license.

This fork of ATDOC extends the possibilities for formating and extracting informations about the package, which has to be documented.

About This Package

Output formats
Sample Documentation
Writing a documentation string
The At-sign syntax
Generating formatted documentation
Generating unformatted XML



Copyright (C) 2006, 2007, 2008 David Lichteblau
Copyright (C) 2012 Dieter Kaiser


This is a documentation of a fork of atdoc from February 22, 2012.


See for the orginal version and ATDOC for this fork.

Mailing List

No mailing list.


Get the source code of this fork of ATDOC from the git repository at or download a tarball master from the repository from this link

Get a tarball of the original version from, or get it from git at


ASDF is used for compilation. Register the .asd file, e. g. by symlinking it, then compile atdoc using asdf:load-system.
  $ ln -sf `pwd`/atdoc.asd /path/to/your/registry/
  * (asdf:load-system :atdoc)    


ATDOC needs Closure XML, Split sequence, Slime's swank, Xuriella XSLT, Closer-MOP, and their dependencies.

Output formats

ATDOC can currently generate documentation in these formats:
  • HTML, one page for each definition, with extra pages containing the package and overview text for its definitions (example multi-pages)
  • HTML, all on one page (example single-page)
  • TeX documents, and
  • Info files.
The output formats TeX and Info files are not supported with the current version of the fork of ATDOC.

Sample Documentation

As an example, code from the book Lisp (3rd edition) by Winston and Horn is chosen. You can find the code with an ASDF definition in the example/ subdirectory of the ATDOC sources so that you can easily compile it yourself. The code included is the Blocks World, from chapters 21 ("The Blocks World with Classes and Methods") and 22 ("Answering Questions about Goals"). Note that the source code from the book has been taken from the publically available lisp3 tarball and is covered by its own license, different from the license of ATDOC.

The multi-page example linked above was generated using:
 (let* ((base (asdf:component-pathname (asdf:find-system :blocks-world)))
        (output-directory (merge-pathnames "example/" base)))
   (ensure-directories-exist output-directory)
     '(:blocks-world :blocks-world-goals)
     :author "Crategus"
     :author-url ""
     :index-title "blocks-world API documentation"
     :heading "blocks-world"
     :css "crategus.css"
     :logo nil
     :single-page-p nil
     :include-slot-definitions-p t
     :include-internal-symbols-p nil))    

Writing a documentation string

Here is a complete example of what the documentation of the Lisp function compile could look like using ATDOC. The output from ATDOC is shown at compile with atdoc.
  @argument[name]{a @term{function name}, or @sym{nil}.}
  @argument[definition]{a @term{lambda expression} or a @term{function}. The
    default is the function definition of @arg{name} if it names a
    @term{function}, or the @term{macro function} of @arg{name} if it names a
    @term{macro}. The consequences are undefined if no @term{definition} is
    supplied when the @term{name} is @sym{nil}.}
  @return{@arg{function} -- the @term{function-name}, or a
    @term{compiled function}.@br{}
    @arg{warnings-p} -- a @term{generalized boolean}.@br{}
    @arg{failure-p} -- a @term{generalized boolean}.}
  @short{Compiles an @term{interpreted function}.}

@sym{compile} produces a @term{compiled function} from @arg{definition}. If the @arg{definition} is a @term{lambda expression}, it is coerced to a @term{function}. If the @arg{definition} is already a @term{compiled function}, @sym{compile} either produces that function itself (i. e., is an identity operation) or an equivalent function.

If the @arg{name} is @sym{nil}, the resulting @term{compiled function} is returned directly as the @term{primary value}. If a @term{non-nil} @arg{name} is given, then the resulting @term{compiled function} replaces the existing @term{function} definition of @arg{name} and the @arg{name} is returned as the @term{primary value}; if @arg{name} is a @term{symbol} that names a @term{macro}, its @term{macro function} is updated and the @arg{name} is returned as the @term{primary value}.

@term{Literal objects} appearing in code processed by the @sym{compile} function are neither copied nor @term{coalesced}. The code resulting from the execution of @sym{compile} references @term{objects} that are @fun{eql} to the corresponding @term{objects} in the source code.

@sym{compile} is permitted, but not required, to @term{establish a handler} for @term{conditions} of @term{type} @condition{error}. For example, the @term{handler} might issue a warning and restart compilation from some @term{implementation-dependent} point in order to let the compilation proceed without manual intervention.

The @term{secondary value}, @arg{warnings-p}, is false if no @term{conditions} of @term{type} @condition{error} or @condition{warning} were detected by the compiler, and true otherwise.

The @term{tertiary value}, @arg{failure-p}, is false if no @term{conditions} of @term{type} @condition{error} or @condition{warning} (other than @condition{style-warning}) were detected by the compiler, and true otherwise. @begin[Examples]{dictionary} @begin{pre} (defun foo () "bar") => FOO (compiled-function-p #'foo) => implementation-dependent (compile 'foo) => FOO (compiled-function-p #'foo) => true (setf (symbol-function 'foo) (compile nil '(lambda () "replaced"))) => #<Compiled-Function> (foo) => "replaced" @end{pre} @end{dictionary} @begin[Affected By]{dictionary} @var{*error-output*}, @var{*macroexpand-hook*}.

The presence of macro definitions and proclamations. @end{dictionary} @begin[Exceptional Situations]{dictionary} The consequences are undefined if the @term{lexical environment} surrounding the @term{function} to be compiled contains any @term{bindings} other than those for @term{macros}, @term{symbol macros}, or @term{declarations}.

For information about errors detected during the compilation process, see Section 3.2.5 (Exceptional Situations in the Compiler). @end{dictionary} @see-function{compile-file}
Note that parts of the documentation strings are just documentation text, which will be included in a section "Details" of the page. Other parts, however, are not part of the actual text, and will be extracted from the documentation string as the first step of processing it. In this case, @argument, @return, and @see-function are the tags that will be removed. All @argument tags will be collected into a section about the function's arguments, all @see-function tags will be collected into a "See also" section.

Tags for use only in the docstring of a package itself
Generates a sub-heading called title with body as the content. A table of contents will be generated at the top of the package pages listing the sections.
Insert the lambda list of function name and its short description which is the contents of @short in its docstring.
Insert the lambda list of macro name and its short description which is the contents of @short in its docstring.
Insert the name of class name and its short description which is the contents of @short in its docstring.
Insert the name of type name and its short description which is the contents of @short in its docstring.
Tags that will be extracted into their own sections
Will be moved into the "Syntax" section.
Will be moved into the "Arguments" section.
Will be moved into the "Return Value" section.
Link to the function named name. Syntactically like @fun, this tag will be moved into the "See also" section.
Similar to @see, this tag specifies a slot reader function for the class it is used in, and will be moved into a "Slot Access Functions" sections. In addition, a section "Inherited Slot Access Functions" will be shown for subclasses.
Similar to @see, this tag specifies a function creating instances of current class, and will be moved into a "Returned By" section.

Tags for use in the documentation text

The following tags are predefined to emphasize the use of symbols in a way similar to the Common Lisp Hyperspec. The fonts of these tags are predefined in a style sheet, which can be overwritten. Furthermore, these fonts are used within other tags like @argument, @return, or @syntax. This way a uniform style can be ensured over the generated documentation.
Denotes a sample name or piece of code that a programmer might write in Common Lisp.
Denotes a symbol name in the package which is documented. The predefined font is monospace bold.
Denotes the name of a parameter or value of a lambda-list or a return value. The font is defined as monospace italic in a style sheet.
Denotes a formal term which might be defined in a glossary.
Like the above tag @term{} but in a bold font to emphasize the indroduction of a new formal term.

Tags for Lists

Use the following tags to generate unordered, ordered, or defintion lists in the documentation.
@itemize, @item
An unordered list like <ul> and <li>
@enumerate, @item
An ordered list like <ol> and >li>
@table, @entry
A definition list like <dl>, <dt>, <dd>

Copies text into the output normally, but will also extract it for use with @about-function, @about-class ...
In-line Lisp code text, will be formatted using a fixed-width font.
Hyperlink. This tag accepts an argument, the URL to be used as the href attribute.

Link to the function named name, read as a symbol into the current package (qualify with a package name to reference other packages included in the same documentation).
Link to the class named name. Works like @fun.
Link to the special variable named name. Works like @fun.
Tags that are passed through to HTML
Preformatted section, e.g. for source code listings.
Bold font.
Italic font.
A single line break.
Two line breaks.

The At-sign syntax

ATDOC looks for markup tags start with an at-sign @, in either a long or a short form. The short form looks like this:
 @return{the computed result}    
The long form can be convenient for multiple lines of text:
   the computed result
Except for the additional whitespace due to line breaks in the second example, the two forms are completely interchangeable. Behind the scenes, both produce an XML element with tag name result, <result>the computed result</result>.

Both forms take an optional argument, written with brackets. To pass a hyperlink use the form:
This form gets translated into <a a="">Cliki</a>, until the XSLT stylesheets rename a into href.

A second example is
which gets translated into <section section="Title">body</section>.

The at-sign also escapes special characters. E. g. closing braces need to be escaped with the at-sign like {n,m@}.

Multiple line breaks delimit paragraphs:
  First paragraph.

Second paragraph.

Generating formatted documentation

Separate functions are offered for each output format: HTML pages, LaTeX/PDF output, and .info files. There is also an older function called generate-documentation, which in now an alias for generate-html-documentation.

Generates HTML documentation for packages. ...

Generates TeX documentation for packages. ...

Generates Info documentation for packages. ...

A deprecated alias for generate-html-documentation.

Generating unformatted XML

Power users might want to extract docstrings into XML and then send that XML through their own XSLT stylesheets. The following function can be used for that purpose.

Extracts docstrings from packages and writes them in XML syntax to the file .atdoc.xml in the specified directory. ...

Exported Symbol Index

*class-name-alias*, Variable  (undocumented)
*external-symbols*, Variable  (undocumented)
*function-name-alias*, Variable  (undocumented)
*symbol-name-alias*, Variable  (undocumented)
*type-name-alias*, Variable  (undocumented)
*variable-name-alias*, Variable  (undocumented)
extract-documentation, Function
generate-documentation, Function
generate-html-documentation, Function
generate-info-documentation, Function
generate-latex-documentation, Function
get-slot-from-name, Function  (undocumented)