1 Introduction

CL-DOCWEAVER is a document weaver for Common Lisp.

Documentation for a Lisp project is written with the user’s tool of choice (like Texinfo, Markdown, etc). Then, Common Lisp definitions are expanded into the documentation source using DocWeaver commands.

DocWeaver commands give the user control on how definitions are to be expanded, either via command options or by choosing a different set of commands.

CL-DOCWEAVER is easy to extend to support different documentation tools.

Texinfo and Markdown are the ones with best support at this moment.

2 Installation

3 Usage

Write documentation for your Common Lisp project in your documentation tool of your choice (either Texinfo or Markdown at this moment). Then invoke cl-docweaver commands to expand Lisp definitions for either variables, functions, macros, classes, or even whole packages.

Commands have the following syntax: (@command-name &rest args).

For example, use (@clfunction alexandria:flatten) to expand the definition of ALEXANDRIA:FLATTEN function.

The expanded function definition looks like this:

Function: ALEXANDRIA:FLATTEN (tree) ¶

Traverses the tree in order, collecting non-null leaves into a list.

Note that commands usually receive options in order to be able to control different aspects of the expanded definition.

By default, docstrings are interpreted to extract possible references to other parts of the code; then those references are formatted as links that can be used to navigate the definitions documentations.

Finally, use WEAVE-FILEto weave your documentation system source files.

Have a look at cl-docweaver documentation in docs directory for an example of how all this works.

• Command Line

make
sudo make install

cl-docweaver - Common Lisp Documentation Weaver

USAGE: sbcl [OPTIONS] INPUTFILE

Weave Common Lisp documentation in INPUTFILE.

Options:
  --version             display version information and exit
  -h, --help            display help information and exit
  -d, --debug           debug
  -o FILE, --output FILE
                        output file
  -s DOCSYSTEM, --docsystem DOCSYSTEM
                        the documentation system to use. either texinfo or
                        markdown. if not specified, the documentation system
                        used is inferred by looking at input file extension.
  -m MODULES, --modules MODULES
                        the list of modules to REQUIRE
  -c COMMAND-PREFIX, --command-prefix COMMAND-PREFIX
                        the command prefix character to use. Default is    --parse-docstrings    When enabled, parse docstrings and format them. This is
                        enabled by default.
  --escape-docstrings   When enabled, escape the docstrings depending on the
                        output. This is enabled by default.

Examples:

  Weave texinfo file and visualize weaved output

      cl-docweaver my-documentation.texi

  Weave texinfo file into a file

      cl-docweaver my-documentation.texi -o my-documentation.weaved.texi

4 Commands

Command: @setup &rest options ¶

Configures cl-docweaver.

OPTIONS is a plist with members:

• :docsystem The documentation system to use. Either :texinfo or :markdown. Default is :texinfo.
• :parse-docstrings A boolean that indicates if docstrings should be parsed or not. Default is T.
• :command-prefix The prefix character to use for commands. Default is the #\@ character.
• :modules A list of Lisp modules to REQUIRE in order to be able to expand definitions.

Command: @clvariable variable-symbol &rest args ¶

Expands definition for variable bound to VARIABLE-SYMBOL.

For example,

(@clvariable cl:*standard-output*)

Expands to this:

COMMON-LISP: *STANDARD-OUTPUT* ¶

default output stream

A list of symbols is also accepted; variable definitions are expanded in sequence.

For example,

(@clvariable (cl:*compile-print* cl:*compile-verbose*))

expands to this:

COMMON-LISP: *COMPILE-PRINT* ¶

The default for the :PRINT argument to COMPILE-FILE.

COMMON-LISP: *COMPILE-VERBOSE* ¶

The default for the :VERBOSE argument to COMPILE-FILE.

Command: @clfunction function-symbol &rest args ¶

Expands definition for function bound to FUNCTION-SYMBOL.

For example,

(@clfunction alexandria:map-permutations)

Expands to this:

Function: ALEXANDRIA:MAP-PERMUTATIONS (function sequence &key (start 0) end length (copy t)) ¶

Calls function with each permutation of LENGTH constructable
from the subsequence of SEQUENCE delimited by START and END. START
defaults to 0, END to length of the sequence, and LENGTH to the
length of the delimited subsequence.

