Consider
(defun resize-array (array amount) ;; improved version thanks to Fred Gilham
"Expands array by the specified amount and returns the possibly new
array. Amount can be negative"
(adjust-array array (+ (length array) amount)))
This is all fine and good as:
CL-USER 14 > (documentation 'resize-array 'function)
"Expands array by the specified amount and returns the possibly new
array. Amount can be negative"
Except that, the line is too long *in the definition*. ie: it doesn't
fit my self-imposed
80 characters per line limit.
So, I'd rather type
;
234567890123456789012345678901234567890123456789012345678901234567890123456789
(defun
resize-array (array amount) ;; improved version thanks to Fred Gilham
"Expands array by the specified amount and returns the possibly new array.
Amount can be negative"
(adjust-array array (+ (length array) amount)))
Except that if I do so, I get:
CL-USER 15 > (documentation 'resize-array 'function)
"Expands array by the specified amount and returns the possibly new array.
Amount can be negative"
So, my question really is: is there a way to split the documentation string on
multiple lines, so that it fits some formatting constraints, yet have
(documentation)
not take those line breaks into account, a bit like a HTML browser just ignores
them?
--
JFB ()
On 2005-11-19 11:50:43 +0000, verec <·····@mac.com> said:
> So, my question really is: is there a way to split the documentation string on
> multiple lines, so that it fits some formatting constraints, yet have
> (documentation)
> not take those line breaks into account, a bit like a HTML browser just ignores
> them?
Well, I figured that what I needed was a macro:
(defmacro doc-string (string-list)
"Concatenates all the strings into one, suitable for documentation to
display"
`(concatenate 'string ,@string-list))
This seems to work in the REPL:
CL-USER 57 > (doc-string ("this +" "is +" "a + test"))
"this +is +a + test"
And the macro-expansion seems to look right
CL-USER 59 > (ppmx (doc-string ("this +" "is +" "a + test")))
Macro expansion:
(CONCATENATE 'STRING "this +" "is +" "a + test")
So I set out to try it, in situ:
;
234567890123456789012345678901234567890123456789012345678901234567890123456789
(defun
resize-array (array amount) ;; improved version thanks to Fred Gilham
(doc-string
("Expands array by the specified amount"
" and returns the possibly new array."
" Amount can be negative"))
(adjust-array array (+ (length array) amount)))
The function does compile fine, but when I try to access the
documentation:
CL-USER 68 > (documentation 'resize-array 'function)
NIL
What am I missing?
--
JFB ()
On 2005-11-19 13:09:21 +0000, verec <·····@mac.com> said:
> (defmacro doc-string (string-list)
> "Concatenates all the strings into one, suitable for documentation to
> display"
> `(concatenate 'string ,@string-list))
> ;
> 234567890123456789012345678901234567890123456789012345678901234567890123456789
(defun
>
> resize-array (array amount) ;; improved version thanks to Fred Gilham
> (doc-string
> ("Expands array by the specified amount"
> " and returns the possibly new array."
> " Amount can be negative"))
> (adjust-array array (+ (length array) amount)))
> CL-USER 68 > (documentation 'resize-array 'function)
> NIL
I think I understand what is happening, but I'm at loss
as to how to fix it.
What I beleive is occuring is that defun expects a string
for the documentation string, not a macro whose expansion
generates a string.
I suspect that the generated code does create the concatenated
string at run time, only to discard it, since the actual result
is the value of the last setf form.
CL-USER 69 > (disassemble 'resize-array)
; Loading /Users/verec/Tools/LispWorks Personal
4.4.6/Library/lib/4-4-0-0/load-on-demand/ccl/dis.nfasl on demand...
#x0: #x80F80692 lwz tmp1,#x692(nil)
[...]
#x24: #x83D70006 lwz const,#x6(func)
#x28: #x80FE001D lwz tmp1,#x1D(const) ; call-counter
#x2C: #x30E70004 addic tmp1,tmp1,#x4
#x30: #x90FE001D stw tmp1,#x1D(const) ; call-counter
#x34: #x607B0000 ori r27-p,res/arg0,#x0
#x38: #x609C0000 ori r28-p,arg1,#x0
#x3C: #x807E002D lwz res/arg0,#x2D(const) ; STRING
#x40: #x809E0031 lwz arg1,#x31(const) ; "Expands array by
the specified amount"
#x44: #x80BE0035 lwz arg2,#x35(const) ; " and returns the
possibly new array."
#x48: #x80DE0039 lwz arg3,#x39(const) ; " Amount can be negative"
#x4C: #x82FE003D lwz func,#x3D(const) ; CONCATENATE
#x50: #x38000004 li nargs,#x4
[...]
#x64: #x82FE0041 lwz func,#x41(const) ; LENGTH
[...]
#x9C: #x82FE0045 lwz func,#x45(const) ; ADJUST-ARRAY
[...]
#xE4: #x4E800420 bctr
58
NIL
CL-USER 70 >
So I'm a bit confused now. I thought that macros where only
evaluated at compile time, so I expected my doc-string to do
its stuff then. Apparenty, defun disagrees with me. How can
I convince defun that what I want is this macro-expansion result
to be slotted into its documentation string?
Many Thanks.
--
JFB ()
verec <·····@mac.com> writes:
> So I'm a bit confused now. I thought that macros where only
> evaluated at compile time, so I expected my doc-string to do
> its stuff then. Apparenty, defun disagrees with me. How can
> I convince defun that what I want is this macro-expansion result
> to be slotted into its documentation string?
Yes, that's what happens when you're careless: you get confused.
Macros are not expanded at compilation time.
They're expanded at macro-expansion time!
Macro-expansion time may occur at compilation time, or at run time.
--
__Pascal Bourguignon__ http://www.informatimago.com/
Grace personified,
I leap into the window.
I meant to do that.
On 2005-11-19 15:08:34 +0000, Pascal Bourguignon <····@mouse-potato.com> said:
> verec <·····@mac.com> writes:
>> So I'm a bit confused now. I thought that macros where only
>> evaluated at compile time, so I expected my doc-string to do
>> its stuff then. Apparenty, defun disagrees with me. How can
>> I convince defun that what I want is this macro-expansion result
>> to be slotted into its documentation string?
>
> Yes, that's what happens when you're careless: you get confused.
As much as I appreciate your technical expertise, I cannot
agree with such a harsh judgment. You are not qualified to
assess how I learn, and whether my way of learning is appropriate,
or not, for me. I'm the sole judge of that.
Let's face it: CL is a monster and the CLHS is THE example of
how to write a user hostile documentation. Each time I have a
problem, I cycle through the CLHS first, note that I don't
understand most of the giberish, falls back to the CLTL2 *book*
(yeah! in print, on actual _paper_), carry on Peter Siebel site
hunting for examples, and finally Googling my way to actual
examples when all else fails.
My posting on c.l.l is really my last resort.
There are people who like to absorb some huge theory first, and,
at some point, try it on real-life examples. I'm not one of them.
I'm learning Lisp, one ( at a time :-)
> Macros are not expanded at compilation time. They're expanded at
> macro-expansion time!
>
> Macro-expansion time may occur at compilation time, or at run time.
Thanks for the clarification.
--
JFB ()
+ verec <·····@mac.com>:
| Let's face it: CL is a monster
I'll leave that particular bit of flame bait alone.
| 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. 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. (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.)
| 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.
--
* Harald Hanche-Olsen <URL:http://www.math.ntnu.no/~hanche/>
- Debating gives most of us much more psychological satisfaction
than thinking does: but it deprives us of whatever chance there is
of getting closer to the truth. -- C.P. Snow
On 2005-11-19 15:58:08 +0000, Harald Hanche-Olsen <······@math.ntnu.no> said:
> + verec <·····@mac.com>:
>
> | 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 ()
verec <·····@mac.com> writes:
> On 2005-11-19 15:58:08 +0000, Harald Hanche-Olsen <······@math.ntnu.no> said:
>> | 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:
That's like saying that Lisp's syntax is poor because it's hard
to keep track of all the parentheses. Traditionally, Lisps have
never stood alone on the language definitions themselves, and the
documentation is no exception.
> 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.
> 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!
It's not a table, per se, but go to
http://www.franz.com/search/index.lhtml#ansispec and type
format tilde characters
into the serch criteria field (and click on the search button).
Having a well-indexed document is usually not a problem when
you have the right tools to look for what you need.
--
Duane Rettig ·····@franz.com Franz Inc. http://www.franz.com/
555 12th St., Suite 1450 http://www.555citycenter.com/
Oakland, Ca. 94607 Phone: (510) 452-2000; Fax: (510) 452-0182
On 2005-11-19 22:26:56 +0000, Duane Rettig <·····@franz.com> said:
> It's not a table, per se, but go to
> http://www.franz.com/search/index.lhtml#ansispec and type
> format tilde characters
>
> into the serch criteria field (and click on the search button).
Indeed. The result pages shows all of those I knew of.
OTOH, typing do, or do* in the same search field yields
no result, while typing "let" seems to send the server
into some infinite loop ... (OK 50s ish wait until
the page appears :-)
While it seems that the final destination is the standard
hyperspec somehow "pretty printed" it is still the same
document with the same self-referential internal links
that do not bring much while trying to understand the big
picture.
> Having a well-indexed document is usually not a problem when
> you have the right tools to look for what you need.
No tool is going to _invent_ examples that are simply
not there ... and the cross indexing of "symbols", "form"
"expression" and the like isn't really of much use. What
would have been much better would have been a "syntax"
chapter, separate, but learning, for *every* *single*
*definition* that they use "forms" made of "symbols"
grouped into "expressions" is a bit redudantly useless...
--
JFB ()
verec <·····@mac.com> writes:
> On 2005-11-19 22:26:56 +0000, Duane Rettig <·····@franz.com> said:
>
>> It's not a table, per se, but go to
>> http://www.franz.com/search/index.lhtml#ansispec and type
>> format tilde characters
>> into the serch criteria field (and click on the search button).
>
> Indeed. The result pages shows all of those I knew of.
>
> OTOH, typing do, or do* in the same search field yields
> no result, while typing "let" seems to send the server
> into some infinite loop ... (OK 50s ish wait until
> the page appears :-)
Well, yes, the tools can always stand improvement. But do,
do*, and let are simple words that can be hard to search for
textually, but which can also be looked up in the index. Also
available is our permuted index:
http://www.franz.com/support/documentation/7.0/doc/permuted-index.htm
> While it seems that the final destination is the standard
> hyperspec somehow "pretty printed" it is still the same
> document with the same self-referential internal links
> that do not bring much while trying to understand the big
> picture.
Right. It is a _reference_, not a textbook or tutorial.
>> Having a well-indexed document is usually not a problem when
>> you have the right tools to look for what you need.
>
> No tool is going to _invent_ examples that are simply
> not there ... and the cross indexing of "symbols", "form"
> "expression" and the like isn't really of much use. What
> would have been much better would have been a "syntax"
> chapter, separate, but learning, for *every* *single*
> *definition* that they use "forms" made of "symbols"
> grouped into "expressions" is a bit redudantly useless...
We'll all have to keep you in mind for the next Ansi Spec iteration
:-)
--
Duane Rettig ·····@franz.com Franz Inc. http://www.franz.com/
555 12th St., Suite 1450 http://www.555citycenter.com/
Oakland, Ca. 94607 Phone: (510) 452-2000; Fax: (510) 452-0182
On 2005-11-20 04:09:48 +0000, Duane Rettig <·····@franz.com> said:
> We'll all have to keep you in mind for the next Ansi Spec iteration
>
> :-)
If it was only me ...
But I'm just not interested in embarking in another long rant/flame
about whether "Lispers" want to compete against the "Java crowds"
or not.
Make up your own judgement as to what is useful and whaty isn't.
--
JFB ()
On 2005-11-19 16:33:20 +0000, verec <·····@mac.com> said:
Sorry for the local URLs. I meant:
http://www.lispworks.com/documentation/HyperSpec/Body/f_format.htm
and
http://www.lispworks.com/documentation/HyperSpec/Body/22_c.htm
respectively.
--
JFB ()
+ verec <·····@mac.com>:
| 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!
Okay, that would have been nice.
| That's a helpful hint. Many thanks.... Back to CLTL2, now, to read
| about "read macros" ...
Actually, they're called reader macros. I mistyped. But by now, you
probably have that one figured out.
--
* Harald Hanche-Olsen <URL:http://www.math.ntnu.no/~hanche/>
- Debating gives most of us much more psychological satisfaction
than thinking does: but it deprives us of whatever chance there is
of getting closer to the truth. -- C.P. Snow
On 2005-11-19 17:19:58 +0000, Harald Hanche-Olsen <······@math.ntnu.no> said:
> + verec <·····@mac.com>:
>
> | 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!
>
> Okay, that would have been nice.
>
> | That's a helpful hint. Many thanks.... Back to CLTL2, now, to read
> | about "read macros" ...
>
> Actually, they're called reader macros. I mistyped. But by now, you
> probably have that one figured out.
Yep.
I also found out that
http://psg.com/~dlamkins/sl/chapter03-12.html
and
http://psg.com/~dlamkins/sl/chapter03-11.html
where quite helpful too.
Thanks again.
--
JFB ()
verec <·····@mac.com> writes:
> 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.
> [...]
> 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 ...)
Indeed, we could add some better cross indexing layers on CLHS.
specbot helps a little here, you can type:
/msg nickserv set unfiltered on ; once
/msg specbot clhs ~s ; for each clhs reference
in irc://irc.freenode.org/#lisp
go get the right link.
--
__Pascal Bourguignon__ http://www.informatimago.com/
You're always typing.
Well, let's see you ignore my
sitting on your hands.
verec wrote:
>
> Certainly, but ... this is a *poor* reference: let me document:
>
Then how do you explain that many people find it a good reference?
Wade
On 2005-11-19 22:34:45 +0000, Wade Humeniuk
<····················@telus.net> said:
> verec wrote:
>> Certainly, but ... this is a *poor* reference: let me document:
> Then how do you explain that many people find it a good reference?
I don't! :-)
I find that I spend less time finding what I'm after by looking
into the CLTL2 printed edition, than trying to make head or tail
of the verbiage in the CLHS. On the other hand, the searching tool
at Franz that I just discovered does bring summary pages that are
not present in the orginal. That makes it a far better experience
but that's still the same old CLHS underneath ...
--
JFB ()
verec <·····@mac.com> writes:
> 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.
The CLHS is a language standard, and one of the better.
The worst thing a standard can do is contradict itself and the
procedure adopted by most standard committees to avoid this is to
avoid redundance. Information is stated typically Once And Only Once.
--
"a totalitarian ideology that hates freedom, rejects tolerance,
and despises all dissent." --- Bush describing his religious
constituency^W^W^Wthe Iraqi resistance
On 2005-11-20 15:33:01 +0000, Lieven Marchand <···@wyrd.be> said:
> verec <·····@mac.com> writes:
>
>> 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.
>
> The CLHS is a language standard, and one of the better.
>
> The worst thing a standard can do is contradict itself and the
> procedure adopted by most standard committees to avoid this is to
> avoid redundance. Information is stated typically Once And Only Once.
The worst thing a standard can do is to be useless to the community
it is meant for. Don't confuse the means and the goals.
--
JFB ()
On Sun, 20 Nov 2005 22:19:15 +0000, verec <·····@mac.com> wrote:
> The worst thing a standard can do is to be useless to the community
> it is meant for.
As others have already pointed out the community the standard is meant
for is mostly that of the language implementors.
From 1.1.1:
"It is a language specification aimed at an audience of implementors
and knowledgeable programmers. It is neither a tutorial nor an
implementation guide."
You're probably not (yet) part of that community.
> Don't confuse the means and the goals.
And you shouldn't do it either.
Cheers,
Edi.
--
Lisp is not dead, it just smells funny.
Real email: (replace (subseq ·········@agharta.de" 5) "edi")
On 2005-11-20 22:25:20 +0000, Edi Weitz <········@agharta.de> said:
> On Sun, 20 Nov 2005 22:19:15 +0000, verec <·····@mac.com> wrote:
>
>> The worst thing a standard can do is to be useless to the community
>> it is meant for.
>
> As others have already pointed out the community the standard is meant
> for is mostly that of the language implementors.
>
> From 1.1.1:
>
> "It is a language specification aimed at an audience of implementors
> and knowledgeable programmers. It is neither a tutorial nor an
> implementation guide."
>
> You're probably not (yet) part of that community.
That's certainly true. But in that case, would people be kind
enough not to refer to it in answering questions that obviously
come from a newbie such as myself?
You see, consitency has to be both ways :-)
--
JFB ()
>>>>> "v" == verec <·····@mac.com> writes:
[on references to the hyperspec]
v> ... But in that case, would people be kind
v> enough not to refer to it in answering questions that obviously
v> come from a newbie such as myself? ...
I was just asking about this to newbies elsewhere. Would you really
prefer that people didn't refer to or quote from the hyperspec?
Assuming people have the time to do it, would you rather see simple
examples or possibly slighty wrong prose in somewhat imprecise
language than that of the hyperspec?
cheers,
BM
Bulent Murtezaoglu <··@acm.org> writes:
>>>>>> "v" == verec <·····@mac.com> writes:
> [on references to the hyperspec]
> v> ... But in that case, would people be kind
> v> enough not to refer to it in answering questions that obviously
> v> come from a newbie such as myself? ...
>
> I was just asking about this to newbies elsewhere. Would you really
> prefer that people didn't refer to or quote from the hyperspec?
> Assuming people have the time to do it, would you rather see simple
> examples or possibly slighty wrong prose in somewhat imprecise
> language than that of the hyperspec?
Hopefully I don't qualify as a newby anymore but I have spent some
time in recent years thinking about how to present Common Lisp to
newbies. It seems to me that some of us occasionally lapse into using
the CLHS as an intellectual weapon--"Well, duh, if you just look at
6.2.3.4.1 combined with the third sentence of the second paragraph of
5.4 it's clear that ..."
Once you know you're way around the CLHS it's an invaluable tool but
it can take some getting use to--both the organization and such
details as the difference between things like "signals an error" and
"should signal an error". With that in mind, I'd imagine that pointing
newbies to the right place in the Hyperspec with maybe a bit of
explanation to help them understand what they'll find when they get
there would be quite helpful. But to imply that someone is dumb or
lazy just because they haven't been able to resolve their own
confusion by referring to the Hyperspec seems a bit harsh.
-Peter
--
Peter Seibel * ·····@gigamonkeys.com
Gigamonkeys Consulting * http://www.gigamonkeys.com/
Practical Common Lisp * http://www.gigamonkeys.com/book/
>>>>> "PS" == Peter Seibel <·····@gigamonkeys.com> writes:
PS> ... It seems to me that some of us occasionally
PS> lapse into using the CLHS as an intellectual weapon--"Well,
PS> duh, if you just look at 6.2.3.4.1 combined with the third
PS> sentence of the second paragraph of 5.4 it's clear that ..."
Oh, _that_ problem. Yes, I understand now. I'd say it is percieved
to be happening more often than it actually happens though.
PS> ... But to imply that someone is dumb or lazy just
PS> because they haven't been able to resolve their own confusion
PS> by referring to the Hyperspec seems a bit harsh.
I agree. I forgot what went on upthread, so I don't know if you are
referring to anything in particular, but I'd say again the dumb and lazy
part might not actually be intended at all. As you point out in the
part I deleted, the skill to use the Hyperspec to good effect is
invaluable if not essential. Most of the time people just want the
newbie to get used to helping himself, IMHO. Or, perhaps I've spent
too much time on usenet and can only detect the grossest slights.
cheers,
BM
From: Kent M Pitman
Subject: Re: newbe: documentation string length
Date:
Message-ID: <umzjy1vqa.fsf@nhplace.com>
Bulent Murtezaoglu <··@acm.org> writes:
> >>>>> "PS" == Peter Seibel <·····@gigamonkeys.com> writes:
>
> PS> ... It seems to me that some of us occasionally
> PS> lapse into using the CLHS as an intellectual weapon--"Well,
> PS> duh, if you just look at 6.2.3.4.1 combined with the third
> PS> sentence of the second paragraph of 5.4 it's clear that ..."
>
> Oh, _that_ problem. Yes, I understand now. I'd say it is percieved
> to be happening more often than it actually happens though.
>
> PS> ... But to imply that someone is dumb or lazy just
> PS> because they haven't been able to resolve their own confusion
> PS> by referring to the Hyperspec seems a bit harsh.
>
> I agree. I forgot what went on upthread, so I don't know if you are
> referring to anything in particular, but I'd say again the dumb and lazy
> part might not actually be intended at all. As you point out in the
> part I deleted, the skill to use the Hyperspec to good effect is
> invaluable if not essential. Most of the time people just want the
> newbie to get used to helping himself, IMHO. Or, perhaps I've spent
> too much time on usenet and can only detect the grossest slights.
I also concur with this general view that you and Peter are putting
out here, btw. I'm always excited when people say they found CLHS
approachable, but it was never intended as tutorial material--that's
just gravy. We talked in committee about having a standard teaching
order even in some other document and decided there was neither a
canonical teaching order nor a canonical theory of subsetting; so we
discarded the idea. And the standard itself would have been
overconstrained if it had catered too closely to teaching.
What I tried to do was to lift the parts of CLTL that were in the wrong
place and move them to easier to find places. e.g., if memory serves,
I believe the only place CLTL mentions left-to-right order of evalution
are in a passage related to setf and another related to defsetf and yet
another related to arithmetic type contagion, all of which promise to
preserve the order. So we tried to centralize it where it belonged. And
there were discussions in some functions on various datatypes of the nature
of data they operated on, but sometimes it wasn't clear (I think for
things like namestrings in the pathname functions) whether the description
was a general definition of the type, or a special case of the type as used
in that function alone. Again, it had to be untangled.
And then the question became duplication. People wanted type trees but also
class precedence lists. We decided it was better to have only one and to let
the other be inferred from the first, so that we didn't contradict ourselves
by accident (as noted in another thread). But that was NOT a way of saying
type trees aren't visually useful tools. We just said "gee, this is long
already, let's not clutter it further with redundancy at the risk of
contradiction". We figured it would be fine to have some books by others
explaining what they'd inferred from the standard.
What I like about the standard and about CLHS personally is that it mostly
achieves the goal of letting ordinary people off the street who have a
question about something, actually read the source material. So if they
wonder if an author is right about what they wrote, they can check. While
I understand there's some value to a standard written in formalese, one of
its disadvantages is that it isn't "accessible". That's why there's the
glossary. The language is a product of its culture, and while I introduced
a couple of the words in the glossary myself, mostly those words all
pre-dated the language and helped to define it. They're vague or ambiguous
once in a while, and we try to overcome that vagueness where it occurs. But
the language is a product of a long and very thoughtful history that has
grown up with those words, and I think the standard shows that it's no
accident that if you start with those words that thoughtful people speak
among themselves and build upward from there, you can get to something
useful. In a world where so much of the culture is about people learning
to be more computer-like, I find it nice to see some things about computers
try to cater to people.
But back to the original point that the thread seemed to be buzzing about,
I think it's wise, all other things being equal, if people don't just throw
newbies at CLHS without a few examples or at least a few urls. Expecting
they'll start from page 1 and read forward to what they need is a bit much.
Certainly telling them that they are dummies or lazy or anything because
they aren't up to that isn't helpful. Among other things, it suggests that
our community is not sensitive to the value of their time. And I think one
of the reasons people like Lisp is that it's supposed to save them time.
So it sends the wrong message when you say people are supposed to spend large
amounts of up-front time as the cost of admission.
+ verec <·····@mac.com>:
| On 2005-11-20 15:33:01 +0000, Lieven Marchand <···@wyrd.be> said:
|
|> The CLHS is a language standard, and one of the better.
|> The worst thing a standard can do is contradict itself and the
|> procedure adopted by most standard committees to avoid this is to
|> avoid redundance. Information is stated typically Once And Only Once.
|
| The worst thing a standard can do is to be useless to the community
| it is meant for. Don't confuse the means and the goals.
I don't see any such confusion here. Goal: The standard should not
contradict itself. Means: State things in one place only. It's
quite simple, really. It may not be the only way to achieve the goal,
but it is most likely the simplest.
And as for the community the standard is meant for? That community
usually consists of implementors. It is generally assumed that a
litterature will spring up to support the users. The Lisp community
is fortunate in having an implementor's standard that is readable by
users, even though you seem to disagree. It seems clear to me that a
major reason for this lucky state of affair is the enormous amount of
effort Kent Pitman has put into maintaining and cross-indexing the
standard as it evolved.
But yes, in some respects we could need even more and better indexes.
One can always use more indexes and overviews. I am sure if someone
were to create a page listing all the format directives, for example,
with a one-line synopsis for each and properly hyperlinked into the
CLHS, the community would happily accept it.
--
* Harald Hanche-Olsen <URL:http://www.math.ntnu.no/~hanche/>
- Debating gives most of us much more psychological satisfaction
than thinking does: but it deprives us of whatever chance there is
of getting closer to the truth. -- C.P. Snow
On 2005-11-20 22:33:06 +0000, Harald Hanche-Olsen <······@math.ntnu.no> said:
> + verec <·····@mac.com>:
>
> | On 2005-11-20 15:33:01 +0000, Lieven Marchand <···@wyrd.be> said:
> |
> |> The CLHS is a language standard, and one of the better.
> |> The worst thing a standard can do is contradict itself and the
> |> procedure adopted by most standard committees to avoid this is to
> |> avoid redundance. Information is stated typically Once And Only Once.
> |
> | The worst thing a standard can do is to be useless to the community
> | it is meant for. Don't confuse the means and the goals.
>
> I don't see any such confusion here. Goal: The standard should not
> contradict itself. Means: State things in one place only. It's
> quite simple, really. It may not be the only way to achieve the goal,
> but it is most likely the simplest.
>
> And as for the community the standard is meant for? That community
> usually consists of implementors. It is generally assumed that a
> litterature will spring up to support the users. The Lisp community
> is fortunate in having an implementor's standard that is readable by
> users, even though you seem to disagree. It seems clear to me that a
> major reason for this lucky state of affair is the enormous amount of
> effort Kent Pitman has put into maintaining and cross-indexing the
> standard as it evolved.
>
> But yes, in some respects we could need even more and better indexes.
> One can always use more indexes and overviews. I am sure if someone
> were to create a page listing all the format directives, for example,
> with a one-line synopsis for each and properly hyperlinked into the
> CLHS, the community would happily accept it.
CLTL2 and the Java Language spec were authored by the same person.
It is just a coincidence if the JLS is a model of clarity and the
CLHS is not?
CLTL2 is also a model of clarity (unfortunately, pre-ANSI).
Or is just that the whole idea of "hyper-links" is just a flawed
idea to start with (the JLS is a PDF!)
Oh, and while I'm at it, in the J world, they were able to separate
the JLS, for users and implementors alike, from the JVMS for implementors
only.
--
JFB ()
In article <·························@news.aaisp.net.uk>,
verec <·····@mac.com> wrote:
> CLTL2 and the Java Language spec were authored by the same person.
> It is just a coincidence if the JLS is a model of clarity and the
> CLHS is not?
>
> CLTL2 is also a model of clarity (unfortunately, pre-ANSI).
>
> Or is just that the whole idea of "hyper-links" is just a flawed
> idea to start with (the JLS is a PDF!)
Uhm, there're no hyperlinks in the CL ANSI standard either.
Neither CLTL2 nor JLS are ANSI standards. Perhaps the amount of rigor
required to get accepted by a standards body accounts for your perceived
lack of readability.
-bcd
--
*** Brian Downing <bdowning at lavos dot net>
Brian Downing <·············@lavos.net> writes:
> Neither CLTL2 nor JLS are ANSI standards. Perhaps the amount of rigor
> required to get accepted by a standards body accounts for your perceived
> lack of readability.
Actually the problem is sometimes the opposite. One is aware
that one is reading a specification and expects it to read
like a legal document with clauses and sub-clauses spreading
out in a tree. In particular, one steels oneself to slog
through sub-clauses that don't apply in order to find the one
that does, and one also expects this pay-off: the enumerations
are exhaustive.
So one expects that each sentence is complete in itself and
tells you the full story, and one expects to pay a heavy
price for this, that the sentence runs on for many pages :-)
To see this not working out look at
3.8 The Evaluation and Compilation Dictionary
Declaration SPECIAL
<snip>
A special declaration does not affect inner bindings of a
var; the inner bindings implicitly shadow a special
declaration and must be explicitly re-declared to be
special. special declarations never apply to function
bindings.
<snip>
When used in a proclamation, a special declaration
specifier applies to all bindings as well as to all
references of the mentioned variables. For example,
after
(declaim (special x))
then in a function definition such as
(defun example (x) ...)
the parameter x is bound as a dynamic variable rather
than as a lexical variable.
That is not the way to write specifications and other
reference material. The correct way is tree off the options
so that it is always explicit whether or not there is more
relevant material to come. For example
1)A special declaration may or may not affect the inner
bindings of a variable.
1.1)We distinguish the two cases by either saying that
the variable has been "proclaimed special" or "declared
special".
1.1.1)There are four ways in which
a variable |x| may be "proclaimed special"
1)(defvar x)
2)(defparameter x)
3)(proclaim '(special x))
4)(declaim (special x))
1.1.2)In all other cases the special declaration causes the
variable to be "declared special"
1.2)When a variable has been "proclaimed special" the special
declaration specifier applies to all bindings as well as to
all references of the mentioned variables. For example,
after
(declaim (special x))
then in a function definition such as
(defun example (x) ...)
the parameter x is bound as a dynamic variable rather than
as a lexical variable.
1.3)When a variable has been "declared special" the special
declaration does not affect inner bindings of a var; the
inner bindings implicitly shadow a special declaration and
must be explicitly re-declared to be special. special
declarations never apply to function bindings.
2)We know we are done here, both by the numbering of the
clauses and by the structure of the text that, at each
stage, announces the options, and then works through
them in order.
If you like viewing train wrecks look at this from
5.3 The Data and Control Flow Dictionary
Special Operator LET, LET*
Syntax:
The form
(let ((var1 init-form-1)
(var2 init-form-2)
...
(varm init-form-m))
declaration1
declaration2
...
declarationp
form1
form2
...
formn)
first evaluates the expressions init-form-1, init-form-2,
and so on, in that order, saving the resulting values. Then
all of the variables varj are bound to the corresponding
values; each binding is lexical unless there is a special
declaration to the contrary. The expressions formk are then
evaluated in order; the values of all but the last are
discarded (that is, the body of a let is an implicit progn).
No, no, no, this just won't do. You cannot say
unless there is a /foo/ to the contrary.
in a specification. The whole point of a specification is to
be specific. What constitutes "a special declaration to the
contrary"? Where do we have to look to find one? Must it be
one of declaration1 to declarationp?
In
(let (x)
(declare (special x))
(let (x)
;;; think about the inner x
Is the outer declaration a declaration to the contrary? A
specification is supposed to say not tease!
This needs to be written along the lines
each binding is lexical unless either
i)one or more of declaration1,..,declarationp
declare the variable to to special
ii)the symbol naming the variable has been proclaimed
to be special at an earlier time, anywhere in the
program.
It is sometimes the lack of rigour in the hyperspec that
makes trying to learn from it an ordeal.
The question that I find especially interesting is "Who is
to blame?"
The ANSI specification was at heart a commerical
enterprise. Fail to come up with a Common Lisp and the DoD
would spend its money elsewhere. There is a case to be made
that the specification cost more than the participants could
afford, users dropped out, vendors went bust. As the AI
winter closed in one could also argure that the
specification took too long to write, and missed the market
window.
Comparing the quality of the work to the real world
constraints under which it was performed I'm receptive to
the argument that the specification represents all that was
humanly possible and that its authors can be justly proud of
what they achieved.
The moral I'm minded to draw is that the ANSI
standardisation process is flawed. What we want is fixity of
meaning. What we get is fixity of text.
ANSI do not distinguish between altering the text in order
to uphold the original meaning and altering the text to order
to change the meaning. Consequently, if the meaning is
difficult to express, abstract in nature, and to be fixed
for a long time, the ANSI process is not appropriate.
Think of reading the standard as part of the process of
learning the language. It is off limits to the concept of
process improvement. If a particular paragraph becomes
notorious for confusing beginners it stays notorious for
confusing beginners. The only way to open up the text of an
ANSI standard for changes is to open up the meaning of the
text for changes, and that is a very different goal, which
is in conflict with the notion of improving the existing
process.
Alan Crowe
Edinburgh
Scotland
From: Kent M Pitman
Subject: Re: newbe: documentation string length
Date:
Message-ID: <ulkz5jwsk.fsf@nhplace.com>
Alan Crowe <····@cawtech.freeserve.co.uk> writes:
> Brian Downing <·············@lavos.net> writes:
>
> > Neither CLTL2 nor JLS are ANSI standards. Perhaps the amount of
> > rigor required to get accepted by a standards body accounts for
> > your perceived lack of readability.
>
> Actually the problem is sometimes the opposite. One is aware
> that one is reading a specification and expects it to read
> like a legal document with clauses and sub-clauses spreading
> out in a tree. In particular, one steels oneself to slog
> through sub-clauses that don't apply in order to find the one
> that does, and one also expects this pay-off: the enumerations
> are exhaustive.
Yes, this is quite true. But it's not a requirement on standards,
interestingly enough. It's sort of something I/we came to as we
bumbled around trying to find good ways to present things... in
part because it's natural for people to ask questions of this form
and one has a desire to answer them.
Probably the key glaring omission in this regard is a simple
enumeration of the namespaces. I believe there to be four (variable,
function, block/return, and tagbody/go), but I shied away from from
putting them into the spec because by the time I thought it would
invite painful last minute debate on what it meant to be a "namespace"--
whether there was a sense in which classes ought to be a namespace,
whether #'(setf foo) names were a separate namespace from the #'foo
namespace, etc.
> So one expects that each sentence is complete in itself and
> tells you the full story, and one expects to pay a heavy
> price for this, that the sentence runs on for many pages :-)
>
> To see this not working out look at
>
> 3.8 The Evaluation and Compilation Dictionary
> [...]
> That is not the way to write specifications and other
> reference material. The correct way is tree off the options
> so that it is always explicit whether or not there is more
> relevant material to come. For example [...]
Good examples, and I agree completely with your point insofar
as it addresses a reasonable goal state for a standard.
As you perhaps know, I normally make a point of not really
debating criticisms of the standard when I perceive they're
legitimate. And I'm ceding that your point is legitimate. But
I'll make an exception and defend the standard on this point
anyway because there's a useful point to be made. (One I've made
before but it bears periodic repeating.)
Here's the thing:
Standards come in different kinds. Some are "from scratch". Some are
"legacy". The issue with "legacy" standards is that the designers
were not free to make incompatible changes. Every change from the
status quo required a vote. As a consequence, the central issue here
was budget.
I've made a periodic show of relating this to world politics, just to
keep things fun, so I'll do it again here by contrasting the standard
with the Iraq war in that it's popular for the Bush camp over the last
few years to defend the war against the straw man that no one is
really holding up "would you really want Saddam back in power?". Of
course most sensible people wouldn't. And if framed that way, the
argument might seem to be between "people who think the Iraqis
shouldn't have been freed" and "people who think they should have
been". That, of course, forces a certain outcome to the discussion
but it doesn't address the totality of the debate.
IMO, the fair way to frame the debate isn't "should this war have been
fought" but "who should be paying for this war?". I think that to the
extent that the US benefits from the outcome of the war, the US should
pay some. But since the primary benefit goes to the Iraqis, and a
secondary benefit goes to other nations that were in direct danger,
those countries are not paying their fair share. And the question
"should we abandon the Iraqis at this point?" which Bushi is presently
asking loudly (urged on by Lieberman) is properly reframed "should the
US continue to be paying?" The Iraqis now have a government. Just as
an example, that government could, now that it's formed, if it's
worried about us pulling out, offer to pay money to offset at least
our dollar costs, even if its people aren't trained up to do the work.
It's all about budget. How long can you go before there's resolution.
"Where is he going with this?" I can hear you ask just about now.
Well, the choice simply wasn't between words like you're offering and
words like the standard contains. We started with CLTL as the
standard. Not just conceptually, but literally. Not everyone knows,
but Kathy Chapman, my predecessor, literally began with that source
and just rearranged it, trying to make it more "spec-like". When I
took over from her, I continued the process. At some point, Steele
agreed for purposes of copyright that the document was so
substantially rearranged that its original form was negligibly
maintained and that there was no sense in which we needed concern
ourselves with copyright concerns. But always throughout, there was
the issue of the "truth" (which cannot be copyrighted, but neither
could it be altered willy-nilly without sacrificing a legacy culture
of users).
So there were places the language was just ill-specified for legacy
reasons and the parlance of the process came to include statements by me
like "Since no one can tell me what happens in thus-and-so case, I'll
just make it 'explicitly vague'." I tried to identify points of confusion
in the spec and to make them not too embarrassing while at the same time
permitting us to upgrade as time permitted.
This issue was especially important to me personally because, as the record
shows, I was personally involved as a technical advocate. I tried to use
the "hats" metaphor, such that when I was "wearing the hat" of a technical
contributor, I permitted myself to advocate for a position on how the
language should change, but while "wearing the hat" of an editor, I was not
permitted to make any change that would (even allegedly) improve or clarify
the language without authorization.
Sometimes there were things I could do that would make the language better
without changing it, by exposing regularity that was there but not documented.
The two best cases of this were "generalized boolean" and "designators", both
of which were introduced without a technical vote because they were really
already true of the language, just never presented in those ways. But most
issues did not resolve that way.
On a day by day basis, I had to pick up the worst chapter and just rearrange
it hoping to make its meaning (or non-meaning) as apparent as possible,
but the document is just large, and like the Iraq war, the process just went
on longer than there was really budget for. The question became who would
pay and who was benefiting. I think the costs were unfairly distributed,
and the real heros of the process were the companies that continued to fund
the effort when a lot of the early contributors fell away, just to see it
through.
But at some point, we had to do the Viet Nam thing and just declare
victory. There is more that many wanted of this standard, but those
people who wanted more weren't the ones paying. :) It had gotten to
the point where it wasn't all we wanted, but at the same time, it was
easily usable for the purpose it was designed for--to answer
commercial questions and yield usable implementations. It did and
does that, warts and all.
As the possibly apocryphal PhD student is alleged to have said, if I'd had
more time, I'd have written something shorter.
> The moral I'm minded to draw is that the ANSI
> standardisation process is flawed. What we want is fixity of
> meaning. What we get is fixity of text.
I think it's more complex than that from the outset because even before
you are into the process, ANSI does not distinguish between "from scratch"
works and "legacy" works. It permits either. But the writing suggestions
for either is the same. And yet, existing documents which might spawn a
desire for standards are sometimes not in a form such that shooting for that
particular goal is practical. I'm not sure this could really be fixed, but
I'm pointing out that the goal you set is unrealistic from the start.
> ANSI do not distinguish between altering the text in order
> to uphold the original meaning and altering the text to order
> to change the meaning. Consequently, if the meaning is
> difficult to express, abstract in nature, and to be fixed
> for a long time, the ANSI process is not appropriate.
ANSI doesn't do this because its primary purpose, as expressed to us on
the first meeting, is to avoid lawsuits. Its secondary purpose is to make
standards. Once it starts to make subjective calls, it's wide open to suit.
This is why when the standard was held up for nearly a year (as I
recall--my memory might be dimming at this point) at the last minute
when someone during a technical review asked a non-technical question,
ANSI couldn't just rule the question non-technical and proceed. It
had no mechanism, and was afraid that the process of ruling it
non-technical and having that challenged would take it longer than
just treating the question as technical and responding in the normal
way.
> Think of reading the standard as part of the process of
> learning the language. It is off limits to the concept of
> process improvement. If a particular paragraph becomes
> notorious for confusing beginners it stays notorious for
> confusing beginners. The only way to open up the text of an
> ANSI standard for changes is to open up the meaning of the
> text for changes, and that is a very different goal, which
> is in conflict with the notion of improving the existing
> process.
It is for this reason that I believe the filibuster is a critical patch
to a bug in the US Constitutional amendment system. Failing to make
Constitutional amendments on abortion, flag burning, and gay marriage,
the US Republicans have taken to trying to change the meanings of words
already in the Constitution--cleverly while at the same time mounting a
campaign saying that the others have already done this and that they're
just "fixing things". (The truth, of course, is that there is no such
thing as "neutral meaning" and any change, right or left, is a change.
There is no "neutral" and "extreme" interpretation. There are just
"interpretations that agree with who's speaking" and "interpretations
that don't".) But the Republicans noticed that a change to the supreme
court takes a 2/3 majority, while a change to the court does not. The
court doesn't change the Constitution, but it changes the way the words
are interpreted. So by a simple majority, they now seek to change the
Constitution using a technique like the one you cite. That's why the
filibuster is important.... it re-establishes a 2/3 requirement where
one always should have existed in supreme court nominations--it was an
oversight in the original design (IMO) that there is no such 2/3 requirement
for advice/consent. My article
http://www.nhplace.com/kent/Politics/Essays/Filibuster.html
explains this.
ANSI stays clear of these sorts of things because it knows that it's all
subjective. I think they're right to do so. They leave "judging" to
private enterprise, and try to stay to objective criteria.
Where I dislike the ANSI process isn't this. I think they do an OK job
for what they do. I just think concensus is overrated. It's not clarity,
but consensus, that is all the expense in the ANSI process.
ANSI used to be a battleground on which the wars for the hearts and minds
of users was fought. Nowadays, I think the world has just changed and this
is no longer where wars are fought, sort of like how country boundaries have
been superseded by corporate boundaries.
I'm rambling somewhat, I guess. But oh well. I've been quite busy of late
and had only a few minutes tonight to dash this off. If I'd had more time,
I would have--er, I'm repeating myself too. Ok, g'nite....
Kent M Pitman <······@nhplace.com> wrote on Thu, 01 Dec 2005:
> As the possibly apocryphal PhD student is alleged to have said, if I'd had
> more time, I'd have written something shorter.
Likely from here:
Reverend Fathers, my letters did not usually follow each other at
such close intervals, nor were they so long. [...] This one would
not be so long had I but the leisure to make it shorter.
-- Blaise Pascal, "Provincial Letters: Letter XIV" (or XVI?), 1657
which is often (mis-?)quoted more like this:
I have made this letter longer than usual because I lack the time to
make it shorter. -- Blaise Pascal
Although I guess the original was in French so perhaps there is no canonical
English translation.
-- Don
_______________________________________________________________________________
Don Geddis http://don.geddis.org/ ···@geddis.org
They say if you cut Donna open, you'll find a heart of gold.
And if not, at least you've cut her open. -- "Portrait" mini-film
On 2005-12-01 17:48:48 +0000, Don Geddis <···@geddis.org> said:
> Kent M Pitman <······@nhplace.com> wrote on Thu, 01 Dec 2005:
>> As the possibly apocryphal PhD student is alleged to have said, if I'd had
>> more time, I'd have written something shorter.
>
> Likely from here:
>
> Reverend Fathers, my letters did not usually follow each other at
> such close intervals, nor were they so long. [...] This one would
> not be so long had I but the leisure to make it shorter.
> -- Blaise Pascal, "Provincial Letters: Letter XIV" (or XVI?), 1657
>
> which is often (mis-?)quoted more like this:
>
> I have made this letter longer than usual because I lack the time to
> make it shorter. -- Blaise Pascal
>
> Although I guess the original was in French so perhaps there is no canonical
> English translation
"Je n'ai fait celle-ci plus longue que parce que je n'ai pas
eu le loisir de la faire plus courte."
http://www.dicocitations.com/resultat.php?id=2193
search for "plus courte", middle of the page.
The first quoted translation above is the closest to the original.
--
JFB ()
From: Kent M Pitman
Subject: Re: newbe: documentation string length
Date:
Message-ID: <ur79a1wp7.fsf@nhplace.com>
Harald Hanche-Olsen <······@math.ntnu.no> writes:
> But yes, in some respects we could need even more and better indexes.
> One can always use more indexes and overviews. I am sure if someone
> were to create a page listing all the format directives, for example,
> with a one-line synopsis for each and properly hyperlinked into the
> CLHS, the community would happily accept it.
CLHS does, by the way, have an index of FORMAT directives. It's perhaps
not the answer to everyone's problems, but in case people didn't think
it was there at all (and it wasn't there in the early versions 3 and 4
of the CLHS--it appeared in v5, I believe), it's in the Master Index,
Non-Alphabetic (since they all start with tilde), toward the end of the page
http://www.lispworks.com/documentation/HyperSpec/Front/X_Mast_9.htm
Kent M Pitman <······@nhplace.com> wrote:
+---------------
| CLHS does, by the way, have an index of FORMAT directives. It's perhaps
| not the answer to everyone's problems, but in case people didn't think
| it was there at all (and it wasn't there in the early versions 3 and 4
| of the CLHS--it appeared in v5, I believe), it's in the Master Index,
| Non-Alphabetic (since they all start with tilde), toward the end of the page
| http://www.lispworks.com/documentation/HyperSpec/Front/X_Mast_9.htm
+---------------
Actually, they're *also* redundantly scattered throughout that page,
in ASCII collating order according to the character after the tilde. ;-}
E.g., if you look at "/" you'll find:
/
Function /
Variable /, //, ///
/ (format directive)
Tilde Slash: Call Function
-Rob
-----
Rob Warnock <····@rpw3.org>
627 26th Avenue <URL:http://rpw3.org/>
San Mateo, CA 94403 (650)572-2607
+ ····@rpw3.org (Rob Warnock):
| Kent M Pitman <······@nhplace.com> wrote:
| +---------------
| | CLHS does, by the way, have an index of FORMAT directives. It's perhaps
| | not the answer to everyone's problems, but in case people didn't think
| | it was there at all (and it wasn't there in the early versions 3 and 4
| | of the CLHS--it appeared in v5, I believe), it's in the Master Index,
| | Non-Alphabetic (since they all start with tilde), toward the end of the page
| | http://www.lispworks.com/documentation/HyperSpec/Front/X_Mast_9.htm
| +---------------
|
| Actually, they're *also* redundantly scattered throughout that page,
| in ASCII collating order according to the character after the tilde. ;-}
Ah yes, I did look in the master index, noticed the scattered ones,
and didn't think to expect them also at the end. Duh.
--
* Harald Hanche-Olsen <URL:http://www.math.ntnu.no/~hanche/>
- Debating gives most of us much more psychological satisfaction
than thinking does: but it deprives us of whatever chance there is
of getting closer to the truth. -- C.P. Snow
On 2005-11-21 03:52:33 +0000, Kent M Pitman <······@nhplace.com> said:
> Harald Hanche-Olsen <······@math.ntnu.no> writes:
>
>> But yes, in some respects we could need even more and better indexes.
>> One can always use more indexes and overviews. I am sure if someone
>> were to create a page listing all the format directives, for example,
>> with a one-line synopsis for each and properly hyperlinked into the
>> CLHS, the community would happily accept it.
>
> CLHS does, by the way, have an index of FORMAT directives. It's perhaps
> not the answer to everyone's problems, but in case people didn't think
> it was there at all (and it wasn't there in the early versions 3 and 4
> of the CLHS--it appeared in v5, I believe), it's in the Master Index,
> Non-Alphabetic (since they all start with tilde), toward the end of the
> page
> http://www.lispworks.com/documentation/HyperSpec/Front/X_Mast_9.htm
I checked.
THAT, is an extremely creative use of an index! :-)
I blame myself for not thinking of it first.
--
JFB ()
Harald Hanche-Olsen <······@math.ntnu.no> writes:
> + verec <·····@mac.com>:
>
> | Let's face it: CL is a monster
>
> I'll leave that particular bit of flame bait alone.
>
> | 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. 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.
Not even that, I would say. The CLHS is a /specification/. That it
does such a good job as reference documentation is just a manifest to
how well written it is.
Bj�rn
verec <·····@mac.com> writes:
> On 2005-11-19 15:08:34 +0000, Pascal Bourguignon <····@mouse-potato.com> said:
>
>> verec <·····@mac.com> writes:
>>> So I'm a bit confused now. I thought that macros where only
>>> evaluated at compile time, so I expected my doc-string to do
>>> its stuff then. Apparenty, defun disagrees with me. How can
>>> I convince defun that what I want is this macro-expansion result
>>> to be slotted into its documentation string?
>> Yes, that's what happens when you're careless: you get confused.
>
> As much as I appreciate your technical expertise, I cannot
> agree with such a harsh judgment. You are not qualified to
> assess how I learn, and whether my way of learning is appropriate,
> or not, for me. I'm the sole judge of that.
I'm not doing any judgement. Just take the contraposed:
If you don't want to be confused, be careful.
Macros are not expanded at compilation time, but at macro expansion time.
> [...]
> I'm learning Lisp, one ( at a time :-)
We are all, and we all need to be careful.
>> Macros are not expanded at compilation time. They're expanded at
>> macro-expansion time!
>> Macro-expansion time may occur at compilation time, or at run time.
>
> Thanks for the clarification.
--
__Pascal Bourguignon__ http://www.informatimago.com/
-----BEGIN GEEK CODE BLOCK-----
Version: 3.12
GCS d? s++:++ a+ C+++ UL++++ P--- L+++ E+++ W++ N+++ o-- K- w---
O- M++ V PS PE++ Y++ PGP t+ 5+ X++ R !tv b+++ DI++++ D++
G e+++ h+ r-- z?
------END GEEK CODE BLOCK------
On 2005-11-19 17:41:13 +0000, Pascal Bourguignon <····@mouse-potato.com> said:
> I'm not doing any judgement. Just take the contraposed:
>
> If you don't want to be confused, be careful.
OK. I'm just going to nit-pick then ... :-)
I can be extremely careful, and yet, still be confused!
I'm carefull in that I try to make as little assumptions
as possible (except obviously for those I am unaware of).
I become confused when the wording is either self-referential
(as in the CLHS) or overly opaque.
> Macros are not expanded at compilation time, but at macro expansion time.
>
>> [...]
>> I'm learning Lisp, one ( at a time :-)
>
> We are all, and we all need to be careful.
But I feel I'm regressing: # -- \x23 -- comes before ( -- \x28 --
in the ASCII table :-)
--
JFB ()
On 2005-11-19 13:09:21 +0000, verec <·····@mac.com> said:
> I suspect that the generated code does create the concatenated
> string at run time, only to discard it, since the actual result
> is the value of the last setf form.
^^^^^^^^^^^^^^
Ooops. I meant: the last adjust-array, obviously
--
JFB ()
verec <·····@mac.com> writes:
> [...]
> ;
> 234567890123456789012345678901234567890123456789012345678901234567890123456789
> (defun
>
> resize-array (array amount) ;; improved version thanks to Fred Gilham
> (doc-string
> ("Expands array by the specified amount"
> " and returns the possibly new array."
> " Amount can be negative"))
> (adjust-array array (+ (length array) amount)))
>
> The function does compile fine, but when I try to access the
> documentation:
> [...]
> What am I missing?
You are missing the fact that DEFUN et al. expect a string literal as
documentation, not an expression to be evaluated.
You could insert a string literal from an expression with #.:
(defun f ()
#.(concatenate 'string "Abc " "def.") ; or of course you can use a macro here.
:result)
(documentation 'f)
If you use your own function in #., be sure to have it defined at read time!
But instead of formating the documentation string, I'd put in it some
markup, and process it when I want to display it:
(show-in-html-browser (doc-to-html (documentation 'f)))
(gen-latex-document (doc-to-latex (documentation 'f)))
(gen-pdf-document (doc-to-pdf (documentation 'f)))
(doc-to-text (documentation 'f))
;; ..
--
__Pascal Bourguignon__ http://www.informatimago.com/
Until real software engineering is developed, the next best practice
is to develop with a dynamic system that has extreme late binding in
all aspects. The first system to really do this in an important way
is Lisp. -- Alan Kay
On 2005-11-19 13:59:20 +0000, Pascal Bourguignon <····@mouse-potato.com> said:
> You are missing the fact that DEFUN et al. expect a string literal as
> documentation, not an expression to be evaluated.
> You could insert a string literal from an expression with #.:
>
> (defun f () #.(concatenate 'string "Abc " "def.") ; or of course
you can use a macro here.
> :result)
Excellent!
(defun resize-array (array amount) ;; improved version thanks to Fred Gilham
#.(doc-string
("Expands array by the specified amount"
" and returns the possibly new array."
" Amount can be negative"))
(adjust-array array (+ (length array) amount)))
CL-USER 80 > (documentation 'resize-array 'function)
"Expands array by the specified amount and returns the possibly new
array. Amount can be negative"
and (disassemble 'resize-array) indeed confirms that there is no
trace of concatenate at runtime.
> If you use your own function in #., be sure to have it defined at read time!
How could that be otherwise? ie, w.r.t
(defmacro doc-string (string-list)
"Concatenates all the strings into one, suitable for documentation to
display"
`(concatenate 'string ,@string-list))
> But instead of formating the documentation string, I'd put in it some
> markup, and process it when I want to display it:
>
> (show-in-html-browser (doc-to-html (documentation 'f)))
> (gen-latex-document (doc-to-latex (documentation 'f)))
> (gen-pdf-document (doc-to-pdf (documentation 'f)))
> (doc-to-text (documentation 'f))
Makes sense.
Many Thanks.
--
JFB ()
verec <·····@mac.com> writes:
> On 2005-11-19 13:59:20 +0000, Pascal Bourguignon <····@mouse-potato.com> said:
>
>> You are missing the fact that DEFUN et al. expect a string literal as
>> documentation, not an expression to be evaluated.
>> You could insert a string literal from an expression with #.:
>>
>> (defun f () #.(concatenate 'string "Abc " "def.") ; or of course
> you can use a macro here.
>> :result)
>
> Excellent!
>
> (defun resize-array (array amount) ;; improved version thanks to Fred Gilham
> #.(doc-string
> ("Expands array by the specified amount"
> " and returns the possibly new array."
> " Amount can be negative"))
> (adjust-array array (+ (length array) amount)))
>
> CL-USER 80 > (documentation 'resize-array 'function)
> "Expands array by the specified amount and returns the possibly new
> array. Amount can be negative"
>
> and (disassemble 'resize-array) indeed confirms that there is no
> trace of concatenate at runtime.
>
>> If you use your own function in #., be sure to have it defined at read time!
>
> How could that be otherwise? ie, w.r.t
>
> (defmacro doc-string (string-list)
> "Concatenates all the strings into one, suitable for documentation
> to display"
> `(concatenate 'string ,@string-list))
It's true for a macro, but note that don't need a macro: a mere
function is enough; and then you'll have to make it available:
(eval-when (:compile-toplevel :load-toplevel :execute)
(defun doc-layout (&rest strings)
...))
(defun f ()
#.(doc-layout
"blah blah blah"
"blah blah
blah blah blah"
"blah blah blah")
'some-result)
Perhaps you want something more than concatenate:
(concatenate 'string
"blah"
"blah"
"blah"
"blah") --> "blahblahblahblah"
>> But instead of formating the documentation string, I'd put in it some
>> markup, and process it when I want to display it:
>>
>> (show-in-html-browser (doc-to-html (documentation 'f)))
>> (gen-latex-document (doc-to-latex (documentation 'f)))
>> (gen-pdf-document (doc-to-pdf (documentation 'f)))
>> (doc-to-text (documentation 'f))
>
> Makes sense.
--
__Pascal Bourguignon__ http://www.informatimago.com/
Grace personified,
I leap into the window.
I meant to do that.
On 2005-11-19 15:20:22 +0000, Pascal Bourguignon <····@mouse-potato.com> said:
>>> If you use your own function in #., be sure to have it defined at read time!
>>
>> How could that be otherwise? ie, w.r.t
>>
>> (defmacro doc-string (string-list)
>> "Concatenates all the strings into one, suitable for documentation
>> to display"
>> `(concatenate 'string ,@string-list))
>
> It's true for a macro, but note that don't need a macro: a mere
> function is enough; and then you'll have to make it available:
>
> (eval-when (:compile-toplevel :load-toplevel :execute)
> (defun doc-layout (&rest strings)
> ...))
Ah. Now I understand what you meant.
>
> (defun f ()
> #.(doc-layout "blah blah blah"
> "blah blah blah blah blah"
> "blah blah blah")
> 'some-result)
Many Thanks.
--
JFB ()
Pascal Bourguignon <····@mouse-potato.com> writes:
> verec <·····@mac.com> writes:
> > [...]
> > ;
> > 234567890123456789012345678901234567890123456789012345678901234567890123456789
> > (defun
> >
> > resize-array (array amount) ;; improved version thanks to Fred Gilham
> > (doc-string
> > ("Expands array by the specified amount"
> > " and returns the possibly new array."
> > " Amount can be negative"))
> > (adjust-array array (+ (length array) amount)))
> >
> > The function does compile fine, but when I try to access the
> > documentation:
> > [...]
> > What am I missing?
>
> You are missing the fact that DEFUN et al. expect a string literal as
> documentation, not an expression to be evaluated.
> You could insert a string literal from an expression with #.:
>
> (defun f ()
> #.(concatenate 'string "Abc " "def.") ; or of course you can use a macro here.
> :result)
>
> (documentation 'f)
>
> If you use your own function in #., be sure to have it defined at read time!
>
> But instead of formating the documentation string, I'd put in it some
> markup, and process it when I want to display it:
>
> (show-in-html-browser (doc-to-html (documentation 'f)))
> (gen-latex-document (doc-to-latex (documentation 'f)))
> (gen-pdf-document (doc-to-pdf (documentation 'f)))
> (doc-to-text (documentation 'f))
> ;; ..
>
I think Pascal is probably on the right track - that is, define
functions to take the output from the documentation function and
format it, rather than trying to format the documentation string in
specific functions. Using the wrapper approach around calls to
documentation will have the advantage that all documentation will now
be formatted according to your formating requirements, not just
functions you define yourself - in fact, you could take it a step
further and just have a format-doc function which takes a formatting
function as an additional (optional) argument.
Tim
--
Tim Cross
The e-mail address on this message is FALSE (obviously!). My real e-mail is
to a company in Australia called rapttech and my login is tcross - if you
really need to send mail, you should be able to work it out!