qbook generates html 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:
1) 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.
2) All lines which start with 4 #\; ("^;;;;") and aren't within a top level form are wrapped in a <P> tag and passed through.
3) All comment lines with less than 4 #\; characters are ignored by qbook.
4) Lines that start with one asterisk * or more are parsed as headings and subheadings.
5) 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.
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")
This is the core of qbook, the driver code which takes a lisp source file and generates an html file.
Function PUBLISH-QBOOK Convert FILE-NAME into a qbook html file named OUTPUT-FILE with title TITLE.
qbook parses lisp code into a list of source-file-part objects. we have an object for code parts (each top level form is considered as a single code object), for comments and for headings.
Class SOURCE-FILE-PART A part of a source file.
Directives are a way to control how qbook processes the lisp code. We currently only support the '@include "filename"' directive. @include allows multiple source files to be combined to form a single html file.
A qbook source file is a lisp source file. Qbook uses the lisp's reader to parse the code (so any valid lisp should be usable). qbook looks for a few things in the lisp file:
1) The code. 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.
2) ;;;; Comments - All lines which start with 4 #\; ("^;;;;") and aren't within a top level form are wrapped in a <P> tag and passed through.
3) ; Comments - All comment lines with less than 4 #\; characters are ignored by qbook.
4) * Headings - Lines that start with one asterisk '*' or more are parsed as headings and subheadings.
5) @ 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.
A decent example of a qbook'd lisp file is qbook itself. qbook.asd contains the include directives which control the order of the sections while the various .lisp files contain qbook comments, qbook headings and ignored comments (every source file contains a copyright message which we don't want to have repeated multiple times in the html)
There is none. You simply can't create tables or produce links or bold text. Patches welcome.
Source code reading consists of the following steps:
1) Read source into parts
2) Post process (merge sequential comments, setup headers, etc.)
3) Handle any directives.
4) Gather any extra source code info
5) Setup navigation elements
6) Remove all the parts before the first comment part
Function READ-SOURCE-FILE Parse a Lisp source code file into parts
Function COLLECT-CODE-INFO Collect specific info for each source code part using ANALYSE-CODE-PART.