Like with See ‘@clvariable’, a list of symbols is also accepted and definitions are expanded in sequence.

Command: @clmacro macro-symbol &rest args ¶

Expands definition for macro bound to MACRO-SYMBOL.

For example,

(@clmacro cl:print-unreadable-object)

Expands to this:

Macro: COMMON-LISP:PRINT-UNREADABLE-OBJECT ((sb-impl::object stream &key type identity) &body sb-impl::body) ¶

Output OBJECT to STREAM with "#‘<’" prefix, "‘>’" suffix, optionally
with object-type prefix and object-identity suffix, and executing the
code in BODY to provide possible further output.

As in other commands, a list of symbols is also accepted; macro definitions are expanded in sequence.

Command: @clclass class-name &rest args ¶

Expands definition of class with name CLASS-NAME.

For example,

(@clclass asdf:component)

Expands to this:

Class: ASDF/COMPONENT:COMPONENT ¶

Base class for all components of a build

Class precedence list: component, standard-object, t

Slots:

• name — type: string; initarg: :name; reader: asdf/component:component-name; writer: (setf asdf/component:component-name)

  Component name: designator for a string composed of portable pathname characters

• version — type: t; initarg: :version; reader: asdf/component:component-version; writer: (setf asdf/component:component-version)
• description — type: t; initarg: :description; reader: asdf/component:component-description; writer: (setf asdf/component:component-description)
• long-description — type: t; initarg: :long-description; reader: asdf/component:component-long-description; writer: (setf asdf/component:component-long-description)
• sideway-dependencies — type: t; reader: asdf/component:component-sideway-dependencies; writer: (setf asdf/component:component-sideway-dependencies)
• if-feature — type: t; initarg: :if-feature; reader: asdf/component:component-if-feature; writer: (setf asdf/component:component-if-feature)
• in-order-to — type: t; initarg: :in-order-to; reader: asdf/component:component-in-order-to; writer: (setf asdf/component:component-in-order-to)
• inline-methods — type: t; reader: asdf/component:component-inline-methods; writer: (setf asdf/component:component-inline-methods)
• relative-pathname — type: t; initarg: :pathname
• absolute-pathname — type: t
• operation-times — type: t; reader: asdf/component:component-operation-times; writer: (setf asdf/component:component-operation-times)
• around-compile — type: t; initarg: :around-compile
• properties — type: t; initarg: :properties; reader: asdf/component:component-properties; writer: (setf asdf/component:component-properties)
• %encoding — type: t; initarg: :encoding; reader: asdf/component::%component-encoding; writer: (setf asdf/component::%component-encoding)
• parent — type: t; initarg: :parent; reader: asdf/component:component-parent
• build-operation — type: t; initarg: :build-operation; reader: asdf/component:component-build-operation
• additional-input-files — type: t; reader: asdf/component::%additional-input-files; writer: (setf asdf/component::%additional-input-files)

As in other commands, a list of symbols is also accepted; class definitions are expanded in sequence.

Command: @clpackage package-name &key (include-external-definitions t) include-internal-definitions (categorized t) ¶

Expands definition for Common Lisp package named PACKAGE-NAME.

If INCLUDE-EXTERNAL-DEFINITIONS is T, then all package external definitions are expanded.

If INCLUDE-INTERNAL-DEFINITIONS is T, then all package internals definitions are expanded.

CATEGORIZED controls how to categorize the expanded package definitions:

• :by-kind or T, definitions are separated in sections (variables, functions, etc).
• :by-docstring-category, definitions are grouped by the category parsed from docstrings. A category for a definition is specified by adding the text “Category: category-name” to the docstring.
• Otherwise, they are expanded in sequence with no separation.

Example:

(@clpackage :alexandria)

Command: @clref symbol type ¶

Creates a reference to SYMBOL. TYPE should be one of variable, function, class, etc.

For example, to reference ALEXANDRIA:FLATTEN function, do this:

(@clref alexandria:flatten function)

And this is the resulting link: FLATTEN

Command: @cleval expression ¶

