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.
qbook can be started directly from ASDF.
Be sure to have loaded the qbook system:
`(asdf:oos 'asdf:load-op 'qbook)`
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"
Assuming that your ASDF package is called 'my-system', use the following commands to create the documentation in
- HTML format:
(qbook:publish-system-qbook :my-system
'qbook:html-generator
:output-directory "/path/to/folder/"
:title "Documentation for my system")- LaTeX format:
(qbook:publish-system-qbook :my-system
'qbook:latex-generator
:output-file "/path/to/file"
:title "Documentation for my system")