About Lectures Research Software Blog
Musical Site

Moods Blog

Dojo Shin Kaï

RSS Feed
Thank you!

XHTML 1.0 conformant
CSS 2.0 conformant
Didier Verna's scientific blog: Lisp, Emacs, LaTeX and random stuff.

Tag - Declt

Entries feed - Comments feed

Tuesday, February 28 2017

Declt 2.1 "Jonathan Archer" is out

I'm happy to announce the release of Declt 2.1 "Jonathan Archer".

New in this release:

  • Handle recent change in SBCL's SB-INT:INFO API.
  • Handle list of contacts (strings) in ASDF systems author and maintainer slots.
  • Some backward-incompatible changes in the keyword arguments to the DECLT function.
  • More hyperlinks between systems and source files.
  • More robust system's packages collection (no more code walking).
  • More robust handling of unavailable ASDF components.
  • More robust naming of cross-references.

Find it at the usual place...

Wednesday, November 4 2015

Declt 2.0.1 "Benjamin Sisko" is out

Declt 2.0.1 "Benjamin Sisko" is out. This is a bugfix release with one internal change (a special variable was not following the earmuffs convention) and one actual bugfix (the same Texinfo anchor was generated for symbols with the same name but in different packages).

Find it at the usual place...

Monday, July 13 2015

Declt 2.0 is out -- IMPORTANT

Declt 2.0 "Kathryn Janeway" is out. This release doesn't contain any change in functionality, yet deserves a major version upgrade since it contains 3 important changes: an infrastructure revamp (along the lines of what Clon endured not so long ago), a license switch from the GNU GPL to a BSD one, and finally a system / package name change. The prefix is now net.didierverna instead of com.dvlsoft. Do I need to apologize for this again? :-)

Find it at the usual place...

Monday, June 29 2015

Declt 1.1 is released


as promised last week, I've just released a new version of Declt, my reference manual generator for ASDF systems. This new version (1.1) is now able to document Clon again (the documentation of which has been updated on the website).

New in this release:

  • Declt now properly handles and documents complex system and component dependencies, such as :feature :require and :version statements,
  • Declt also documents a system's :if-feature if any.

But the most important addition is the ability to document several ASDF systems in the same reference manual. More precisely, Declt now documents not only the main system but also all its subsystems. A subsystem is defined as a system on which the main one depends on in any way, and which is also part of the same distribution (under the same directory tree). Declt also understands multiple system definitions from the same .asd file.


Thursday, June 25 2015

Clon 1.0b24 is released -- IMPORTANT


I'm happy to announce the release of the next beta version of Clon, the Common Lisp / Command Line Options Nuker library. This release doesn't contain much change in terms of functionality, but it contains a lot of change in terms of infrastructure, plus very important and backward-incompatible modifications. So if you're a Clon user, please read on.

