Package liber

Overview
Output formats
Sample Documentation
The Liber syntax
Writing a documentation string
Generating formatted documentation
Generating unformatted XML

Overview

Author

Copyright (C) 2006 - 2008 David Lichteblau
Copyright (C) 2012 . 2025 Dieter Kaiser

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.

Generating formatted documentation

Generates HTML pages or a single HTML page.

Generating unformatted XML

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