I think most of you will agree that once you're hooked on Common Lisp
you realize that you've found a language which has things to offer
that no competitor has, so I won't discuss this any
further. Nevertheless, CL is also a language that is somewhat hard for
newcomers, especially for those who've used other, more widespread
languages before: I come from the Perl/C/Java camp (and this is how I
pay my rent) and there are myriads of _simple_ tasks that I could
implement in these languages without thinking while I would have to
work hard to get them done in CL. This is what this posting is about:

I now that many c.l.l regulars despise Perl, but I hope you'll agree
that the Perl community has a couple of things that we can learn
from. The one thing that I'm going to talk about here is the famous
(?) Perl Cookbook (see < http://www.*-*-*.com/ ;), a
nice little book that provides concise, elegant and instructive
answers to seemingly simple questions like "You need to find the
number of days between two dates or times" or "You want to get a list
of filenames similar to MS-DOS's *.* and Unix's *.h", or "You want to
access or modify just a portion of a string, not the whole thing". If
you've been using Lisp since the day you were born this might seem
trivial to you, but judging from my experience - and from many
questions I've read in this newsgroup - many of these simple tasks
seem to be harder than they should be in CL (and they are usually not
dealt with in the standard literature, i.e. Graham, Norvig,
Winston/Horn, and so on).

This posting is a proposal for a community effort to provide a "Common
Lisp Cookbook" that will mimick the Perl Cookbook (or similar sources
for Java, python and other languages). It'll provide 'recipes' that'll
help you in implementing mundane stuff and thus enabling you to get
more comfortable with the language as well as giving you more time to
think about the stuff that's really hard (and would probably be a pain
to do in other languages).

I hereby volunteer to organize/maintain this project if enough people
are willing to help. I will also be able to host the project (see
below) if this will be the agreed-upon way to do it. Following are a
couple of thoughts about the Cookbook project. I hope many people will
have something to say about it - additions, corrections, improvements,
suggestions, comments are welcome (and should be directed to the
newsgroup and not to my email address).

