Re: newbe: documentation string length

On 2005-11-19 15:58:08 +0000, Harald Hanche-Olsen <hanche@xxxxxxxxxxxx> said:

+ verec <verec@xxxxxxx>:

| Let's face it: CL is a monster

I'll leave that particular bit of flame bait alone. 

No flame intended. With about 1000 predefined "things", CL
certainly doesn't qualify as a reading companion for my
weekly 3 hours train journey back from London to Paris.

For good or bad, CL is *huge*. And it takes time, effort
and dedication to make progress. Whether some elitists consider
this "feature" as way to eliminate feable minds such as mine is
entirely their calls.

| and the CLHS is THE example of how to write a user hostile
| documentation.

The CLHS is just fine for what it is: A /reference/.  It is not a
tutorial, and was never intended as such.


Certainly, but ... this is a *poor* reference: let me document:

I was looking for the format special characters (the s, d, x and
other stuff after the ~). Do you think there is a single place
where the CLHS would document it? Nope! All scattered in various
more or less logical places.

You go here first
file:///Users/verec/Tools/LispWorks%20Personal%204.4.6/Library/lib/4-4-0-0/manual/online/web/CLHS/Body/f_format.htm

Find 

nothing but a hint at "section 22.3" so you go there

file:///Users/verec/Tools/LispWorks%20Personal%204.4.6/Library/lib/4-4-0-0/manual/online/web/CLHS/Body/22_c.htm

Read 

all of 22.3.1 to 22.3.12, and still can't find a single place
where they're all listed. I just wanted a simple table!

talk of a _reference_ !

The intended audience for a
reference is people who already have a pretty good idea how it all
hangs together, but need a place to look up the specifics in all their
horrific detail.


But even for people with actual working knowlege of the language,
I find it extremely deceptive. Most links are just brain dead links.
Sure they work, and are technically correct. They're just useless.
(Kind of reminds me of an old joke ...)

 (This hasn't stopped me from learning from the CLHS,
but maybe I'm a computer language masochist.  I never would have
managed it without a good book like Graham's ANSI Common Lisp to get
me started, though.  Or at least, it would have taken me a lot
longer.)


When the only thing you have is pretty bad, that's still the
only thing you have!

I learnt _more_ in _less_ time by reading Siebel or Graham book, than
by perusing the CLHS. YMMV of course.

| I'm learning Lisp, one ( at a time :-)

Fine, and good luck to you.  When you feel like learning another
tidbit, consider learning about read macros.  You might wish to use
them instead of #.(...) magic to format your doc strings.


That's a helpful hint. Many thanks.... Back to CLTL2, now, to read
about "read macros" ... not the CHLS, unless I want, again, to get
confused and come back empty handed :-(

--
JFB  ()

.

Relevant Pages

  • Re: AAMT responds to Nuance/Dictaphone acquisition, Kaiser Permanente goes to the Dragon
    ... The macros especially. ... If you have no interest in learning something, then it's going to be extremely difficult to learn or impossible to learn. ... However, you have no interest in or desire to learn Dragon, so it would a total waste of your time to even try. ... I don't feel comfortable accepting those kinds of favors from friends. ...
    (sci.med.transcription)
  • Re: VBA or Visual Basic?
    ... VBA is based in VB Classic, and is the language used by the programs to ... Within these macros, you have great ... created on my machine using Word and Excel macros. ... > I had learnt Visual Basic first, as a mtetr of fact still learning. ...
    (microsoft.public.word.vba.beginners)
  • Re: VBA or Visual Basic?
    ... Within these macros, you have great ... >> Hi Sam, ... >> I had learnt Visual Basic first, as a mtetr of fact still learning. ... >> concepts in VBA too, the visual basic editor in word etc, are almost the ...
    (microsoft.public.word.vba.beginners)
  • Re: Time to develop adequate Macro and VBA knowledge
    ... When learning something new, I find I have to achieve something, so when it ... given what you are trying to learn the topics above are the basics in any ... I totally agree with the thing about macros I personally never use them if I ... can do it in vba, learn vba it is very powerful. ...
    (microsoft.public.access.gettingstarted)
  • Re: newbe: documentation string length
    ... The CLHS is just fine for what it is: ... (This hasn't stopped me from learning from the CLHS, ... managed it without a good book like Graham's ANSI Common Lisp to get ...
    (comp.lang.lisp)