On 2010-11-07, Steven D'Aprano <st...@remove-this-cybersource.com.au> wrote:
> 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.
There's a sort of fuzzy boundary about how the term "reference manual" is
used. Some people view it more in terms of presenting, for each major
feature or class of functionality, an overview of what you need to know to
use it, which may not be everything you need to know to implement it
correctly.
Consider:
In Python, indentation determines control flow. Statements which
take a block of code must be followed by at least one line of a
greater indentation level; all following lines of that
indentation level are part of the block, ending at the first line
which is less indented than the block. Each block should be
indented by four spaces from the preceeding block, and tabs should
not be used.
That might be quite suitable* for a "reference manual" as many people use
the term, but would be useless for a language lawyer. A language lawyer
needs to know that " \t" at the beginning of a line is construed to
be the same indentation level as " " or "\t". A typical reference
manual might simply ignore that information because it's telling you what
you need to write good code, not what you need to know to write a compatible
implementation.
That said... I am certainly biased on the issue, but IMHO a reference manual
should not "gloss over" things like that, but should be at least as detailed
as a formal specification; where it might differ is in *additional* material
with explanations and clarifications. YMMV.
-s
[*] Well, imagine that, only written better and properly edited, and so on.
--
Copyright 2010, all wrongs reversed. Peter Seebach / usenet-nos...@seebs.net
http://www.seebs.net/log/ <-- lawsuits, religion, and funny pictures
http://en.wikipedia.org/wiki/Fair_Game_(Scientology) <-- get educated!
I am not speaking for my employer, although they do rent some of my opinions.
--
http://mail.python.org/mailman/listinfo/python-list