[Disclaimers: 1. I'm rather new to CL. I'm lightyears away from being
the Tom Christiansen of Common Lisp, so I will need the help of as
many people as possible. (A newbie might be able to ask the right
questions but somebody has to answer them...) 2. I have a family to
feed, so I can't guarantee to keep any terms.]

Having said that, here comes the main stuff:

0. What it is and what it isn't.

- This'll be about ANSI Common Lisp, not about Scheme, Emacs Lisp,
  AutoLisp, or whatever.

- The target audience are people who are new to (Common) Lisp - people
  who have just discovered the language and are willing to learn it.

- The Cookbook will provide small code snippets as answers to
  frequently asked questions usually beginning with "How do I..." (see
  above for examples). The code should ideally be accompanied with a
  discussion of how it works and what has to be paid attention to plus
  pointers to relevant chapters in books, online articles or the
  CLHS. (The standard article in the Perl Cookbook has four parts:
  "Problem", "Solution", "Discussion", "See also". An example can be
  found at
  < http://www.*-*-*.com/ ;.)

- The project does not aim to supplant introductory books or the
  HyperSpec. People who use the Cookbook are expected to know the
  language basics and to consult the CLHS if necessary.

- The Cookbook should be agnostic to operating systems and
  implementations if possible. It will surely be necessary to provide
  information that is specific to a certain OS or vendor (especially
  if we're talking about non-ANSI stuff) but it would be nice if
  readers had a choice between different versions.

- Contributions to the Cookbook aren't expected to be exhaustive or
  worthy a Pulitzer Price. On the contrary - I am convinced that at
  least thirty percent of the typical newbie questions can be answered
  by pointing them to a specific function entry in the CLHS (or - even
  better - by providing a one-line solution).

- Due to the nature of this there will be some intersection with the
  c.l.l FAQ (recently revived by Christophe Rhodes at
  < http://www.*-*-*.com/ ~csr21/lispfaq.html>), but I think
  these projects are different enough to warrant two distinct
  documents.

- This'll be an ongoing collaborative effort and it will be perfectly
  OK to just post a good question. Let someone else take care of the
  answer.

1. Content

Here's a quick sketch of the content in very rough form. It's
assembled from the O'Reilly Books, the CLHS, and from postings to this
newsgroup.

- Basics: Installation, Loading and Compiling
- Numbers: BIGNUMS, rationals, complex numbers
- Strings / Regular Expressions
- Dates and Times
- Arrays
- Hash Tables
- Lists/Conses
- Structures
- CLOS
- Other data structures: Btrees, Queues, Linked Lists
- Iteration: LOOP, SERIES, MAP functions
- Searching and Sorting
- Input and Output, Streams, FORMAT, the Lisp Reader
- Conditions, Error Handling
- File Access, File Contents, Directories
- Packages
- Defsystem
- Debugging, Profiling, Advice
- Database Access
- Sockets
- Internet Protocols, Web Serving
- Multi-Processing, Multi-Threading
- FFI, Extending and Embedding CL
- Communicating with other processes
- GUI
- I18N
- XML
- MOP

This is of course open to discussion. I'm sure I've missed
something. Also, I'm not sure about the correct order and I'm aware of
the fact that I've mixed rather basic stuff with advanced topics.

Let me repeat that I think the basic stuff is important and this'll be
what the Cookbook is about. Many Lisp newcomers have an idea how to
implement something in their preferred programming language but they
tend to feel lost if they're to choose from the wealth of built-in
functions and data types that CL has to offer.

2. Infrastructure / How to do it

2.1. The first thing that comes to mind (and has been mentioned here
     already) is CLiki. The good thing about it is that it's already
     there and we can simply start hacking in questions and
     answers. But I think it might be better if we had some means to
     organize the whole project - providing for ways to easily
     re-structure the whole document and for automatic generation of
     different formats like HTML, TeX, PDF...

2.2. That's why I think a custom-tailored database-backed website
     would be the best solution. As with CLiki, everybody should be
     able to add content or change what's there already (maybe after
     registering once with his name and email address). I would
     volunteer to set up such a thing (although I'd currently write it
     in mod_perl/DBI - shame on me - rather than in CL/USQL) and
     provide a server to host it.

     [This could be somewhat similar to the Python Cookbook at
     < http://www.*-*-*.com/ ;. I haven't
     looked at every detail but it seems to be OK.]

2.3. As an alternative one could start a Sourceforge project to host a
     couple of Texinfo files. Contributors would have to use CVS.

3. License

This will be a collaborative effort, so we'll have to find a license
that seems fair to everyone who contributes code and advice. I'm not
familiar with Open Source Documentation Licenses. What do you think
would be the best one and why?

4. "Prior Art"

I'm pretty sure that most of the stuff that would go into this
Cookbook has already been posted to c.l.l at least once by very
knowledgeable people, it's just a matter of finding and organizing
it. Would you think it'll be OK to take a code snippet from
groups.google.com, put it into the Cookbook and add a reference like
"posted to comp.lang.lisp by Donald Duck at Dec 12, 1996 as

restrictions?

OK, I hope this is enough to start a discussion and to solicit more
input. I'm really willing to do this - not only because I'm a good guy
(ahem) but mainly because I think it'll be a very good way to improve
my own knowledge of Common Lisp. It'd be great if many others would
join this project for whatever reasons they might have.

Thanks for your time,
Edi.

Sorry for answering to myself but this might be interesting:

<http://slashdot.org/article.pl?sid=02/01/23/2022235&mode=thread&thres...>

Edi.

[snip...]

Don't forget those who learned Lisp in some recent (or distant) past but are
coming back to it.

[snip...]

If they end up having too much intersection it will be possible to merge
them anyway.

[snip...]

sexpr ?

Argh! mod_perl.... Please use mod_lisp or any CL web server ;-)

Marc

One of my servers has mod_lisp installed and I'm experimenting with
CMUCL there. However, if I would write the application with mod_lisp
and CL I'd need _much_ more time for it (while mod_perl is my
bread-and-butter currently). Installing UncommonSQL alone might take
me a couple of hours... :(

[This is a FreeBSD machine, no CCLAN and apt-get install available.]

Once the Cookbook is finished all this will be much easier of
course. Version 2.0 will be hosted by a CL web server... :)

Cheers,
Edi.

Why do you want a SQL database ? For now you have 0 article so you don't
need an SQL database. Even when you have lots of articles, you won't need an
SQL database.
As I wrote in the previous post, you can use sexprs to store the data. Or
some CLOS objects in a hash table or in a list. There are lots of quick
start solutions.

To start you just need a server, apache, mod_lisp and an HTML generation
macro and that's it.
Start with an in memory database saved as an ascii file (remember Lisp has a
nice reader). It's better to have a working solution in a few days and then
to refine it when it is a huge success.

Then you can put in it the first article : How to write a successful web
application in Lisp in 3 days...

Marc

I think this is a very good proposal indeed, and highly refreshing,
after all the constant whining that has been posted here during the
last couple of weeks.  I'll add a couple of comments below:

I think it wouldn't hurt to let the focus expand as needed, to include
not quite so new people, who are still willing to learn common idioms,
etc.  There are quite a number of known idioms for slightly
advanced/specialized stuff, which would profit from being presented in
a cookbook/recipe like style, like MOP-stuff, etc.

It might be useful to start off with CLiki (possibly on a separate
site), and expand the mark-up stuff, and reorganization facilities...

Legally, the stuff posted to newsgroups is covered by copyright laws,
although the application of copyright law to Usenet is probably not
very well understood.  I.e. one would presume that certain rights are
implicitly granted by posting, like e.g. the right to redistribute
and copy for the purposes of dissemination on Usenet servers.  There
are also the obvious rights granted under fair-use, but one of the
problems with this is that the relation of quoted and unquoted amounts
are taken into consideration, and it is easy to fall afoul of this
requirement with Usenet postings, which are already quite small.

On the whole I'd advise that you get the permission of the poster
(either for an individual posting, or for all postings on c.l.l by the
given poster) prior to inclusion, since this is the best way to cover
yourself, and it might also lead to further interesting input from the
poster, e.g. by pointing out better, or more relevant code in another
posting/source, or by informing the poster of the existence of your
project, which might lead to the poster participating more directly,
or giving you pointers to other interesting articles in the past or
the future.

You might want to contact Paolo Amoroso, who has been doing excellent
work as the editor/creator of the EncyCMUCLopedia, and who will
probably be able to give you more advice on this, and related matters.

Including pointers to the original article is also very important from
the POV of the user, since it gives him the ability to read relevant
parts of the whole thread that give him more context and background on
the why of that particular solution.  This prevents the cookbook
approach from degenerating into a simple clipboard to copy from
without understanding, but as a valuable starting point for a journey
that results in deeper insight into the language, and the problem and
solution spaces surrounding a particular question.

Regs, Pierre.

--

 The most likely way for the world to be destroyed, most experts agree,
 is by accident. That's where we come in; we're computer professionals.
 We cause accidents.                           -- Nathaniel Borenstein

If you are looking for a caned app type of solution, take a look
at openacs.org.  It looks like what you want in the first draft of
the site is already there:
sql back end(postgres and oracle)
message boards
administrative interface, create/modify/delete message boards ...
full text search

I have installed it a few times to play with and have gotten it running
on freebsd. I would be willing to help install/manage it.

A couple of possible issues:
it uses aolserver not apache
tcl is the scripting language

marc

Absolutely -- I'd welcome contributors over here too; time is
limited... :)

