User Tools


What? Why? How? When?

As for what: I have been growing sick of the current state of Common Lisp documentation in general.

  • The main reference document for Common Lisp, the legendary CLHS, is:
    • based on a standard that - although serving the Lispers well - has its textual inconsistencies and mistakes like every work of such size,
    • dated, as any programming language standard from twenty years ago would be,
    • impossible to edit or fix, according to the license it is distributed under,
    • impossible to extend with new documentation for exactly the same reason,
    • impossible to link with new documentation for exactly the same reason,
    • scaring a lot of people away with its outer look straight out of 1996.
  • The references for many important parts of the Lisp ecosystem - implementations, MOP, ASDF and UIOP, Quicklisp, graphical frontends - are fragmented, in various versions.
  • Many libraries - both ancient and contemporary - despite being working and useful:
    • have their documentation located in various, various parts of the Web. Various documentation aggregators have been designed to aid this, but the documentation they serve in this way is in no way interlinked, consistent or safe from suddenly disappearing,
    • they are sometimes not portable and need work to make them depend on portability libraries instead of implementation-dependent features,
    • have their documentation aggregated on some of the solutions to the aforementioned problem, but they nevertheless depend on whatever the library authors put in Quicklisp, what and where they put on their websites, plus often the only (or almost only) thing available there is a link to an external website,
    • often lack any sensible documentation at all, making them virtually unusable for developers which lack the time to understand or debug the code the slow way.
  • There is very little effective pressure towards changing this state - at least given what I saw and perceived from my very little experience with the Common Lisp community.

This is why the Common Lisp UltraSpec project appeared.

I know that this approach is very prone to breaking, therefore - about how - I want to make a few assertions this project is meant to be achieving at any given moment.

  • The whole documentation is meant to be as complete as possible given its contributors' time and strength, becoming the community-made reference document for the whole Common Lisp universe.
  • For the Common Lisp standard, I do not use any material from the CLHS - instead, I use the third draft of the ANSI CL Standard, put into public domain by its authors - members of the X3J13 itself. The standard, while being copied as close to the original as possible, will be fixed without changing its meaning wherever possible, refined, hyperlinked further
  • I currently use DokuWiki as the backend, which requires only PHP on the server-side, stores its data as a tree of directories and easily parsable and editable TXT files, and makes it possible and easy to make static HTML-only mirrors/snapshots.
  • For the authors of external libraries, I plan on promoting the best documented code. Aside from storing parsed copies of the available documents as pages of the wiki, I want to give people motivation for documenting their Common Lisp libraries - for libraries which have the best external and internal documentation, I want to merge and hyperlink them with the whole rest of the documentation, creating a thought-out, tightly-knitted, well-linked and well-documented reference manual in the effect.
  • The whole documentation is meant to be hosted on Git for ease of cloning, mirroring, version control and cooperation, and released into the public domain.
  • I know that I will need help - and therefore will be looking for contributors to help me by retrieving various Lisp documents that have a license permissible enough to be merged into the wiki, fighting for permission in case of the documents that don't, thinking the whole layout out and cooperating on the tedious work of proper parsing and hyperlinking everything to make this documentation project as usable for the Lispers in general as possible.

As for when - as of writing these words, I've finished porting Chapter 14 - about conses - of the third standard draft to the DokuWiki. It still has some minor bugs, but these will get polished along the way, as it is integrated with the upcoming rest of the standard. This has taken me about a week of somewhat intensive work. At this rate, I expect to have ported and polished the whole standard by the end of 2016 on my own, if time and luck allows. This will be faster if people help - and let me make sure that you know - you're one of the possible helpers. Money is money, it's almost always fun and helping - but what this project really needs is time, attention and love. There's a lot of work to be done for this to become useful, but I think it's more than possible and more than worth the time spent.

And, before you ask - yes, I'll be giving a lightning talk about this on ELS2016.

I hope I've answered all of your questions so far - in case I'm wrong, below is my contact information. As for now - no to jedźmy z tym koksem.

~phoe - Cracow, Poland, 31.03.2016, 02:40 GMT+1