> The *Language Reference* is designed to be much more formally defined, and > favors correctness and completeness over being easy to access by less > technical readers. >
Not really my opinion. Language Reference (LR) style is still written in a conversational style, giving examples instead of definition. Typically consider this paragraph from the LR: ------------ begin excerpt ------- The value of some objects can change. Objects whose value can change are said to be mutable; objects whose value is unchangeable once they are created are called immutable. (The value of an immutable container object that contains a reference to a mutable object can change when the latter’s value is changed; however the container is still considered immutable, because the collection of objects it contains cannot be changed. So, immutability is not strictly the same as having an unchangeable value, it is more subtle.) An object’s mutability is determined by its type; for instance, numbers, strings and tuples are immutable, while dictionaries and lists are mutable. ------------ end excerpt ------- The explanations inside the parenthensis is a by-the-way explanation, a mark of conversional style not to say tutorial style. Before parenthensis, we are talking about value of **any kind** of object and changeability in general. Now, the parenthensis is refering to immutable container as an illustration. The same for last sentence : "for instance ..." The problem is that the documentation doesn't define what the value of an object is, what means changing the value. The documentation doesn't explain **how** mutability is determined by the type of the object. By the way, how the docs define a container? Answer: "Some objects contain references to other objects; these are called containers". So to summarize : "a container contains", what a great definition! You said that LR is designed to be much more formally defined, and favors correctness and completeness. Good, so can you answer this question after reading the LR : what is a "token"? Did't find a definition. Is the "is not" operator a token? > There's an argument to be made that the description of the expected > __str__() behavior of ints is not easy to find within section 3 of the > language reference, and I imagine that a reasonable proposed change to this > wording would be considered favourably. (python is accepting pull requests > when they pass review :). > A drop in the ocean, sorry but Python docs are irrecoverable. -- https://mail.python.org/mailman/listinfo/python-list