I do want to get the FAQ up to postable state, but, alas, the real
world is intervening at the moment.

Christophe
--
Jesus College, Cambridge, CB5 8BL                           +44 1223 510 299
http://www-jcsu.jesus.cam.ac.uk/~csr21/                  (defun pling-dollar
(str schar arg) (first (last +))) (make-dispatch-macro-character #\! t)
(set-dispatch-macro-character #\! #\$ #'pling-dollar)

Quite simple. For each batch of newsgroup or mailing list postings from a
same author that I plan to include in a version of the EncyCMUCLopedia, I
contact the author asking for permission, and including all material for
his reference and convenience. Then I include in the EncyCMUCLopedia
distribution a copy of each posting with full headers as received by my
mail/newsreader, adding a blurb such as "included with permission" in each
index entry.

As Pierre suggests, I have found that contacting authors provides valuable
additional feedback on the material I am interested in.

As for useful tools with which to maintain the Cookbook, I suggest Edmund
to have a look at the SBCL Internals Documentation project, which has
similar technical requirements and is based on CLiki technology:

  http://ww.telent.net/sbcl-internals/index

Paolo
--
EncyCMUCLopedia * Extensive collection of CMU Common Lisp documentation
http://web.mclink.it/amoroso/ency/README
[http://cvs2.cons.org:8000/cmucl/doc/EncyCMUCLopedia/]

[...]

This will be extremely useful for people like me who know something of the
Lisp language but have little experience using it for daily work. I
currently use CMUCL for experimenting with ideas in an Emacs/ILISP buffer,
but I'd like to go beyond that.

I think one of the first hurdles is understanding the package system and
installing new 'modules' (for want of correct terminology). People quite
often complain that the free Lisp implementations lack GUI toolkit support,
database access and so on. It's obviously not true. The packages are out
there, but the installation instructions, if present, often assume prior
knowledge of how Lisp packages work, how they're loaded, how they're used,
etc.

I confess with some embarrassment that I don't know anything about this, and
have not found any idiot-proof instructions. Whilst I could probably install
any package through trial and error, I do think that Common Lisp's way of
handling packages and installing/loading of extensions is sufficiently
different from other languages to merit some basic explanation. Even simple
concepts like "saving an image", which experienced Lisp users naturally take
for granted, are alien to most people who come to Lisp from other languages.
In my opinion, this would be a good place to start.

If we had a page with detailed step-by-step instructions on how to set up,
say, Clisp or CMUCL with a commonly requested configuration, eg. complete
with bindings to GTK+ and MaiSQL, it would give the user the background s/he
needs to install other packages when the time comes.

I think your project is an excellent idea.
I will certainly be willing to contribute when I can.

Well, we sort of do, but currently it starts with
"1. Install Debian..."
because that is the only "Operating Environment" that
common-lisp-controller, or any equivalent to my knowledge, runs
on. Counterexamples are welcome :)

Christophe
--
Jesus College, Cambridge, CB5 8BL                           +44 1223 510 299
http://www-jcsu.jesus.cam.ac.uk/~csr21/                  (defun pling-dollar
(str schar arg) (first (last +))) (make-dispatch-macro-character #\! t)
(set-dispatch-macro-character #\! #\$ #'pling-dollar)

On Fri, 25 Jan 2002 05:50:05 +1100, "novice106"

Last weekend I tried to install lispdebug for CLisp.
Apparently the maintainer of lispdebug stopped maintaining the
CLisp version ( this is a guess ) and the package system changed so
that CLisp no longer installs.
I've gone over to the CLisp mail-list and been trying to get some
help, but things have started to get testy over there. ( I'm try to
not let the tone get to hot. )

Excellent! I these are all topics that we would love to see addressed
from the "pragmatic" programmer's perspective--especially those topics
that are never formally addressed.

-dj

 >
 > This posting is a proposal for a community effort to provide a "Common
 > Lisp Cookbook" that will mimick the Perl Cookbook (or similar sources
 > for Java, Python and other languages). It'll provide 'recipes' that'll
 > help you in implementing mundane stuff and thus enabling you to get
 > more comfortable with the language as well as giving you more time to
 > think about the stuff that's really hard (and would probably be a pain
 > to do in other languages).

I too think that this is a great project, and I'll be glad to
contribute if (as I hope) it gets off the ground. Just a few comments:

 > - This'll be about ANSI Common Lisp, not about Scheme, Emacs Lisp,
 >   AutoLisp, or whatever.

Agreed.

 > - Due to the nature of this there will be some intersection with the
 >   c.l.l FAQ (recently revived by Christophe Rhodes at
 >   <http://www-jcsu.jesus.cam.ac.uk/~csr21/lispfaq.html>), but I think
 >   these projects are different enough to warrant two distinct
 >   documents.

It's good to see that the FAQ is being revived, first of all. I agree
on the "two documents" strategy, but I also think that the two projects
should be coordinated. The FAQ could act as an "entry level" document,
pointing to the relevant sections of the Cookbook when necessary for
people who want more detail. The Cookbook would in turn point to the
CLHS, newsgroup messages, online resources, etc. for even more detailed
info. I also think the FAQ could benefit from a little restructuring:
for example, the first entry in section 4 (Programming Questions) is
about how to write a 'Hello World' program, and the second one deals
with FLET. Quite a big conceptual gap, I'd say...

 > 2. Infrastructure / How to do it
 >
 > 2.1. The first thing that comes to mind (and has been mentioned here
 >      already) is CLiki. The good thing about it is that it's already
 >      there and we can simply start hacking in questions and
 >      answers. But I think it might be better if we had some means to
 >      organize the whole project - providing for ways to easily
 >      re-structure the whole document and for automatic generation of
 >      different formats like HTML, TeX, PDF...
 >
 > 2.2. That's why I think a custom-tailored database-backed website
 >      would be the best solution. As with CLiki, everybody should be
 >      able to add content or change what's there already (maybe after
 >      registering once with his name and email address). I would
 >      volunteer to set up such a thing (although I'd currently write it
 >      in mod_perl/DBI - shame on me - rather than in CL/USQL) and
 >      provide a server to host it.
 >
 > 2.3. As an alternative one could start a Sourceforge project to host a
 >      couple of Texinfo files. Contributors would have to use CVS.

Being one of the many people who use Lisp for database-backed web
applications, I like solutions 1 and 2, but I'm concerned that the time
to design and set up such an environment might be too long, causing the
project to lose momentum. I'd rather see it start in a simple way
(solution 3, or HTML, or even plain text files) than not start at all.

Anyway, thanks for doing this, and let us know when and how we can start
contributing!

--
Alberto Riva
Children's Hospital
Informatics Program