Evaluates Lisp EXPRESSION and prints the result.

Command: @clcapture-output expression ¶

Evaluates Lisp EXPRESSION, captures its output, and prints it to the document.

5 Documentation systems

• Texinfo

@cldefun{alexandria, flatten, ()}
Traverses the @var{tree} in order, collecting non-null leaves into a list. 
@endcldefun

@c Macros for Common Lisp definitions

@c Variable definition
@macro cldefvar{package, name}
@vindex \package\:\name\
@anchor{\package\:\name\ variable}
@defvr \package\ \name\
@end macro

@macro endcldefvar
@end defvr
@end macro

@c Function definition
@macro cldefun{package, name, args}
@findex \package\:\name\
@anchor{\package\:\name\ function}
@defun \package\:\name\ \args\
@end macro

@macro endcldefun
@end defun
@end macro

@c Example:
@c @cldefun {alexandria, flatten, (x y z)}
@c This is alexandria flatten function
@c @endcldefun

@c Function definition
@macro cldefmacro{package, name, args}
@findex \package\:\name\
@anchor{\package\:\name\ macro}
@defmac \package\:\name\ \args\
@end macro

@macro endcldefmacro
@end defmac
@end macro

@c Example:
@c @cldefmacro {alexandria, with-gensyms, (&rest args)}
@c This is alexandria with-gensyms macro
@c @endcldefmacro

@c Generic function definition
@macro cldefgeneric{package, name, args}
@findex \package\:\name\
@anchor{\package\:\name\ function}
@deffn Generic-Function \package\:\name\ \args\
@end macro

@macro endcldefgeneric
@end deffn
@end macro

@c Class definition
@macro cldefclass{package, name}
@tindex \package\:\name\
@anchor{\package\:\name\ class}
@deftp Class \package\:\name\
@end macro

@macro endcldefclass
@end deftp
@end macro

@c References
@macro clref{package, name, type}
@ref{\package\:\name\ \type\,\name\, \name\}
@end macro

@c Source references
@macro clsourceref{type,package,name}
@end macro

@c Use @clref{package, name} to reference cl definitions

@c Weave Common Lisp function definition
@macro clfunction{package, name}
@end macro

@macro clsourcecode{system,path}
@end macro

@macro setup{things}
@end macro

6 Tips and tricks

• Lisp evaluation

7 API

PACKAGE: DOCWEAVER ¶

External definitions

Macros

Macro: DOCWEAVER:DEF-WEAVER-COMMAND-HANDLER (command-name args (&key docsystem) &body body) ¶

Define a weaver command handler.
COMMAND-NAME is the name of the command, without the prefix (like ’clvariable’, ’clfunction’, etc.)
ARGS is the list of arguments for that command in the DOCSYSTEM implementation.
DOCSYSTEM is a specializer for the documentation system. For example, (eql :texinfo).
BODY should write to an implicit variable, to expand the command.

This is implemented as a wraper over PROCESS-WEAVER-COMMAND .

Generic functions

Generic-Function: DOCWEAVER:PROCESS-WEAVER-COMMAND (docsystem command args stream) ¶

The generic function to specialize for implementing weaving commands for the different documentation systems.

See: DEF-WEAVER-COMMAND-HANDLER

Functions

Function: DOCWEAVER:WEAVE-FILE (file output-file &key docsystem modules command-prefix (parse-docstrings t) (escape-docstrings t)) ¶

Weaves documentation source in FILE and writes the result to OUTPUT-FILE.

Arguments:

- DOCSYSTEM : specify the documentation tool that is being used (:texinfo, :markdown, etc.).
- MODULES : is the list of modules (or ASDF system names) that need to be loaded to be able to read definition descriptions.
- COMMAND-PREFIX : is the character to use as prefix for commands. The character ‘at‘ is the default.
- PARSE-DOCSTRINGS : if T, then docstrings are parsed and highlighted and references to code from it created.
- ESCAPE-DOCSTRINGS: if T, then docstrings are escaped by the documentation system. Escaping allows the use of special documentation system characters in docstring sources. If the escaping of docstrings is turned off, then that allows to use documentation system markup in docstrings.
Category: TopLevel

8 Index