First of all, a huge revamp of the library's infrastructure (package hierarchy, ASDF and Make implementations) occurred. A large portion of this work is actually not mine, but Fare's (big thanks to him, 'cause the level of ASDF expertise required just means that I couldn't have done that by myself). The purpose here was twofold: first, remove all logic from the ASDF files (so that other system managers could be used; not sure that's actually useful right now) and second, split the library in two: the core, basic functionality and the non-standard platform-dependent bells and whistles (read: termio support). The result is that Clon now comes with 4 different ASDF systems! A setup system allows you to configure some stuff prior to loading the library, a core system allows you to load only the basic functionality and the regular one loads everything, autodetecting platform-dependent features as before. The fourth system is auxiliary and not to be used by hand. All of this is properly documented. For a code maniac like me, this new infrastructure is much more satisfactory, and I've learned a lot about ASDF less known features.

Next, I've moved the repository to Github. Please update your links! It seems that I've lost all my former tags in the process, but oh well...Only the Git repo has moved. The main Clon web page still contains the full history of tarballs, the preformatted documentation, and will continue to do so in the future.

Finally (I've kept this to myself until the last possible minute because I'm scared like hell to tell): I've changed the systems and packages names... The com.dvlsoft prefix has been replaced with net.didierverna. All other libraries of mine will eventually endure the same surgery. It's for the best, I apologize for it and I swear I will never ever do that again, EVER (fingers crossed behind my back).

So what's next? Before considering an official 1.0 release, there are two things that I want to do. First, cleanup some remaining Fixmes and some shaky error handling. Second, provide an even simpler way of using Clon than what the Quick Start chapter in the doc demonstrates. The idea is to just implement a main function with keyword arguments, and those argument magically become command-line options.

A side-effect of this work is that Declt now chokes on Clon, because some ASDF features that it doesn't understand are in use. So Declt has a couple of new challenges ahead, and you should expect a new release in the weeks to come.

Saturday, August 24 2013

Declt 1.0 is out

After 15 betas, I'm happy enough with the current state of Declt to finally make a 1.0 release.

A lot of things have changed since the previous version, sometimes in a backward-incompatible way. Many more items are documented (including, as you have recently seen, method combinations). In addition to the reference manual, generated by Declt itself, there is now a real user manual.

Declt is still SBCL-only, requires ASDF 3 and Texinfo 4 but generates code that is compatible with Texinfo 5. Also, beware, I've deleted the old repository and moved the project to GitHub. Below is a more precise description of what Declt currently does.

Declt (pronounce "dec'let") is a reference manual generator for Common Lisp libraries. It works by loading an ASDF system and introspecting its contents. The generated documentation contains the description for the system itself and its components (modules and files), the packages defined in that system and the definitions found in those packages.

Exported and internal definitions are listed separately. This allows the reader to have a quick view on the library's public API. Within each section, definitions are sorted lexicographically.

In addition to ASDF system components and packages, Declt documents the following definitions: constants, special variables, symbol macros, macros, setf expanders, compiler macros, functions (including setf ones), generic functions and methods (including setf ones), method combinations, conditions, structures, classes and types.

The generated documentation includes every possible bit of information that introspecting can provide: documentation strings, lambda lists (including qualifiers and specializers where appropriate), slots (including type, allocation and initialization arguments), definition source file etc.

Every documented item provides a full set of cross-references to related items: ASDF component dependencies, parents and children, classes direct methods, super and subclasses, slot readers and writers, setf expanders access and update functions etc.

Finally, Declt produces exhaustive and multiple-entry indexes for every documented item.

Reference manuals are generated in Texinfo format (compatible, but not requiring Texinfo 5). From there it is possible to produce readable / printable output in info, HTML, PDF, DVI and PostScript with tools such as makeinfo, texi2dvi or texi2pdf.

The Declt reference manual is the primary example of documentation generated by Declt itself.

Friday, August 16 2013

Lisp Corner Cases: Method Combinations

In the process of writing Declt, I had to deepen my knowledge of some Lisp corner cases, notably in the area of introspection. As you know, Lisp has in fact more than 2 namespaces. Sometimes, introspecting a potential symbol definition in one namespace is trivial. COMPILER-MACRO-FUNCTION is one example. The "functional" namespace is heterogeneous but you can still make your way out of macros, regular or generic functions very easily. In the same vein, distinguishing constants, special variables and symbol macros in the "variables" namespace is more complicated because there is no standard way to access that information, but with the help of some vendor-specific machinery (e.g. SB-INT:INFO), it's still doable.

At some point, I tackled the case of method combinations, and to my greatest surprise, found out that introspecting a method combination by name is not simple. In fact, it's not even doable. The reason is that method combinations don't have a namespace proper. Let me explain why.

You define a new method combination of some NAME with DEFINE-METHOD-COMBINATION, and you use it with the :METHOD-COMBINATION option to DEFGENERIC. But how do you introspect a NAME for a potential method combination definition? Well, you can't do exactly that. First, there is no standard way to do so. Next, let's look at what the MOP provides. One would expect something along the lines of FIND-CLASS...

There is indeed something called FIND-METHOD-COMBINATION, but either I'm missing something, or it is really, and I mean really badly designed. The arguments to this function are: a generic function meta-object, a method combination name and some method combination options. So if this function is supposed to be the equivalent of FIND-CLASS for method combinations, what in the hell are the 1st and 3rd arguments for? In fact, it's not supposed to do what its name suggests. According to the AMOP, p.191, the purpose of this function is to "determine the method combination object used by a generic function". In practice however (at least in SBCL), it's not doing that either (see below), and anyway, determining the method combination object used by a generic function is better achieved by using the GENERIC-FUNCTION-METHOD-COMBINATION accessor.

So this protocol doesn't seem to make any sense. In order to understand what to make of all this, I looked at how SBCL handles method combinations (I don't know what other vendors do) and here is what I found. When you call DEFINE-METHOD-COMBINATION for some NAME, SBCL creates a new method for FIND-METHOD-COMBINATION, eql-specialized on that NAME. This method is encapsulated in a closure containing the method combination's definition, ignores its first argument (the generic function meta-object; that's why I said that it's not really doing what the AMOP says it does), recreates and returns a new method combination object on the fly every time it is called.

This has several consequences. First, the notion of "method combination named NAME" doesn't really make sense. Method combinations don't have a proper namespace. Every time you create a new generic function, the method combination essentially becomes local to that function. Redefining a method combination has no effect on existing generic functions using a method combination of the same NAME. To put it differently, you can end up with several generic functions using different yet equally named method combinations.

