Re: Silly newbie question - Carrot character (^)
In message mailman.697.1289067607.2218.python-l...@python.org, Dennis Lee Bieber wrote: On Sat, 6 Nov 2010 10:22:47 -0400, Philip Semanchuk phi...@semanchuk.com declaimed the following in gmane.comp.python.general: Some people might think the language ref is a fine place to direct newcomers to Python. I don't. It's not awful, but it's dense and unfriendly for those just starting out. Have you ever looked at the reference manual for Ada? Or even worse, the annotated reference. I thought annotations were supposed to clarify things; in this case they seemed to have the opposite effect... -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On 2010-11-09, Lawrence D'Oliveiro l...@geek-central.gen.new_zealand wrote: In message mailman.697.1289067607.2218.python-l...@python.org, Dennis Lee Bieber wrote: Have you ever looked at the reference manual for Ada? Or even worse, the annotated reference. I thought annotations were supposed to clarify things; in this case they seemed to have the opposite effect... Clearly, you've never seen Schildt's infamous Annotated ANSI C Standard. -s -- 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
Re: Silly newbie question - Carrot character (^)
On 2010-11-07, Nobody nob...@nowhere.com wrote: 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. Seems pretty explanatory to me. I mean, maybe it helps that I already basically understood both of the things you could put in [], but it's pretty clear. -s -- 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
Re: Silly newbie question - Carrot character (^)
In article slrnidc7r1.138j.usenet-nos...@guild.seebs.net, Seebs usenet-nos...@seebs.net wrote: On 2010-11-07, Roy Smith r...@panix.com wrote: Any self-respecting C++ programmer would have given up the scavenger hunt by now. Just kept throwing typecasts at your code until it compiles, and move on. That does not sound like a self-respecting programmer of anything. Well, maybe I was being a little sarcastic. The real point was that if you make it hard for people to do the right thing (i.e. look up the details in the reference manual), you should not be surprised if they do the wrong thing (i.e. find some way to make it work by trial and error). -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
Nobody nob...@nowhere.com writes: 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. I still don't see those as being different. A language reference should set out all of the details of the language syntax and semantics. It should answer every question of the form `what happens if I write this?' In so doing, it /must/ also provide enough information for an implementer to write an new implementation. 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. Agreed. 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. `Using' a language involves two activities: writing it, and reading it. You're only considering one of those activities, and I think it's the less important one. 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. I'm confronted with some code, written by someone else, and when I run it I get an unexpected result. The language reference should be able to explain to me precisely why I get the result that I see. If it can't, it's of no value. 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. It doesn't adequately specify them either. That section is just poorly written. 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. I disagree with both claims. Examples cannot undermine precision: if the normative text is correct then an example can only demonstrate an application of the specified rules. If the normative text is wrong then the specification is broken and needs fixing. But the same applies to a reference. Either it supplies enough detail to answer every question about how programs behave or it's broken: precision is essential here, but is not -- and cannot -- be compromised by adding examples. 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. Yes, I'm familiar with the `leave the reader to fill in the gaps in my exposition for himself' approach to documentation -- and with the unenjoyable task of fixing the reader's confused mental model afterwards. -- [mdw] -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On 2010-11-07, Roy Smith r...@panix.com wrote: Well, maybe I was being a little sarcastic. The real point was that if you make it hard for people to do the right thing (i.e. look up the details in the reference manual), you should not be surprised if they do the wrong thing (i.e. find some way to make it work by trial and error). Fair enough. That said, I don't think it's the *writing* of the C spec that would make it hard for people to look up details. Dunno for C++. -s -- 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
Re: Silly newbie question - Carrot character (^)
On Nov 6, 2010, at 10:45 AM, D'Arcy J.M. Cain wrote: On Sat, 6 Nov 2010 10:22:47 -0400 Philip Semanchuk phi...@semanchuk.com wrote: The tutorial isn't meant as an exhaustive lesson on every single Python feature. I agree, and I don't expect otherwise. My point was that if the tutorial doesn't mention a feature, the only other place to learn about it (on python.org) is the language ref. Some people might think the language ref is a fine place to direct newcomers to Python. I don't. I don't think that anyone was suggesting the reference as the first place to send newcomers. Hi D'Arcy, I agree, no one -- not even I -- suggested that. The tutorial is always the first stop. You send them there when they need something beyond the basics. But IMO this is still a problem. After the tutorial, then what? Someone who has read the tutorial can still be new to Python by my definition. You may feel that the current language ref is OK for newcomers. I don't, and that's my point. I think the only issue here is that operators are pretty basic and that specific thing is missing in the tutorial. It would be a mistake to write a whole new document because the tutorial is missing one thing. Better would be to propose an operators section. The issue is not just operators. As I mentioned, the tutorial doesn't cover decorators, assert, exec, ternary if, and maybe a few other things. IMO that's fine. A tutorial should introduce the basics. I'm sure we could have a fine argument about what features of Python are basic and which are advanced, but I'd rather not as long as we can agree with Steven D'Aprano's comment that The tutorial isn't meant as an exhaustive lesson on every single Python feature. I certainly agree with that. Personally, I liked using the tutorial for learning Python. It's readable. But after getting familiar with the language I wanted to move on to something more structured. I also realized that the tutorial didn't cover every aspect of the language because I saw references in code and discussions to things that weren't mentioned in the tutorial. I didn't feel like the python.org documentation provided an obvious next step, though, because I started with Python 2.3, and the language reference was still entitled for language lawyers back then. The section's name may have changed since then, but it looks like the style hasn't changed much. I believe the lack of a complete, friendly post-tutorial document to read made learning Python more difficult for me. I realize that the Python Foundation doesn't have infinite resources to work with, so maybe they'd love to create maintain a more readable language reference if they had time/money/people. I don't hear anyone talk about it, though. Lots of people talk. Action, not so much. How about you? Are you ready to start writing a new reference manual? First you suggest that writing a whole new document would be a mistake, then you encourage me to do it. =) The old open source challenge of If you don't like it, fix it is liberating but it's also a nifty way of changing the subject. Whether or not I can or will fix a problem doesn't make my criticism any more or less legitimate which (I thought) was the issue at hand. To answer your question: no, I'm not willing to start writing a new reference manual. For one thing, I don't think it's wanted judging by the response I've seen here. I see a lot of people saying what we have is fine. To put it another way, based on this small sample size survey, opinions are mixed on the current state of the documentation. The effort required to make substantial changes (e.g. create a reference manual that's sort of a marriage of the tutorial and the language spec) is large but would likely result in very little net improvement as perceived by the community as a whole. To put it a fifth way (Sir Galahad: third, sir) -- people learn differently. Cheers Philip -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On 11/05/10 23:33, Steven D'Aprano wrote: As far as the OP's question, I'm kind of surprised that he wasn't told that Google is his friend. The very first hit for python caret answers his question. If he had spent even five seconds googling, he would have got his answer. http://www.google.co.uk/search?hl=ensafe=offq=python+caretbtnG=Search The OP didn't seem to know the name for the character which makes it difficult. As they wrote in the initial message, Sadly my google foo is failing since the character gets filtered out. I'm guessing the OP tried to search for python ^, and the ^ just got filtered out, which makes for a rather unhelpful search for just python. And since the OP had already tried to google it, they weren't told to attempt it again. ;-) Yes, with a little tweaking to the query, something like python ^ operator would get them to pages matching python operator in which they could have searched for ^, but at least they made the attempt (the lack of an *attempt* is what usually brings out the GTFW responses). -tkc -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
Seebs usenet-nos...@seebs.net writes: I'm a bit lost here. Could you highlight some of the differences between a reference manual for the language itself and something written for language lawyers? I don't speak for Nobody, but to me a reference manual would be a document intended for the user of the language. The thing for the language lawyer is something intended for the implementor, or possibly for the very advanced user who argues with the implementor about intricacies of behavior. The latter document is also known as the specification or the standard. These two types of document serve different needs and are written for different audience. In Python the choice was made for the library to be written in a reference-manual way, and for the language reference to be written in a specification way. This choice is reasonable, but it can lead to problems when you want to refer a regular user to documentation about the language for educational purposes. -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On Nov 6, 2010, at 12:33 AM, Steven D'Aprano wrote: On Fri, 05 Nov 2010 23:21:11 -0400, Philip Semanchuk wrote: Take the OP's question. How is one supposed to find out about bitwise operators in Python? AFAICT they're not mentioned in the tutorial, and neither are decorators, assert(), global, exec, the ternary if statement, etc. The tutorial isn't meant as an exhaustive lesson on every single Python feature. I agree, and I don't expect otherwise. My point was that if the tutorial doesn't mention a feature, the only other place to learn about it (on python.org) is the language ref. Some people might think the language ref is a fine place to direct newcomers to Python. I don't. It's not awful, but it's dense and unfriendly for those just starting out. There are plenty of other resources available: learning Python *starts* with the python.org tutorial (or some equivalent), it doesn't end there. Yes, I agree. That's what I said in my email too. One goes through the tutorial a few times and then...? There's not a formal document to turn to after that. There are plenty of resources -- books, mailing lists, etc. But they're 3rd party, unstructured, not maintained, etc. I realize that the Python Foundation doesn't have infinite resources to work with, so maybe they'd love to create maintain a more readable language reference if they had time/money/people. I don't hear anyone talk about it, though. bye Philip -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On Sat, 6 Nov 2010 10:22:47 -0400 Philip Semanchuk phi...@semanchuk.com wrote: The tutorial isn't meant as an exhaustive lesson on every single Python feature. I agree, and I don't expect otherwise. My point was that if the tutorial doesn't mention a feature, the only other place to learn about it (on python.org) is the language ref. Some people might think the language ref is a fine place to direct newcomers to Python. I don't. I don't think that anyone was suggesting the reference as the first place to send newcomers. You send them there when they need something beyond the basics. I think the only issue here is that operators are pretty basic and that specific thing is missing in the tutorial. It would be a mistake to write a whole new document because the tutorial is missing one thing. Better would be to propose an operators section. I realize that the Python Foundation doesn't have infinite resources to work with, so maybe they'd love to create maintain a more readable language reference if they had time/money/people. I don't hear anyone talk about it, though. Lots of people talk. Action, not so much. How about you? Are you ready to start writing a new reference manual? How about just that one section on operators that's missing from the tutorial. Remember, Python is we, not they. -- D'Arcy J.M. Cain da...@druid.net | Democracy is three wolves http://www.druid.net/darcy/| and a sheep voting on +1 416 425 1212 (DoD#0082)(eNTP) | what's for dinner. -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On 2010-11-06, Hrvoje Niksic hnik...@xemacs.org wrote: I don't speak for Nobody, but to me a reference manual would be a document intended for the user of the language. The thing for the language lawyer is something intended for the implementor, or possibly for the very advanced user who argues with the implementor about intricacies of behavior. The latter document is also known as the specification or the standard. I guess I would think that if such a document cannot be used as a reference, it's not very well done. -s -- 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
Re: Silly newbie question - Carrot character (^)
In article 11a0f261-1bf4-4c35-83fa-c47bf968d...@semanchuk.com, Philip Semanchuk phi...@semanchuk.com wrote: On Nov 6, 2010, at 12:33 AM, Steven D'Aprano wrote: On Fri, 05 Nov 2010 23:21:11 -0400, Philip Semanchuk wrote: Take the OP's question. How is one supposed to find out about bitwise operators in Python? AFAICT they're not mentioned in the tutorial, and neither are decorators, assert(), global, exec, the ternary if statement, etc. The tutorial isn't meant as an exhaustive lesson on every single Python feature. I agree, and I don't expect otherwise. My point was that if the tutorial doesn't mention a feature, the only other place to learn about it (on python.org) is the language ref. Some people might think the language ref is a fine place to direct newcomers to Python. I don't. It's not awful, but it's dense and unfriendly for those just starting out. In the Python documentation set, the language reference should usually be the second place to send someone. The first place is The Python Standard Library manual where built-in types and the methods supported by them are documented. For bit string operations: http://docs.python.org/library/stdtypes.html#bit-string-operations-on-int eger-types -- Ned Deily, n...@acm.org -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On Nov 5, 5:51 pm, Seebs usenet-nos...@seebs.net wrote: On 2010-11-05, Nobody nob...@nowhere.com wrote: However, it's still written for language lawyers. IMHO, the lack of a reference manual for the language itself is a major hole in Python's documentation. I'm a bit lost here. Could you highlight some of the differences between a reference manual for the language itself and something written for language lawyers? In a word HUMOR! Obviously the commentator who has a lack of the hidden meaning of language lawyers has no sense of humor -- sadly another lost virtue of the French! -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On 11/6/2010 10:45 AM, D'Arcy J.M. Cain wrote: I realize that the Python Foundation doesn't have infinite resources to work with, so maybe they'd love to create maintain a more readable language reference if they had time/money/people. I don't hear anyone talk about it, though. While that isn't a current priority it certainly seems like a worthy goal to me. But the Python Software Foundation is people, and we certainly don't have the resources to simply enter into a contract with an organization to produce a more readable language reference - whether those resources are time, money or people (which can tend to become indistinguishable when planning is underway). We would love for Python's documentation to be even better, but the last major change in the documentation (the dropping of LATEX as the source language and the switch to Sphinx) was largely a result of one person (Georg Brandl) scratching an itch. Maybe a more readable language reference will come about the same way ... Lots of people talk. Action, not so much. How about you? Are you ready to start writing a new reference manual? How about just that one section on operators that's missing from the tutorial. That ought to be quite a manageable project. Remember, Python is we, not they. Quite. having-no-wish-to-be-they-ly - steve -- Steve Holden +1 571 484 6266 +1 800 494 3119 PyCon 2011 Atlanta March 9-17 http://us.pycon.org/ See Python Video! http://python.mirocommunity.org/ Holden Web LLC http://www.holdenweb.com/ -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On 2010-11-06, rantingrick rantingr...@gmail.com wrote: On Nov 5, 5:51?pm, Seebs usenet-nos...@seebs.net wrote: I'm a bit lost here. ?Could you highlight some of the differences between a reference manual for the language itself and something written for language lawyers? In a word HUMOR! Huh? Obviously the commentator who has a lack of the hidden meaning of language lawyers has no sense of humor -- sadly another lost virtue of the French! It is a shame that there was a guy standing behind you with a gun preventing you from explaining what the alleged hidden meaning was, so all you could do is allude to it without explaining it. Maybe later you can get away from your captors and post an explanation of what the hidden meaning is, in your eyes? -s -- 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
Re: Silly newbie question - Carrot character (^)
On Fri, 05 Nov 2010 22:51:10 +, Seebs wrote: IMHO, the lack of a reference manual for the language itself is a major hole in Python's documentation. I'm a bit lost here. Could you highlight some of the differences between a reference manual for the language itself and something written for language lawyers? A reference manual tells you how to use the language. A specification tells you how to implement it. It's possible to /deduce/ how to use the language from a specification, but it could take significant time and effort. A specification is typically designed to be read in its entirety, and may yield little usable information until you've read a substantial portion of it. A reference manual is structured such that you can easily locate the portion which is necessary for the task immediately to hand, and only need to read that portion. OTOH, a tutorial typically isn't exhaustive. And even if it is, the information related to a topic may be scattered throughout multiple sections, making it hard to find a specific piece of information. E.g. the syntax of expressions adheres rather rigidly to the grammar used for parsing, which is fine for a specification, but not how a reference manual would normally be written. -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On Sat, 06 Nov 2010 23:19:18 +, Nobody wrote: On Fri, 05 Nov 2010 22:51:10 +, Seebs wrote: IMHO, the lack of a reference manual for the language itself is a major hole in Python's documentation. I'm a bit lost here. Could you highlight some of the differences between a reference manual for the language itself and something written for language lawyers? 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. And a specification (for language lawyers) tells you *what* to implement, not how. E.g. a specification should tell you that the language needs a sorted() function, what arguments it takes, and what it should do. It should not tell you how to implement it (Quicksort or Timsort? Sort pointers to items or an array of items? External sort or in- memory sort?). Any instructions on how to implement the language will depend on what language you're implementing it in. An implementers guide written for C programmers will be very different from one written for Lisp or Forth or Haskell programmers. 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. By it's very nature, documentation of all types falls into a continuum of overlapping fuzzy sets. But to the extent that the terms have any specific meaning, a reference manual and something for the language lawyers (a specification) are the same thing. Different specific reference manuals may be aimed at different levels of sophistication, more or less successfully, but arguments about categories are pointless since we're rarely going to agree on the definition of the categories. 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. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
Steven D'Aprano st...@remove-this-cybersource.com.au writes: 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 certainly wouldn't agree with that. The language's syntax is essential part of the language, and must be described clearly and unambiguously. Formal grammars aren't especially hard to understand, and they're pretty much everywhere, so learning how to read them is an essential skill anyway. To be honest, I reckon the Python language reference is too friendly and fluffy. The manual for F#, say, is a harder read. The Standard ML language reference is a book full of mathematical notation (inference rules for operational semantics, mainly) and little else. The Scheme language used to be described by a page or so of equations giving a translation into lambda calculus (but now that's operational semantics too) -- oh, there are prose descriptions too, but they're not easy going either in places, and the formal semantics are necessary to clear up some of the details. You Python people have it easy. -- [mdw] -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
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
Re: Silly newbie question - Carrot character (^)
Seebs usenet-nos...@seebs.net writes: On 2010-11-06, Hrvoje Niksic hnik...@xemacs.org wrote: I don't speak for Nobody, but to me a reference manual would be a document intended for the user of the language. The thing for the language lawyer is something intended for the implementor, or possibly for the very advanced user who argues with the implementor about intricacies of behavior. The latter document is also known as the specification or the standard. I guess I would think that if such a document cannot be used as a reference, it's not very well done. It's not a matter of quality, but of intended audience. To most ordinary programmers the standards documents such as the C standard, the C++ standard, or the Python reference are quite dense and hard to use as a reference, and yet they are considered quite well done. -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On 2010-11-07, Hrvoje Niksic hnik...@xemacs.org wrote: It's not a matter of quality, but of intended audience. To most ordinary programmers the standards documents such as the C standard, the C++ standard, or the Python reference are quite dense and hard to use as a reference, and yet they are considered quite well done. Huh. I quite liked the C spec as a reference. Yeah, it's a bit dense, but that just means it's all actually *reference*. :) -s -- 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
Re: Silly newbie question - Carrot character (^)
In article 87fwve53ve@xemacs.org, Hrvoje Niksic hnik...@xemacs.org wrote: It's not a matter of quality, but of intended audience. To most ordinary programmers the standards documents such as the C standard, the C++ standard, or the Python reference are quite dense and hard to use as a reference, and yet they are considered quite well done. Not only is the C++ reference obtuse and dense, it's also not commonly available. It is copyright by ISO and only available for a fee. I own a copy, but I'd venture to say that the vast majority of C++ programmers out there have never seen one. Heck, if was a programmer and wanted to spend money today to buy a copy, I wouldn't even know where to go to order one. I googled for iso c++ standard and found http://www.open-std.org/jtc1/sc22/wg21/, which includes a well-hidden link to http://www.open-std.org/jtc1/sc22/wg21/docs/standards, which says, Published ISO and IEC standards can be purchased from a member body of ISO or IEC. How one would go about figuring out who such member body is, I have no idea. Any self-respecting C++ programmer would have given up the scavenger hunt by now. Just kept throwing typecasts at your code until it compiles, and move on. Python may not have a reference manual which is up to the quality of the C++ manual, but what's there is freely available on docs.python.org. As for the subject of this thread, you might want to check out http://archive.midrange.com/midrange-l/200703/msg00036.html. -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On 2010-11-07, Roy Smith r...@panix.com wrote: Any self-respecting C++ programmer would have given up the scavenger hunt by now. Just kept throwing typecasts at your code until it compiles, and move on. That does not sound like a self-respecting programmer of anything. -s -- 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
Re: Silly newbie question - Carrot character (^)
On Sun, 07 Nov 2010 00:06:25 +, 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. -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On Fri, Nov 5, 2010 at 2:43 PM, Matty Sarro msa...@gmail.com wrote: Hey Everyone, Just curious - I'm working on a program which includes a calculation of a circle, and I found myself trying to use pi*radius^2, and getting errors that data types float and int are unsupported for ^. Now, I realized I was making the mistake of using '^' instead of **. I've corrected this and its now working. However, what exactly does ^ do? I know its used in regular expressions but I can't seem to find anything about using it as an operator. Sadly my google foo is failing since the character gets filtered out. It's a binary operator i think... something like xor. -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
2010/11/5 Matty Sarro msa...@gmail.com: Hey Everyone, Just curious - I'm working on a program which includes a calculation of a circle, and I found myself trying to use pi*radius^2, and getting errors that data types float and int are unsupported for ^. Now, I realized I was making the mistake of using '^' instead of **. I've corrected this and its now working. However, what exactly does ^ do? I know its used in regular expressions but I can't seem to find anything about using it as an operator. Sadly my google foo is failing since the character gets filtered out. -- http://mail.python.org/mailman/listinfo/python-list Hi, see http://docs.python.org/reference/expressions.html#binary-bitwise-operations for bitwise XOR. The usage in regular expressions is different, of course; hth, vbr -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
However, what exactly does ^ do? Bitwise XOR: http://docs.python.org/py3k/reference/expressions.html#binary-bitwise-operations -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On Fri, 5 Nov 2010 09:43:25 -0400
Matty Sarro msa...@gmail.com wrote:
now working. However, what exactly does ^ do? I know its used in regular
expressions but I can't seem to find anything about using it as an operator.
It's the XOR operator. Try help('^') for more detail.
By the way, it's caret, not carrot.
--
D'Arcy J.M. Cain da...@druid.net | Democracy is three wolves
http://www.druid.net/darcy/| and a sheep voting on
+1 416 425 1212 (DoD#0082)(eNTP) | what's for dinner.
--
http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On Fri, Nov 5, 2010 at 7:26 PM, Krister Svanlund krister.svanl...@gmail.com wrote: On Fri, Nov 5, 2010 at 2:43 PM, Matty Sarro msa...@gmail.com wrote: Hey Everyone, Just curious - I'm working on a program which includes a calculation of a circle, and I found myself trying to use pi*radius^2, and getting errors that data types float and int are unsupported for ^. Now, I realized I was making the mistake of using '^' instead of **. I've corrected this and its now working. However, what exactly does ^ do? I know its used in regular expressions but I can't seem to find anything about using it as an operator. Sadly my google foo is failing since the character gets filtered out. It's a binary operator i think... something like xor. Yes. Infact '^' is binary XOR. a = 4 bin(a) '0b100' b = 5 bin(b) '0b101' a ^ b 1 100 ^ 101 = 001 -- http://mail.python.org/mailman/listinfo/python-list -- ~l0nwlf -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
Thanks everyone, that explains it :) -Matty On Fri, Nov 5, 2010 at 9:43 AM, Matty Sarro msa...@gmail.com wrote: Hey Everyone, Just curious - I'm working on a program which includes a calculation of a circle, and I found myself trying to use pi*radius^2, and getting errors that data types float and int are unsupported for ^. Now, I realized I was making the mistake of using '^' instead of **. I've corrected this and its now working. However, what exactly does ^ do? I know its used in regular expressions but I can't seem to find anything about using it as an operator. Sadly my google foo is failing since the character gets filtered out. -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On Nov 5, 2010, at 9:43 AM, Matty Sarro wrote: Hey Everyone, Just curious - I'm working on a program which includes a calculation of a circle, and I found myself trying to use pi*radius^2, and getting errors that data types float and int are unsupported for ^. Now, I realized I was making the mistake of using '^' instead of **. I've corrected this and its now working. However, what exactly does ^ do? I know its used in regular expressions but I can't seem to find anything about using it as an operator. Sadly my google foo is failing since the character gets filtered out. As others have said, ^ is for XOR. That's buried here in the documentation: http://docs.python.org/release/2.7/reference/expressions.html#binary-bitwise-operations Not that I would have expected you to find it there since that's pretty dense. In fact, older versions of the Python doc used to describe this section as for language lawyers but I see they've changed that now. BTW the more common name for this character is caret (ka-RAY). Cheers Philip -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On Fri, 5 Nov 2010 10:12:05 -0400, Philip Semanchuk wrote: BTW the more common name for this character is caret (ka-RAY). Yes, it's caret, but no, it's KA-rit, almost the same as carrot. It's straight from Latin, with no detour through French. -- To email me, substitute nowhere-spamcop, invalid-net. -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On Nov 5, 2010, at 12:43 PM, Peter Pearson wrote: On Fri, 5 Nov 2010 10:12:05 -0400, Philip Semanchuk wrote: BTW the more common name for this character is caret (ka-RAY). Yes, it's caret, but no, it's KA-rit, almost the same as carrot. It's straight from Latin, with no detour through French. This I did not know (obviously). Thanks. I knew all those years of studying French would ruin me somehow. -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
It's ok, people who refer to a labret piercing as a la-BRAY piercing are also incorrect. It's pronounced lab-RET, as its base word is the latin labretta. French as a language shall doom us all :) On Fri, Nov 5, 2010 at 2:54 PM, Philip Semanchuk phi...@semanchuk.comwrote: On Nov 5, 2010, at 12:43 PM, Peter Pearson wrote: On Fri, 5 Nov 2010 10:12:05 -0400, Philip Semanchuk wrote: BTW the more common name for this character is caret (ka-RAY). Yes, it's caret, but no, it's KA-rit, almost the same as carrot. It's straight from Latin, with no detour through French. This I did not know (obviously). Thanks. I knew all those years of studying French would ruin me somehow. -- http://mail.python.org/mailman/listinfo/python-list -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On 11/5/2010 9:43 AM, Matty Sarro wrote: Hey Everyone, Just curious - I'm working on a program which includes a calculation of a circle, and I found myself trying to use pi*radius^2, and getting errors that data types float and int are unsupported for ^. Now, I realized I was making the mistake of using '^' instead of **. I've corrected this and its now working. However, what exactly does ^ do? I know its used in regular expressions but I can't seem to find anything about using it as an operator. Sadly my google foo is failing since the character gets filtered out. All such symbol questions are aswered (or should be) in PySymbols.html: https://code.google.com/p/xploro/downloads/detail?name=PySymbols.html -- Terry Jan Reedy -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On Fri, 05 Nov 2010 10:12:05 -0400, Philip Semanchuk wrote: As others have said, ^ is for XOR. That's buried here in the documentation: http://docs.python.org/release/2.7/reference/... Not that I would have expected you to find it there since that's pretty dense. In fact, older versions of the Python doc used to describe this section as for language lawyers but I see they've changed that now. However, it's still written for language lawyers. IMHO, the lack of a reference manual for the language itself is a major hole in Python's documentation. -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On Nov 5, 2010, at 5:21 PM, Nobody wrote: On Fri, 05 Nov 2010 10:12:05 -0400, Philip Semanchuk wrote: As others have said, ^ is for XOR. That's buried here in the documentation: http://docs.python.org/release/2.7/reference/... Not that I would have expected you to find it there since that's pretty dense. In fact, older versions of the Python doc used to describe this section as for language lawyers but I see they've changed that now. However, it's still written for language lawyers. IMHO, the lack of a reference manual for the language itself is a major hole in Python's documentation. I agree. -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On 2010-11-05, Nobody nob...@nowhere.com wrote: However, it's still written for language lawyers. IMHO, the lack of a reference manual for the language itself is a major hole in Python's documentation. I'm a bit lost here. Could you highlight some of the differences between a reference manual for the language itself and something written for language lawyers? -s -- 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
Re: Silly newbie question - Carrot character (^)
On Fri, 05 Nov 2010 22:51:10 +, Seebs wrote: On 2010-11-05, Nobody nob...@nowhere.com wrote: However, it's still written for language lawyers. IMHO, the lack of a reference manual for the language itself is a major hole in Python's documentation. I'm a bit lost here. Could you highlight some of the differences between a reference manual for the language itself and something written for language lawyers? +1 QOTW -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On Nov 5, 2010, at 6:51 PM, Seebs wrote: On 2010-11-05, Nobody nob...@nowhere.com wrote: However, it's still written for language lawyers. IMHO, the lack of a reference manual for the language itself is a major hole in Python's documentation. I'm a bit lost here. Could you highlight some of the differences between a reference manual for the language itself and something written for language lawyers? The former refers to something that programmers would use to learn the language once they've gone through the tutorial a few times. The latter is great for writing a Python parser but isn't the friendliest guide to language constructs. Take the OP's question. How is one supposed to find out about bitwise operators in Python? AFAICT they're not mentioned in the tutorial, and neither are decorators, assert(), global, exec, the ternary if statement, etc. It seems that plowing through a document written for language lawyers is the only formal way to learn about those language features, and that could be improved upon IMO. Cheers Philip -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On 2010-11-06, Philip Semanchuk phi...@semanchuk.com wrote: The former refers to something that programmers would use to learn the language once they've gone through the tutorial a few times. The latter is great for writing a Python parser but isn't the friendliest guide to language constructs. That sounds, then, like it's not very well written, even for language lawyers. It seems that plowing through a document written for language lawyers is the only formal way to learn about those language features, and that could be improved upon IMO. It sounds to me like it could be improved on, but I don't think the problem is written for language lawyers, but not very well done. If you do a good job of writing something useful to language lawyers, any programmer should be able to look things up in it. -s -- 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
Re: Silly newbie question - Carrot character (^)
On Fri, 05 Nov 2010 23:21:11 -0400, Philip Semanchuk wrote: Take the OP's question. How is one supposed to find out about bitwise operators in Python? AFAICT they're not mentioned in the tutorial, and neither are decorators, assert(), global, exec, the ternary if statement, etc. The tutorial isn't meant as an exhaustive lesson on every single Python feature. There are plenty of other resources available: learning Python *starts* with the python.org tutorial (or some equivalent), it doesn't end there. As far as the OP's question, I'm kind of surprised that he wasn't told that Google is his friend. The very first hit for python caret answers his question. If he had spent even five seconds googling, he would have got his answer. http://www.google.co.uk/search?hl=ensafe=offq=python+caretbtnG=Search It seems that plowing through a document written for language lawyers is the only formal way to learn about those language features, and that could be improved upon IMO. Google on Python book and you will find dozens of other formal ways to learn about language features. At the interactive interpreter, type help(^) and press Enter, and (assuming your help system is set up correctly, which it may not be) you will get a table of operators, including ^ and . Is it reasonable to assume somebody knows that symbols like + - * and ^ are called operators in most programming languages? I think so -- you have to assume some level of knowledge. So you could start at the Python language reference and scan the table of contents by eye for operators operations, ops or similar. This gives: 5. Expressions 5.1. Arithmetic conversions 5.2. Atoms 5.3. Primaries 5.4. The power operator 5.5. Unary arithmetic and bitwise operations 5.6. Binary arithmetic operations 5.7. Shifting operations 5.8. Binary bitwise operations ... Admittedly, the language reference is a bit n00b-hostile with it's use of extended BNF notation for syntax. But I don't think it's entirely unreasonable to expect even a newbie to read and understand: The ^ operator yields the bitwise XOR (exclusive OR) of its arguments, which must be plain or long integers. The arguments are converted to a common type. So, yes, the docs could be improved. They could *always* be improved, because somebody will always find something they don't like -- too detailed, not detailed enough, too long, too short, too hard for newbies, too dumbed down, not dumbed down enough... -- Steven -- http://mail.python.org/mailman/listinfo/python-list
Re: Silly newbie question - Carrot character (^)
On Sat, 06 Nov 2010 04:33:25 +, Steven D'Aprano wrote: As far as the OP's question, I'm kind of surprised that he wasn't told that Google is his friend. The very first hit for python caret answers his question. If he had spent even five seconds googling, he would have got his answer. http://www.google.co.uk/search?hl=ensafe=offq=python+caretbtnG=Search Ha, on the other hand googling for python carrot isn't helpful at all. But python carrot operator *does* give the same link as above. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
