Liber API documentation

About liber:

The Liber library is a HTML documentation generation tool for Common Lisp packages. It extracts documentation strings written in a custom markup language and generates either multiple HTML pages or a single HTML page for the documentation. The source code for the Liber library is available on GitHub.

Liber is developed using SBCL on Ubuntu. The library runs successfully on Windows. The Liber library is licensed under the MIT license.

Liber is a forck of the atdoc library written by David Lichteblau.

Package liber

Package liber

Overview

Author

Homepage

The documentation is available at Liber API documentation.

Download

The source code for the Liber library is available on GitHub.

Installation

The Liber library is ASDF-installable:

(asdf:load-system :liber)

Dependencies

The Liber library needs Closure XML, Split sequence, Xuriella XSLT, Closer-MOP, and their dependencies.

Output formats

The Liber library 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, see the example blocks-world API documentation.
HTML, all on one page, see the example blocks-world API documentation (single-page).

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 Liber sources so that you can easily compile it yourself. The code included is the Blocks World, from chapter 21: "The Blocks World with Classes and Methods" and chapter 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 the Liber library.

In general, you will write a Lisp script that loads the necessary packages for the documentation, configures the environment and executes the HTML generation. Below is an example from the generate-html.lisp file for the BLOCKS-WORD example that comes with the library.

;; Make HTML (multiple pages)
(defun generate-html ()
  (let* ((base (asdf:component-pathname (asdf:find-system :blocks-world)))
         (output-directory (merge-pathnames "doc/" base)))
    (ensure-directories-exist output-directory)
    (liber:generate-html-documentation
      '(:blocks-world :blocks-world-goals)
      output-directory
      :author "Crategus"
      :author-url "http://www.crategus.com"
      :index-title "Blocks World API documentation"
      :heading "blocks-world"
      :css "default.css"
      :icon "lambda.icon"
      :single-page-p nil
      :paginate-section-p nil
      :include-slot-definitions-p t
      :include-internal-symbols-p nil)))

The Liber syntax

Liber looks for markup tags that start with an at-sign @, in either a long or a short form. The short form looks like this:

 @return{The string for the result.}

The long form can be convenient for multiple lines of text:

 @begin{return}
   The string for the result.
 @end{return}

The two forms are completely interchangeable. Behind the scenes, both produce an XML element with tag name result, <result>The string for the result.</result>.

