Metaspectre

Metaspectre is a system to parse the draft ANSI standard for Common Lisp (dpANS3), and produce an easily parseable version freed from the difficulty of parsing the original TeX document. A special purpose format, sdoc, has been defined in a simple (NODE PLIST [CHILDREN]) format. This new formatting of the spec is free to use, copy, modify, and distribute.

As a proof of concept, there is an html renderer that consumes the sdoc file. The renderer somewhat mimics the style of the Common Lisp Hyperspec. The document comments, not visible in the Hyperspec, are rendered in the margins as historical notes. You may peruse the rendered website at The Common Lisp Metaspec.

Dependencies

These should be readily available in Quicklisp.

• alexandria for miscellaneous utilities
• cl-ppcre for regex matching
• stencl for html templating in the renderer (not in Quicklisp yet)

Building

• Run git clone https://codeberg.org/dlowe/metaspectre.git to get this source.
• Use asdf or quicklisp to load the metaspectre system.
• Execute (convert-whole-spec) in your favorite Common Lisp implementation, which will output the sdoc.
• Execute (render-whole-spec) which will read the sdoc and output an html rendering.

Publishing

The top-level :metaspectre node in sdoc has :version and :origin properties, which are set by default to "1.0.0x" and "unknown" respectively. They can be overridden with a p-list saved in config.lisp-expr on the project root. When publishing is intended, a version with an incremented patch number should be set, and the origin should be set to the url of a public repository.

On every page, there is an HTML comment with the version, the origin, the build timestamp of the sdoc, and the rendering timestamp of the HTML corpus.

Contents

• doc/metaspec.sdoc is the translated specification.
• doc/output-spec.md describes the sdoc format and how to use it

Differences from the Hyperspec

• Most importantly, it is free to modify and distribute.
• The original TeX is very hard to parse and use for things other than generating a printed copy. The Hyperspec is an HTML rendering which can be parsed as HTML, but loses a lot of information. The Metaspec has an easily parsed intermediate form that can be used for all kinds of purposes, like converting into lookups.
• Math equations are rendered using MathML.
• Includes the acknowledgements and appendix sections.
• Uses progressively enhanced Javascript to provide search and light/dark theme switching.
• Incorporates over 145 patches for content, using corrections accumulated over the years, and documented in the errata page.
• Includes TeX comments, which can contain interesting historical data.
• Includes links and identifiers to bibliographical references.

Searching

The Metaspec HTML render includes a JavaScript search box at the top, as well as a dedicated search page at search.html. If there is a query string q, then the page will redirect immediately on an exact or single match. Otherwise, the query string will simply fill the search box. This enables a user to create a browser shortcut using the string https://metaspec.dev/search.html?q=%s and have CLMS search from the address bar.

Why the name Metaspec?

The official reason:

In Greek, the prefix μετα- indicates a repeated action, reflecting the hopes that this will be the springboard to many more spec versions.

The actual reason:

It's an affectionate reference to the space cadet keyboard which has both Hyper and Meta modifiers.

Acknowledgements

Thanks to CLiki, especially the ANSI clarifications and errata corrections.

Thanks to the libera.chat #commonlisp IRC channel, which has been my primary lisp community for over two decades.