Silly newbie question - Carrot character (^)

[Steven D'Aprano]

On Sat, 06 Nov 2010 23:19:18 +0000, Nobody wrote:

> On Fri, 05 Nov 2010 22:51:10 +0000, Seebs wrote:
> 
>>> IMHO, the lack of a reference manual for the language itself is a
>>> major hole in Python's documentation.
>> 
>> I'm a bit lost here.  Could you highlight some of the differences
>> between "a reference manual for the language itself" and "something
>> written for language lawyers"?
> 
> A reference manual tells you how to use the language. A specification
> tells you how to implement it.

Surely a tutorial tells you *how* to use the language. I wouldn't expect 
a reference manual to teach me how to run and edit programs -- the *how* 
of using the language.

And a specification ("for language lawyers") tells you *what* to 
implement, not how. E.g. a specification should tell you that the 
language needs a sorted() function, what arguments it takes, and what it 
should do. It should not tell you how to implement it (Quicksort or 
Timsort? Sort pointers to items or an array of items? External sort or in-
memory sort?).

Any instructions on how to implement the language will depend on what 
language you're implementing it in. An implementers guide written for C 
programmers will be very different from one written for Lisp or Forth or 
Haskell programmers.


> It's possible to /deduce/ how to use the language from a specification,
> but it could take significant time and effort.

I think you're looking for hard distinctions that simply doesn't exist. 
By it's very nature, documentation of all types falls into a continuum of 
overlapping fuzzy sets. But to the extent that the terms have any 
specific meaning, a reference manual and something for the language 
lawyers (a specification) are the same thing. Different specific 
reference manuals may be aimed at different levels of sophistication, 
more or less successfully, but arguments about categories are pointless 
since we're rarely going to agree on the definition of the categories.

If you want to argue that the Python reference manual is aimed at the 
wrong level of sophistication, specifically that the BNF syntax stuff 
should be ripped out into another document, then I might agree with you. 
But to argue that it's entirely the wrong "kind" of thing is, in my 
opinion, unjustified.


-- 
Steven