sb-texinfo converts Common Lisp documentation strings for inclusion in a Texinfo manual—which can then be converted into eg. HTML and PDF.
While current implementation is SBCL-only, there is no fundamental reason why support for other Common Lisps could not be added.
sb-texinfo was originally written for processing the SBCL docstrings by Rudi Sclatte in 2004, and has been maintained as part of SBCL since then. This version was split from the SBCL sources in 2011 in order to generalize it for documenting other software. Like SBCL, this manual is in the Public Domain.
sb-texinfo is maintained in Git:
git clone git://github.com/nikodemus/sb-texinfo.git
will get you a local copy.
is the GitHub project page, where the issue tracker is located.
There are two main ways of using sb-texinfo
document-packagewith the name of the package or packages to document. This will produce a Texinfo file containing extracted documentation for the project.
This can be a convenient way to produce a template for further development using the first method, and perhaps more importantly quickly allows you to generate reference documentation for packages with docstrings but no manual.
This manual is produced using the
sb-texinfo.texinfo is the main Texinfo source file, where
docstrings are included.
A Makefile is responsible for running SBCL and the Texinfo toolchain.
Finally, style.css is used to prettify the HTML version.
This produces the following HTML and PDF files:
and a GNU info file as well.
An alternate version of this manual, produced using
(sb-texinfo:document-package :sb-texinfo :output-file "document-package-sample.texinfo")
and further processed using the Makefile linked above:
Creates Texinfo documentation for
output-file, which defaults to the <shortest-package-name>.texinfo. Returns the pathname of the created file as the primary value. An "include/" directory is created in the same location as the Texinfo file, which contains parts included in the Texinfo file.
standaloneis true (the default), a standalone Texinfo file is created. Otherwise a file suitable for including in other Texinfo files is created.
titleis used for the documentation, defaulting to capitalized shortest package name.
The generated Texinfo uses include files generated by
generate-includes, making this function a convenient way to generate an initial template for a manually maintained Texinfo manual.
Returns the pathname used for
document-packagewhen called with the same arguments.
Create files in
directorycontaining Texinfo markup of all docstrings of each exported symbol in
directoryis created if it does not exist yet. Trailing slash is required.
The names of the generated files are of the form<doc-type>-<packagename>-<symbol-name>.texinfo
and can be included in Texinfo source via @include statements. Texinfo syntax-significant characters are escaped in symbol names, but if a docstring contains invalid Texinfo markup, you lose.