On Tue, Mar 4, 2008 at 8:03 PM, Stephen J. Turnbull stephen@xemacs.org wrote:
Adam Olsen writes:
On Tue, Mar 4, 2008 at 3:13 PM, Stephen J. Turnbull stephen@xemacs.org wrote:
I would like to see the clear division between the language (ie, the syntax) and the built-in functionality maintained. I'm not sure I like the proposed title for that reason.
Such a division would make it unnecessarily hard to find documentation on True, False, None, etc. They've become keywords for pragmatic purposes (to prevent accidental modification), not because we think they ideally should be syntax instead of builtins.
This is Python; of course practicality beats purity. I have no problem with putting some keywords in the "built-in functionality" section, or even (boggle) duplicate them across the two sections.
-1 on duplicating anything. Provide links to a single location instead. Otherwise you end up with two explanations of the same thing, with different wording and subtle differences or missing details.
I too was put off by the separation of syntax from built-in functionality when I first started using the documentation, but later I came to appreciate it. I'm a relatively casual user of Python, and having a spare "syntax" section has made it much easier to learn new syntax such as comprehensions and generators. I suspect it will make it a lot easier to learn the differences between Python 2 and Python 3, too. I do not want to lose that.
I learned them through third-party docs. Even now I have a hard time finding list comprehension/generator expression in the docs. Apparently they're in the Expression section, under "Displays for lists, sets and dictionaries", and neither that nor anything with list comprehension or generator expression is in the index. The term "Displays" is pretty obscure as well, not something I've seen used besides on this list or right there in the documentation.
I don't pretend to be speaking for anyone else, but I'd be surprised if I were unique.<wink>
Your experiences *shouldn't* be unique, but I'm afraid they might be. Another example is the use of BNF, which although dominant in its field, it provides a steep learning curve for most programmers.
I'm afraid this has turned into a rant, but it should be seen as the experiences of someone who relies on the documentation a great deal. Is there a better way to channel feedback on the documentation?