[Gardeners] Mangling the hyperspec

[Peter Herth]

On 12/31/05, Josh Stone <lispniks at josho.org> 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