Silly newbie question - Carrot character (^)

[Nobody]

On Sun, 07 Nov 2010 00:06:25 +0000, Steven D'Aprano wrote:

>> 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.

You're taking "how" too literally, so let me rephrase that:

  A reference manual tells you what you need to know in order to use the
  language. A specification tells you what you need to know in order to
  implement it.

>> 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. 

There isn't a /hard/ distinction, but there is a distinction, IMHO.

A tutorial provides an overview of the language, but won't necessarily
describe every aspect (maybe not even close), and is generally designed to
be read in order.

In order to provide working examples, it may be necessary to introduce
some features in the "wrong" order (e.g. in a language which doesn't
provide an interactive read-eval-print loop, I/O may be introduced early
on simply so that complete programs can be constructed). And once the
feature is covered, it probably won't be repeated when the tutorial gets
to a more appropriate section (e.g. the I/O section may omit features
covered in the introduction).

A reference manual would describe whatever you need to know in order to
"use" the language. It shouldn't omit anything short of the "you are not
expected to understand this" level. IOW, any omissions shouldn't matter
unless you are e.g. writing analysis utilities which need to accept /any/
valid program and interpret it correctly.

E.g. a reference manual would need to describe indentation, but details
such as the interpretation of a mixture of tabs and spaces can be limited
to "don't do this", whereas a specification would need to either specify
the details or at least specify that it invokes "undefined behaviour".

> 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.

I'm arguing that the reference manual reads too much like a specification.
E.g. look at "5.2.4. List displays" and tell me whether you consider that
it adequately /explains/ list displays to someone wishing to use them.

I note that the "reference manual" contains very few examples. For a
specification, this would be quite normal, as examples can serve to
undermine precision. For a reference manual, precision has to be traded
for clarity, which may mean using examples where appropriate.

OTOH, a tutorial often contains little more than a sequence of examples
along with informal explanations as to their structure and functioning. As
a result, tutorials tend to lack precision; they provide specific cases
which will work and some "clues" as to what else is likely to work.

Regarding BNF: reference manuals tend to use less formal descriptions.
E.g. something akin to to --help syntax, or a "dumbed-down" BNF which may
technically be ambiguous, with ambiguities resolved by specifying
precedences separately or listing would-be ambiguous cases along with a
description of their correct interpretation.