Both forms can take an optional argument, written with brackets, that is used in the following example to pass a hyperlink:

 @url[http://www.crategus.com/books/liber]{Liber API documentation}

The long form is:

@begin[http://www.crategus.com/books/liber]{url}
  Liber API documentation
@end{url}

These forms gets translated into <a a="http://www.crategus.com/books/liber">Liber API documentation</a>, until the XSLT stylesheets rename the <a> tag into href.

A second example with an argument in brackets is:

 @begin[Title]{section}
   body
 @end{section}

which gets translated into <section section="Title">body</section>.

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

Multiple line breaks delimit paragraphs:

  First paragraph.


  Second paragraph.

Writing a documentation string

Here is an example of what the documentation of the gtk:application-active-window accessor looks like using Liber:

(setf (liber:alias-for-function 'application-active-window)
      "Accessor"
      (documentation 'application-active-window 'function)
 "@version{2025-07-28}
  @syntax{(gtk:application-active-window object) => window}
  @argument[object]{a @class{gtk:application} instance}
  @argument[window]{a @class{gtk:window} widget}
  @begin{short}
    The accessor for the @slot[gtk:application]{active-window} slot of the
    @class{gtk:application} class returns the active window of the application.
  @end{short}
  The active window is the one that was most recently focused within the
  application. This window may not have the focus at the moment if another
  application has it - this is just the most recently focused window within
  this application.
  @see-class{gtk:application}
  @see-class{gtk:window}")

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

The following tags are listed in their short form, but are typically used in their long form.

@section[title]{body}: Generates a section called title with body as the content. A table of contents listing the sections will be generated at the top of the package pages.
@subsection[title]{body}: Generates a subsection called title with body as the content.

The following tags inserts the corresponding symbol name and its short description which iss the contents of @short in its docstring.

@about-symbol{name}: Insert the name of a symbol name and its short description.
@about-class{name}: Insert the name of class name and its short description.
@about-type{name}: Insert the name of type name and its short description.
@about-generic{name}: Insert the name of an generic function name and its short description.
@about-function{name}: Insert the lambda list of function name and its short description.
@about-macro{name}: Insert the lambda list of macro name and its short description.

Tags that will be extracted into their own sections

@syntax[name]{description}: Will be moved into the "Syntax" section.
@argument[name]{description}: Will be moved into the "Arguments" section.
@return{description}: Will be moved into the "Return Value" section.
@see-function{name}: Link to the function named name. Syntactically like @fun, this tag will be moved into the "See also" section.
@see-slot{name}: 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.
@see-constructor{name}: 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.

@code{name}: Denotes a sample name or piece of code that a programmer might write in Common Lisp.
@sym{name}: Denotes a symbol name in the package which is documented. The predefined font is monospace bold.
@arg{name}: 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.
@term{name}: Denotes a formal term which might be defined in a glossary.
@defterm{name}: Like the above tag @term{} but in a bold font to emphasize the indroduction of a new formal term.

@short{text}: Copies text into the output normally, but will also extract it for use with @about-function, @about-class ...
@code{text}: In-line Lisp code text, will be formatted using a fixed-width font.
@url[URL]{name}: Hyperlink. This tag accepts an argument, the URL to be used as the href attribute.
@fun{name}: 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).
@class{name}: Link to the class named name. Works like @fun.
@variable{name}: Link to the special variable named name. Works like @fun.

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>

Tags that are passed through to HTML

@pre{text}: Preformatted section, e.g. for source code listings.
@b{text}: Bold font.
@em{text}: Italic font.
@br{}: A single line break.
@break{}: Two line breaks.

Generating formatted documentation

Generates HTML pages or a single HTML page.

Function liber:generate-html-documentation (packages directory &key author author-url date index-title heading css icon single-page-p paginate-section-p include-slot-definitions-p include-internal-symbols-p)

Arguments:

packages -- list of package designators, documentation will be generated for these packages

directory -- a pathname specifying a directory, all output files and temporary data will be written to this directory, which must already exist

index-title -- a string for the title of the main page, index.html, other pages will be named according to the object they are documenting

heading -- a string for a visible title on top of every page

css -- a pathname or namestring pointing to a cascading stylesheet (CSS) file, this file will be copied to the target directory under the name index.css, if this argument is a string and does not start with a dot, it will be taken as namestring relative to the liber/css directory

single-page-p -- a boolean

include-slot-definitions-p -- a boolean

include-internal-symbols-p -- a boolean

Returns:

The pathname of the generated file index.xml.

Details:

Generates HTML documentation for packages. With single-page-p, all documentation is assembled as a single page called index.html. Otherwise, index.html will include only a symbol index and a summary of each package, with links to other pages.

With include-slot-definitions-p, pages for symbols that are not exported will be included, so that documentation for exported symbols can safely refer to internal pages (but internal symbols will not be included in the symbol index automatically). This option has no effect if single-page-p is enabled.

With include-slot-definition, class documentation will include a list of direct slots.

Generating unformatted XML

Power users might want to extract docstrings into XML and then send that XML through their own XSLT stylesheets.

Function liber:extract-documentation (packages directory &rest keys &key include-slot-definitions-p include-internal-symbols-p &allow-other-keys)

Arguments:

packages -- list of package designators, documentation will be generated for these packages

directory -- a pathname specifying a directory, the output file will be written to this directory, which must already exist

include-slot-definitions-p -- a boolean

keys -- extra parameters for stylesheets

Details:

Extracts docstrings from packages and writes them in XML syntax to .atdoc.xml in the specified directory. With include-slot-definitions-p, class documentation will include a list of direct slots.

Extra parameters will be inserted as attributes on the root element.

Other Functions in liber

Function liber:alias-for-class (name)

No documentation string. Possibly unimplemented or incomplete.

Function liber:alias-for-function (name)

No documentation string. Possibly unimplemented or incomplete.

Function liber:alias-for-symbol (name)

Details:

Gets the alias for the NAME of a symbol.

Function liber:alias-for-type (name)

No documentation string. Possibly unimplemented or incomplete.

Function liber:alias-for-variable (name)

No documentation string. Possibly unimplemented or incomplete.

Function liber:slot-documentation (slot-name class-name)

No documentation string. Possibly unimplemented or incomplete.

Function liber:symbol-documentation (symbol)

Syntax:

(liber:symbol-documentation symbol) => docstring
(setf (liber-symbol-documentation symbol) docstring)

Arguments:

symbol -- an external symbol for the package

docstring -- a string for the documentation string

Details:

Gets or sets the documentation string for an external symbol.

2025-09-04

Other Symbols in liber

Symbol liber:liber

No documentation string. Possibly unimplemented or incomplete.

Keyword liber:single-page-p

Details:

Index of Exported Symbols

`liber:`	alias-for-class, Function (undocumented)
`liber:`	alias-for-function, Function (undocumented)
`liber:`	alias-for-symbol, Function
`liber:`	alias-for-type, Function (undocumented)
`liber:`	alias-for-variable, Function (undocumented)
`liber:`	extract-documentation, Function
`liber:`	generate-html-documentation, Function
`liber:`	liber, Symbol (undocumented)
`liber:`	single-page-p, Keyword
`liber:`	slot-documentation, Function (undocumented)
`liber:`	symbol-documentation, Function

Contents

Package liber

Overview

Output formats

Sample Documentation

The Liber syntax

Writing a documentation string

Tags for use only in the docstring of a package itself

Tags that will be extracted into their own sections

Tags for use in the documentation text

Tags for Lists

Tags that are passed through to HTML

Generating formatted documentation

Generating unformatted XML

Other Functions in liber

Other Symbols in liber

Index of Exported Symbols