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