Package atdoc

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

Overview

Author

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

Version

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

Homepage

See http://www.lichteblau.com/atdoc/ for the orginal version and ATDOC for this fork.

Mailing List

No mailing list.

Download

Get the source code of this fork of ATDOC from the git repository at gitorious.org/lisp-projects/atdoc or download a tarball master from the repository from this link gitorious.org/lisp-projects/atdoc/archive-tarball/master

Get a tarball of the original version from http://www.lichteblau.com/atdoc/download/, or get it from git at http://www.lichteblau.com/git/atdoc.git

Installation

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)    

Dependencies

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)
   (atdoc: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 "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

@section[title]{body}

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.

@about-function{name}

Insert the lambda list of function name and its short description which is the contents of @short in its docstring.

@about-macro{name}

Insert the lambda list of macro name and its short description which is the contents of @short in its docstring.

@about-class{name}

Insert the name of class name and its short description which is the contents of @short in its docstring.

@about-type{name}

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

@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}

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.

@see-constructor{name}

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.

@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.

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>

@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.

@a[href="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 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.

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:

 @begin{return}
   the computed result
 @end{return}    

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:

 @a[http://www.cliki.net]{Cliki}    

This form gets translated into <a a="http://www.cliki.net">Cliki</a>, until the XSLT stylesheets rename a into href.

A second example is

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

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.

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.