In Declt, I'm now assuming that programmers behave and only define method combinations once. Which brings us to the second consequence. With that assumption in mind, the "proper" way to introspect a NAME for a method combination definition (at least in SBCL) is to first look for the existence of a FIND-METHOD-COMBINATION method eql-specialized on that NAME, and then call it to retrieve the actual definition.

I haven't thought about it a lot yet, but it would be interesting to investigate the idea of cleaning this up a bit. I mean, establishing a real global namespace for method combinations, creating an alternate FIND-METHOD-COMBINATION protocol more along the lines of FIND-CLASS. And then, it could also be interesting to investigate on the potential applications of allowing method combination redefinition to affect live generic functions, just like class redefinition affects live instances...

Tuesday, October 23 2012

Declt 1.0b15 "Kyoto" is out

This is Declt 1.0b15, the "Kyoto" release... Declt is a reference manual generator for Common Lisp libraries.

This version underwent a major internals overhaul, required by some of the new features described below:

  • Packages sections now advertise all definitions instead of just the symbols naming them. They also advertise their use-list and used-by-list, with cross-references.
  • Conditions, structures and classes now advertise their sub- and super-classes, direct methods, initargs and slots, with cross-references.
  • Slots documentation include docstring, type, initargs, initforms, readers and writers with cross-references.
  • Declt now documents symbol macros and compiler macros.
  • The *LINK-FILES* special is gone (M-x all-hail-purely-functional-style).
  • All ASDF components now advertise their descriptions and long descriptions, if any.
  • Docstrings are displayed in a more reader-friendly fashion.
  • Documentation entries for methods are nested within the corresponding generic function entry.

Grab it at the usual place.

Tuesday, September 25 2012

Declt 1.0b14 is out

I've just released a new version of Declt, my reference manual generator for ASDF systems.

This release containts some improvements based on Sabra Crolleton's feedback. The most notable improvements are support for two new license types (MIT and LGPL), a new :DECLT-NOTICE keyword argument that gives you control on the "automatically generated by Declt" notice that appears in the reference manuals, and a bug fix (missing support for empty lists in lambda-lists).

Grab it at the usual place.

Monday, June 4 2012

Declt 1.0b13 is out

I've just released a new version of Declt, my reference manual generator for ASDF systems. This release includes some uninteresting internals update, plus an important bug fix: there were two calls to FIND-METHOD missing an ERRORP flag set to nil, leading to Declt throwing an error where it shouldn't have.

Grab it at the usual place.

Wednesday, June 29 2011

Declt 1.0b12 is out

I've just released the next version of Declt, my reference manual generator for ASDF systems.

This release includes some fixes for the Info format target but most notably, support for documenting (generic) writer functions and methods. When it makes sense, the documentations for func and (setf func) are grouped together. Getting closer to an official 1.0 stable version...

Grab it here, and enjoy!

Tuesday, May 31 2011

Declt 1.0b11 is out

I've just released a new version of Declt, my Texinfo reference manual generator for ASDF systems. This release contains only one bugfix: when trying to create links to source files, Declt now checks whether the files actually exist or not.

Tracking this bug down had the side-effect of exhibiting a misfeature of SBCL's introspection facility: the COPY-<struct> functions (automatically generated by defstruct calls) have their definition source set to target-defstruct.lisp which is an SBCL source file. It would make more sense to set it to the file containing the defstruct call instead, as is already the case for constructors, predicates and accessor functions. Patch sent to the SBCL developers.

Wednesday, February 23 2011

Declt 1.0b9 is out

The next edition of Declt, the Documentation Extractor from Common Lisp to Texinfo, is out. In this release:

  • Bugfix: rendering the documentation for methods with EQL specializers didn't work.
  • Feature: licensing and copyrighting the reference manual is now optional. Licenses currently supported are BSD and GPL.
  • Declt now generates its own reference manual by default.
  • Some package infrastructure changes that should remain transparent.

Grab it here

Happy documenting!

Tuesday, September 21 2010

Declt version 1.0b1 - first public release


I'm happy to announce the first public release of Declt.

Declt (pronounce dec'let) is a reference manual generator for Common Lisp. It extracts and formats documentation from ASDF systems, including the system itself and its components, the packages defined in the system and definitions like constants, special variables, macros, functions, generic functions and methods, conditions, structures and classes.

Reference manuals are generated in Texinfo format which can be subsequently converted into info, HTML, DVI, PostScript or PDF. The generated manuals are fully indexed and provide a complete set of cross-references between documentation elements. For instance, files and packages point to the definitions they provide, and those definitions point back to package and file in which they can be found.

Get it at:
http://www.lrde.epita.fr/~didier/softwa ... .php#declt

Declt requires SBCL to work (if you're interested in porting it, grep
PORTME in the sources). Also, ASDF 2 has not been tested yet.
French Flag English Flag
Copyright (C) 2008 -- 2013 Didier Verna didier@lrde.epita.fr