On 12/31/05, Josh Stone <[EMAIL PROTECTED]> wrote: > What bothers me the most about the Hyperspec is that it's inconsistent. > For example, > the entry for "char-code" doesn't even mention an inverse, whereas the > entry for "code-char" has an example that uses #'char-code and a link in > the "See Also" section. Of course, if you go to > Contents->Characters->Character\ Concepts->Introduction\ to\ Characters, > you will see them both listed.
Well for those "errors", have you tried dropping Lispworks a mail? If anyone, they can fix these things. > > One thing that slows people down (and definitely slowed me down for a > long time) is that it's not easy to take existing programming knowledge > and port it to Common Lisp. If I want to write a program in Lisp, my > normal storehouse of programming idioms and techniques may or may not be > doable. I think the Common Lisp Cookbook does a lot to help with this > problem, but it is still very small and has lots of room to grow. I > wonder if the Cookbook doesn't have the kind of recognition it ought to > have? > Well this is obviously something different than the Hyperspec is intended for - its the very technical and concise Lisp standard. And yes, if you could add to the Cookbook, this would be a great help for newbies. > For many, the Hyperspec seems "old school", inefficient, and needlessly > complex. I wish more languages would learn from the example of PHP (not > in terms of the language, but in terms of documentation). Great > searchable documentation, complete cross-referencing of companion > functions for each entry, chapters on lots of aggregate topics, many > (many) examples, and annotations added by those using the documentation > which throws all kinds of usefulness into the bottom of every page. > Every time I have to swish my feet around in it, the documentation never > fails to satisfy. If only the language was prettier ;-). The hyperspec has its place as the pure technical reference. Of course, with a complex language like Common Lisp, this makes for a complex documentation. What is missing perhaps, is a companion for the Hyperspec, which gives a more simplified and newbie-friendly (but hence less exhaustive and complete) access to the standard. I think creating such a companion is quite possible, you could even link into the hyperspec where needed, if you just make it clear enough that you link into another document. Peter _______________________________________________ Gardeners mailing list [email protected] http://www.lispniks.com/mailman/listinfo/gardeners
