Awesome

The qbook lisp documentation system

qbook generates HTML (or LaTeX) formatted code listings of Common Lisp source files. Comments in the source code are rendered as HTML paragraphs, text is rendered in <pre> blocks. Headings are created by preceding the text of the comment with one or more * chars.

This is inspired by Luke Gorrie's pbook.el.

How to use it

Load qbook system

qbook can be started directly from ASDF.

Be sure to have loaded the qbook system:

`(asdf:oos 'asdf:load-op 'qbook)`

Write comments to be formatted as documentation

Write commented text in your Lisp sources, with at least four semi colons.

These are the rules:

• Each top level form is wrapped in <PRE> tagged as pased through to the HTML. The first line (not form) of the top level form is presented in a bold font. If the form is longer than 3 lines it will be truncated to 3 lines and readers will have to click an the form to see the hidden text.

• ;;;; Comments - All lines which start with 4 #\; ("^;;;;") and aren't within a top level form are wrapped in a <P> tag and passed through.

• ; Comments - All comment lines with less than 4 #\; characters are ignored by qbook.

• * Headings - Lines that start with one asterisk * or more are parsed as headings and subheadings.

• @ directives - Lines which start with ;;;;@ are qbook directives. These allow the developer to control how qbook processes the source files. Currently the only supported directive is include.

Add @include directives to your ASDF file. Include the source files you want.

For example, like this:

;;;;@include "src/code-analysis.lisp"

;;;;@include "src/defcode-info-collector.lisp"

;;;;@include "src/html.lisp"

;;;;@include "src/stylesheets.lisp"

;;;;@include "src/latex.lisp"

Publish the documentation

Assuming that your ASDF package is called 'my-system', use the following commands to create the documentation in

1. HTML format:

(qbook:publish-system-qbook :my-system
                        'qbook:html-generator
                        :output-directory "/path/to/folder/"
                        :title "Documentation for my system")

2. LaTeX format:

(qbook:publish-system-qbook :my-system
                             'qbook:latex-generator
                             :output-file "/path/to/file"
                             :title "Documentation for my system")