Hacker News Reader

Comment by bjourne | Hacker News Reader

Great story. Unfortunately, the API documentation and tutorial writing guilds went extinct decades ago and has never been able to return to Lispland. :)

View on HN

This is how false misperceptions are spread.

I'd ask you to mention a lisp library which you use but find under-documented (as another reply already has), but I don't think anyone with actual first-hand knowledge of the CL ecosystem would make this comment (even though I'm sure it recieved many enthusiastic if uninformed upvotes).

Lets look at some popular libraries with documentation. - Alexandria http://common-lisp.net/project/alexandria/draft/alexandria.h... - CL-PPCRE http://weitz.de/cl-ppcre/ - metabang-bind http://common-lisp.net/project/metabang-bind/ - not to mention the standard by which all other language documentation should be judged, the CL hyperspec http://www.lispworks.com/documentation/HyperSpec/Front/

And with sites like http://www.cliki.net/, http://common-lisp.net/ and http://www.gigamonkeys.com/book/ and many other full length books, if you can't find lisp documentation you're not looking very hard.

"I don't think anyone with actual first-hand knowledge of the CL ecosystem would make this comment"

I'll make that statement, but only in a somewhat pedantic sense about the language standard itself. Yes, I know CLTL2 is over a thousand pages long, but the one thing about programming languages that always bothers me is undefined behavior. Sadly, even Common Lisp has undefined behavior; Paul Graham's book On Lisp actually relies on undefined behavior being implemented in a particular way e.g. using setq on an unbound variable.

Good documentation should not leave anything undefined; good documentation should leave no questions about the semantics of a system/API/language. Given source code and documentation, it should be possible (perhaps difficult, but possible) for a person to figure out what will happen if the program is run.

The undefined behavior in the Common Lisp specification was a design choice. It has nothing to do with 'good' or 'bad' documentation. Common Lisp was designed from 1981 on. The Lisp community (here the successors of Maclisp) went to explore a lot of new ground: implementations on mini computers, mainframes, super computers, parallel machines, microprocessors, stack architectures, on top of other programming languages like C, etc. There were small and stupid compilers, optimizing compilers, whole-program compilers, ... It was a time of experimentation. At that time a lot of behavior was not defined to allow compiler writes to explorer different types of implementations. With the knowledge of a decade later some of that could have been defined more precisely, but then the standardization process ran out of steam due to lack of funding and interest.

Using SETQ on an undefined variable may be undefined in the Common Lisp standard, but every implementation deals with that and allows it. That's a non-issue. There are a lot of other things which isn't defined in the standard and which all implementations deal with. Garbage Collection. Also not in the standard, but every user expects garbge to be collected.

It would be nice to have less undefined behavior, but it has nothing to do with good or bad. It was useful in a time of experimenting.

Even worse for Common Lisp was that in 1981 there wasn't yet an OOP system for Lisp that was explored and accepted. This way CLtL1 was defined without an object system and it had later to be added (CLOS).

Lisp is very under documented compared to other languages. This makes learning LISP extremely difficult.

Let's take a look at HyperSpec, I follow your link and I'm greeted with a mostly blank (and very ugly) page. Ok there is something called starting points, I guess I'll start there. That page just lists all the indexes. Ok let's try chapters, that sounds like a place to start. Oh yay, another page with nothing but links. Ok, let's try introduction. Again, just a mostly empty page with links. Most people would have given up by now. But lets keep going. Let's try 1.1, which takes us to ANOTHER page of links. I'm feel like I'm getting the run around here. Lets click 1.1.1 and see what happens. Finally I get a page that isn't all links, and it's a single paragraph. What a waste of time.

Let's try another language, how about JavaScript? Google gives me this link: https://developer.mozilla.org/en-US/docs/JavaScript Some helpful information on the first page! Do I want a reference? Do I want a guide? Do I want a re-introduction? Maybe some sites with courses on JavaScript! Wow, that's really useful. Lets just start with the guide because it's "Our primary guide about how to program with JavaScript" and that sounds about right. It takes me to a list of links, Yuck, let's try the fist one called "JavaScript Guide" (Isn't that what I clicked on to get here?). Yup, that link just refreshes the page. That sucks, let's try the second link "About this Guide". A page that describes what I should already know, how to find my way around the guide, and tips for diving into JavaScript.

This is the problem with LISP documentation. At best, if I know exactly what I am looking for I find a giant index. At worst I have no idea what I'm looking for and I get snooty comments from LISPers.

The point is you shouldn't make people look really hard to find information. Good documentation should be easy to find and navigate.

The hyperspec is standard document, not an introduction. It's an invaluable reference you use after you get familiar with the language. I also have emacs set up so that I can look up symbols from within my source, and have the relevant page open up in a w3m window in emacs. I use it constantly and miss the same level of quality and clarity in other language documentation, but you need to get used to it's style and format. If you want to get started with lisp, you go to http://www.gigamonkeys.com/book/ and http://www.cliki.net/

Learning lisp wasn't any more difficult for me than learning any other language. "Practical common lisp" is well written. "Object oriented programming in common lisp" is a well written book as well, "Land of lisp" was fun, and not too bad either.

The core language is extremely well documented and understood. As for the libraries, some of them are well documented, some of them aren't. After the docs for RESTAS started going slightly out of date, I just opened the source and read it all in an afternoon(~600loc), and mostly understood it. I prefer not to have to do that, but claiming it makes it extremely difficult to learn, I don't know, to me it's just an inconvenience, and I have a much better understanding of the framework now, which I couldn't get from just reading docs. And some libraries are so small, I can just figure them all by inspecting the package in slime, and reading the docstrings. Usually there is at least example code. The situation isn't perfect, but it is more than possible to use lisp libraries with great success. Most authors are also pretty approachable on irc or the mailing lists. In other words, I'm a young amateur programmer, who picked common lisp less than two years ago, I'm barely competent as a programmer, and I could figure this all out, why can't expert programmers with years of hacking behind them do the same, I can't understand.

PS as for the ugliness of the hyperspec, I'm happy if it scares away people who get impressed by "modern" design, more than substance and content. I usually read it in text only browsers, and curse docs I can't read well from within emacs. Alt-tabbing to a browser and having to use the mouse while hacking ruins my day :)

Seriously, this is a great point. One of the big problems with a small community of programmers who all think of themselves as elite, is that tasks like documentation and tutorial writing go by the wayside. This comment should be a wake-up call to any smart and far-sighted individuals who want to promote a language.

Is there a open source Common Lisp library that you'd like to see better documented?

Also, if you're (or anyone else is) interested in working on a Common Lisp environment tutorial, shoot me an email. I've been working on one but haven't launched it yet.

> Is there a open source Common Lisp library that you'd like to see better documented?

I was talking as a long time member of a different programming community with similar attributes. (Smalltalk - since 1998)

I would love to see cffi, opengl and one of the gtk binding libs have better documentation.

The opengl bindings don't really need documentation, as they're automatically generated to mirror the C API. Really, if you want to know how to use `cl-opengl`, you memorize a simple naming convention and the rest is a matter of "how do I use OpenGL," not "how do I use cl-opengl?"

That's great, but I haven't learned C. Besides that, leveraging documentation from another language is a hack. As it stands, there isn't documentation around for learning to create 3d graphics without needing to know other languages first.

Are you trolling? First off, learning C well enough to understand opengl documentation will take you much less time that understanding opengl it self(since you'll only need to read and not write C). You have a problem, people gave you a solution, having separate cl docs for opengl that have THE SAME contents, but using lisp function names instead of C ones(as it was explained, it is simple function to transform one into the other in your head). What the hell do you want?

PS I forgot why I stopped commenting on HN threads about lisp. If you read the old usenet, this kind of discussion has been plaguing lisp since day one. People complain, and when given the solution, they just start bitching about something else, avoiding the solution. There are no docs, now the docs are in C, what else? As I've become part of the lisp community, I learned the proper way to fix this, If I encounter deficiency in the lisp ecosystem, I deal with it if I can, and If I can't I politely ask the author/maintainer if they have time to work on the issue. If they don't have the time, I simply accept reality, and move on with my problems. Bitching on HN solves nothing. Honestly, why lisp? Why do people have this supreme need to express their dissatisfaction with a language, with libraries developed by humans in their spare time away from their lives, for free. Be fucking happy, and help out if you care about lisp, otherwise, just shut up!

Why are you angry? It look like you've decided that if people complain about something, those people must be broken and not the system.

And why do people complain about Lisp? It's because the syntax is amazing. It's an incredible language to write in. It is more expressive than anything anyone has ever used, but then they can't do anything with that because it takes so much more effort with lisp to do things that are taken for granted in other languages. GUI libraries and frameworks are so easy with C based languages, because they contain powerful tools that I don't have to write myself.

  GUI libraries and frameworks are so easy with C based languages, because they contain powerful tools that I don't have to write myself.

But you DO have to write them your self. Thats just how open source works. Open source isn't about getting free stuff. People had to write those tools, and they did, because they cared. Lisp isn't so great because McCarty made it great, it's great because for 50 years people worked fucking hard to make it great. Standardizing common lisp took 10 years and a shit ton of money. Every library took months or years out of someones life. You get all that for FREE. If you really care about lisp, you will actually work to make it better. You will be one of those who spend their time and money on it.

Being one of the countless people complaining on forums impresses no one, only makes your ego feel better, doesn't actually help at all. In fact, it's hurtful to lisp, because curious people might read your comments and conclude that lisp isn't worth it for them, and for some of them, it might be, it certainly was for me. So that is why I'm angry. I'm actually trying to help you and lisp, not trying to insult people. If you care about lisp, you'll make it better, if you don't, just do something else, and be happy with it, if lisp can't make you happy. Complaining is a non solution, and I dislike non solutions.

It's NOT a hack because the bindings are calling directly into C. CFFI is a way for lisp to directly run C functions, and a CFFI wrapper does just that: for every function that exists in the OpenGL API, the same function (with the same arguments) exists in the CFFI OpenGL bindings.

Duplicating documentation needlessly is a hack. If your library that you program uses another library, are you required to document that other library as well as your own? No, that library already has documentation.

If you want to learn OpenGL, learn a tiny bit of C. You know what? Learn a tiny bit of C either way. It's the foundation at the core of every program written, no matter what language. Plus, OpenGL is a lot more complicated than C, so you've got your work cut out for you if you can't handle C.

Thankyou for changing my perspective. I've used a fair few high level programming languages, but it's time to get closer to the metal.

And where do I find this "simple naming convention"? I tried google and found repos to the project, but nothing that told me how to read the C documentation and translate it into LISP.

I've never used cl-opengl, but the usual nameing convention for lisp names is as follows:

  name-with-multiple-words

  *global-variable*

so GLOBAL_VARIABLE and NameWithMultipleWords or name_with_multiple_words are easy to figure out. Any body who has used lisp for more than a few days knows how to name things, and since the combinations of naming schemes in C is finite, figuring this out is close to common sense. so glLoadIdentity() in lisp is (gl:load-identity).

Happy Hacking!

I don't know CFFI well enough to take a stab at it. The github manual has a lot of words in it, afaict. :-)

However, I've been longing for getting one of the GTK bindings working for me; when I do that I'll contribute back some docs.

...And cffi is one of the better documented libraries, I have used it quite a bit and have had very little trouble working it out.

Yep. They have time to draw elaborate cartoons, but not elaborate documentation! Funny how that works.

The author (Conrad Barski) wrote a book: Land of Lisp ...

They're alive and well for Racket and Clojure.

Here's a racket guide, which provides detailed documentation for every facet of the language: http://docs.racket-lang.org/

This is why after trying to learn LISP I ended up with Racket.

The comic references clojure in multiple sections (multicore, lazy), I think you'll find the tutorial and documentation guilds still alive and well there.

Actually my snide remark came from trying to find docs for Clojure libraries. :) Clojure Docs (http://clojuredocs.org/) is alright for the standard library, API documentation (http://clojure.github.com/clojure/) not so nice. But finding complete and updated docs for Compojure or any other of Clojure's web frameworks is impossible. Ironically, Noir (http://www.webnoir.org/) seem to be the best documented of the bunch but it has been deprecated.

Reply on news.ycombinator.com