Re: [Python-Dev] Sets are mappings?
Aahz wrote: On Wed, Dec 21, 2005, Michael Chermside wrote: So I have a counter-proposal. Let's NOT create a hierarchy of abstract base types for the elementary types of Python. (Even basestring feels like a minor wart to me, although for now it seems like we need it.) If the core problem is how do you create a canonical ordering for objects that survives serialization and deserialization into a different VM?, then somehow abstract base types doesn't seem like the most obvious solution. And if that's not the problem we're trying to solve here, then what IS? Because I don't know of very many ACTUAL (as opposed to theoretical) use cases for abstract base classes of fundamental types. You've got a good point, but the documentation issue still exists; that's what I was more interested in. Clearly lists, tuples, and strings are sequences; clearly dicts are a mapping; the question is whether sets get tossed in with dicts. Overall, I think it's pretty clear that the answer is no, particularly given that sets don't support __getitem__(). Like Aahz, my interest is more pedagogic than practical. Python's slightly unusual in that the behaviour of sequences and multi-dimensional arrays (or any kind of mapping, really) is more a matter of convention than anything enforced by the language - whether or not a container understands slices or a tuple of slices is the closest thing I've found to a reliable indicator as to whether or not something is a sequence or multiarray rather than a simple mapping. So in looking for a defining characteristic for those two terms (sequence, in particular, is a term that gets thrown around a lot without being really well defined), those are the main features I'd pick. In practice, as MC said in his other email, just try it and see what happens is generally a far better approach. To answer MC's other point in that email, I actually agree it's perfectly possible to have a mapping which is not a container, so the structure of the taxonomy should be eliminated entirely. Whether or not something is a container and whether or not it is a mapping are independent questions. Cheers, Nick. -- Nick Coghlan | [EMAIL PROTECTED] | Brisbane, Australia --- http://www.boredomandlaziness.org ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] status of development documentation
[EMAIL PROTECTED] wrote: Fredrik If you google c.l.python for the word documentation, you'll Fredrik find recent megathreads with subjects like bitching about the Fredrik documentation, opensource documentation problems and python Fredrik documentation should be better among the top hits. But if you Fredrik check the bug and patch trackers, you don't find many Fredrik contributions. Something's definitely broken. People find it easier to complain than to contribute. Maybe we should fix that problem... I very much agree that we should, and *not* by making it more difficult to complain ;-) Could the PSF help here by offering annual prizes for the best contributions to the documentation, or wouldn't that be an adequate motivator? regards Steve -- Steve Holden +44 150 684 7255 +1 800 494 3119 Holden Web LLC www.holdenweb.com PyCon TX 2006 www.python.org/pycon/ ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Sets are mappings?
Michael Chermside [EMAIL PROTECTED] writes: So I have a counter-proposal. Let's NOT create a hierarchy of abstract base types for the elementary types of Python. +1 Cheers, mwh -- bruce how are the jails in israel? itamar well, the one I was in was pretty nice -- from Twisted.Quotes ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] status of development documentation
Fredrik Lundh [EMAIL PROTECTED] writes: Checked the python-list archives lately? If you google c.l.python for the word documentation, you'll find recent megathreads with subjects like bitching about the documentation, opensource documentation problems and python documentation should be better among the top hits. But if you check the bug and patch trackers, you don't find many contributions. Something's definitely broken. Hmm, it's this discussion again! Let me make my point again! Writing good documentation is hard. And sometimes the problem is that the document isn't really structured right, or it has been hastily updated to cover too many changes that it's a dogs breakfast, or some other 'global' problem and these *really* take time to fix. I really, really don't think the formatting tools make that much difference in the grand scheme of things. I think streamlining the process of getting a patch in would help a lot more (and not just for the documentation, obviously) but still not *that* much. Cheers, mwh (another one in the 'hates editing HTML' camp, if anyone's counting) -- The ability to quote is a serviceable substitute for wit. -- W. Somerset Maugham ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] status of development documentation
Ian Bicking wrote: This is somewhat tangential to this discussion, but I did have the Python documentation in mind as a potential future target for Commentary: http://pythonpaste.org/comment/commentary/ -- which would allow more casual contributions that seem to work well for other projects. indeed. Commentary worked better this time than last time I tinkered with it. a few notes: - it would be nice to be able to cancel a new note by double-clicking again in the same spot (at least as long as the note is empty) - IE support seems to be a little shaky; klicking and entering text works fine, but when I click save, nothing happens. in IE, that is. if I look at the site in Firefox, the note is there. - if you click edit this comment on an existing note, and then click cancel, the note disappears (in Firefox). double-clicking on the associated block no longer works, after that, so the note is still in there somewhere... - many notes added to the same place may squeeze the original text into a very narrow column. note sure how to address that, but some kind of mini- mize or hide feature could be nice. /F ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] status of development documentation
Steve Holden writes: Could the PSF help here by offering annual prizes for the best contributions to the documentation, or wouldn't that be an adequate motivator? Money is not a very effective motivator for this sort of work. (Well, in sufficient quantities it is, but the quantities required are quite large.) Offering *credit* is more effective -- a mention within a contributors list perhaps. Even more effective is offering the chance to make a difference: immediate feedback (seeing your edit in place). Thus, I'm a big fan of amk's suggestion: I think the most effective thing would be [...] to build a real comment-on-the-docs system. But I agree strongly with Fred's concerns: he was worried about whether anyone would garden the comments to remove spam. and as Michael Hudson put it: Writing good documentation is hard. And sometimes the problem is that the document isn't really structured right, or it has been hastily updated to cover too many changes that it's a dogs breakfast, or some other 'global' problem and these *really* take time to fix. My own favorite idea is to create a comment-on-the-docs mechanism allowing both COMMENTS, and PROPOSED EDITS. The proposed edits would need to be reviewed by one of a small number of skilled and dedicated editors (Fred Drake... you're a hero!) before being officially incorporated. That's not all that different from the current system (submit a patch to sourceforge), except that the format for entering the change would be simpler. Of course, the person who REALLY gets to decide how it works isn't me; it's whoever decides to spend the time to BUILD this system. -- Michael Chermside ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] status of development documentation
On Thursday 22 December 2005 08:50, Michael Chermside wrote: Money is not a very effective motivator for this sort of work. (Well, in sufficient quantities it is, but the quantities required are quite large.) Offering *credit* is more effective -- a mention within a contributors list perhaps. There is a credits list for the documentation, and it's included in the HTML version of the formatted result as well. Extra credit if you know where it is without looking, though. My own favorite idea is to create a comment-on-the-docs mechanism allowing both COMMENTS, and PROPOSED EDITS. The proposed edits would need to be reviewed by one of a small number of skilled and dedicated I'm unclear on what you buy with having these two labels; are comments things that (presumably) get ignored by the documentation editor, or are the proposed edits simply more specific? If the later, I'm not sure having the labels helps. (I'm also concerned that the whole thing could end up being misused as a help desk, littering the docs with questions about application problems.) Of course, the person who REALLY gets to decide how it works isn't me; it's whoever decides to spend the time to BUILD this system. The builder certainly determines what they build, but in the longer term, whoever is using it to incorporate changes into the documentation will likely have something to say about it, since that's who determines if it actually gets used to improve the documentation. -Fred -- Fred L. Drake, Jr. fdrake at acm.org ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] status of development documentation
2005/12/21, Phillip J. Eby [EMAIL PROTECTED]: 3. Fredrik believes that more people would participate in updating Python documentation if it didn't require a LaTeX toolchain or LaTeX-friendly editor. I'm sure he's right. I'm not talking about any random user that finds a doc bug and wants to generate a patch, here I'm talking of my own experience: I had to correct a few lines in the almost perfect documentation that Raymond generated for Decimal. I fighted with my Linux (at that time, FC1) to be able to compile the docs, and couldn't do it. I ended touching the XML by hand. It worked, but a) Took some time. b) Wasn't really sure that it was well corrected. So, I really think that a more human friendly format will help here. What I do NOT know, if the effort of converting the whole docs to another format is worth it, and that effort should be deviated to something that will help more other users to help with docs (for example, that the official docs could be annotatted, a la MySQL (AMK did something like this, right?)). Regards, .Facundo Blog: http://www.taniquetil.com.ar/plog/ PyAr: http://www.python.org/ar/ ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] status of development documentation
At 10:27 AM 12/22/2005 +0100, Walter Dörwald wrote: Phillip J. Eby wrote: [...] If someone has examples of actual Pythondoc markup that don't translate to reST, I'd be really interested in seeing them, just for my own education. Of course, I'd also be curious how common such constructs are. I'm using XML markup for our packages. Examples can be found at [snip] By Pythondoc, I mean the LaTeX-based markup system being used for the official Python documentation, not arbitrary methods of documentation for Python code. The source is definitely wordier than reST, but adding new markup is trivial. Take a look at http://www.livinglogic.de/Python/xist/Download.html and at the source at http://www.livinglogic.de/Python/xist/Download.htmlxsc. The download element automatically determines the size of the package. Source can be found here http://www.livinglogic.de/viewcvs/index.cgi/LivingLogic/WWW-Python/site/Python_xmlns.py?rev=1.43content-type=text/vnd.viewcvs-markup (search for class download). Would something like this be possible with reST? The docutils toolchain converts reST input into a DOM, and allows arbitrary transformation phases to be added to processing before conversion to output. This includes processing of directives, e.g. commands like: .. include:: filename And of interpreted text roles, e.g. `Foobar`:class:. It is not, however, a general XML transformation toolkit, if that's what you're asking. However, if you wanted to be able to use XML input as part of a docutils DOM, you could certainly do that. For that matter, you could take a reST document and simply transform it to XML for use with the rest of your toolset. But this isn't particularly relevant to the discussion about *Python's* documentation, and I'm not even advocating that Python switch, let alone arbitrary other projects. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] Patch to make unittest.TestCase easier to subclass
Hello all! I just submitted Patch #1388073, designed to make unittest's TestCase class easier to subclass, and I'd appreciate a review of/feedback on the code there. While recently working on a subclass of unittest.TestCase to support TODO-tests, I found a large number of __-prefixed attributes in TestCase. The presence of these attributes meant that I had to copy several methods over to my new subclass in order for things to work. The patch I've provided converts these __-prefixed attributes to _-prefixed attributes, making it much simpler to subclass TestCase. The patch is against unittest.py from SVN revision 41775. Included with the patch are before and after versions of my subclass showing the impact of the change to unittest.TestCase. Thanks, Collin Winter ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] timeout options in high-level networking modules
Yesterday, I needed to make a web request in a program (actually a test) that could block indefinately, so I needed to set a socket timeout. Unfortunately, AFAICT none of urllib, urllib2, httplib provide options to set the timeout on the sockets they use. I ended up having to roll my own code to make the request. It would be nice if high-level network modules, like the ones mentioned above, had options to provide a timeout. (For example, urlopen could grow an optional timout argument.) Thoughts? If we think this is a good idea, then someone who has time could start chipping away at it. I'm happy to work on this *if* I can find time. This would make a nice easy sprint project at PyCon too. Jim -- Jim Fulton mailto:[EMAIL PROTECTED] Python Powered! CTO (540) 361-1714http://www.python.org Zope Corporation http://www.zope.com http://www.zope.org ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] timeout options in high-level networking modules
Yup. I just went through a similar exercise with urllib2. It wasn't too hard to plumb through a different HTTPHandler that set the timeout, but it would be much nicer as a default option. It seems like a 30 minute project; might fit in an odds and ends sprint. Jeremy On 12/22/05, Jim Fulton [EMAIL PROTECTED] wrote: Yesterday, I needed to make a web request in a program (actually a test) that could block indefinately, so I needed to set a socket timeout. Unfortunately, AFAICT none of urllib, urllib2, httplib provide options to set the timeout on the sockets they use. I ended up having to roll my own code to make the request. It would be nice if high-level network modules, like the ones mentioned above, had options to provide a timeout. (For example, urlopen could grow an optional timout argument.) Thoughts? If we think this is a good idea, then someone who has time could start chipping away at it. I'm happy to work on this *if* I can find time. This would make a nice easy sprint project at PyCon too. Jim -- Jim Fulton mailto:[EMAIL PROTECTED] Python Powered! CTO (540) 361-1714http://www.python.org Zope Corporation http://www.zope.com http://www.zope.org ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/jeremy%40alum.mit.edu ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] timeout options in high-level networking modules
Jim Fulton wrote: Yesterday, I needed to make a web request in a program (actually a test) that could block indefinately, so I needed to set a socket timeout. Unfortunately, AFAICT none of urllib, urllib2, httplib provide options to set the timeout on the sockets they use. I ended up having to roll my own code to make the request. It would be nice if high-level network modules, like the ones mentioned above, had options to provide a timeout. (For example, urlopen could grow an optional timout argument.) Thoughts? If we think this is a good idea, then someone who has time could start chipping away at it. I'm happy to work on this *if* I can find time. This would make a nice easy sprint project at PyCon too. That's a very good idea. At present the only option one has is to set a global socket.defaulttimout() or somehow monkey-patch the modules you want to use, and neither of those options are entirely satisfactory. Basically any method that can create a new TCP connection should acquire an optional timeout=None parameter, right? regards Steve -- Steve Holden +44 150 684 7255 +1 800 494 3119 Holden Web LLC www.holdenweb.com PyCon TX 2006 www.python.org/pycon/ ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] status of development documentation
Whenever people have demanded that I write documentation in html I have always done this: pre all my documentation, as output from a text editor. All subsequent formatting to be done by somebody else who doesn't find dealing with html as excruciatingly painful as I do. /pre I suspect there are lots of people who have concluded that this is all the html that you really need. The question is, are you willing to put up with documentation like this from people? Laura ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] timeout options in high-level networking modules
Steve Holden [EMAIL PROTECTED] wrote: Jim Fulton wrote: Yesterday, I needed to make a web request in a program (actually a test) that could block indefinately, so I needed to set a socket timeout. Unfortunately, AFAICT none of urllib, urllib2, httplib provide options to set the timeout on the sockets they use. I ended up having to roll my own code to make the request. [...] That's a very good idea. At present the only option one has is to set a global socket.defaulttimout() or somehow monkey-patch the modules you want to use, and neither of those options are entirely satisfactory. Basically any method that can create a new TCP connection should acquire an optional timeout=None parameter, right? Yes. It might also be nice if the modules that rely on blocking mode being set on sockets (basically anything using socket.ssl()) actually explicitly set that first. Right now, if you do socket.setdefaulttimeout() to a non-None value and then try to use anything that does SSL (poplib, imaplib), the connections will quickly die. Charles -- --- Charles Cazabon [EMAIL PROTECTED] GPL'ed software available at: http://pyropus.ca/software/ --- ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] LaTeX and Python doc contributions
Just a quick note based on some of the discussion on the Doc-SIG list: Some people are getting asked to convert their documentation contributions to LaTeX themselves, and that *is* a barrier to contribution. I've generally stated that I'm willing to perform conversion, making plain text / ReST completely acceptable for documentation contributions. Others have commonly converted plain text to LaTeX as well. I'd like to make sure that Python committers know that this is reasonable; if the only thing holding a contribution back is LaTeXification of documentation, feel free to assign it to me for conversion. I do not want LaTeX itself to cause us to lose documentation contributions; the hard part for documentation really is getting good content. Hard workers shouldn't be turned away. :-) -Fred -- Fred L. Drake, Jr. fdrake at acm.org ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] status of development documentation
I wrote: My own favorite idea is to create a comment-on-the-docs mechanism allowing both COMMENTS, and PROPOSED EDITS. Fred Drake replies: I'm unclear on what you buy with having these two labels; are comments things that (presumably) get ignored by the documentation editor, or are the proposed edits simply more specific? Things that get ignored by the doc editors. (I'm also concerned that the whole thing could end up being misused as a help desk, littering the docs with questions about application problems.) Me too. Specifically, I think if you make it really easy to write notes on the docs you will get some helpful documentation content. You will also get lots of things that are too lengthy or exhaustive, to specific to one person's problem, helpdesk style questions, and probably spam. All I meant was to allow the contributor to specify which category they think this particular note belongs to so the doc editors can read only the ones that people thought ought to be included in the docs. -- Michael Chermside ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] LaTeX and Python doc contributions
Fred Some people are getting asked to convert their documentation Fred contributions to LaTeX themselves... Who is asking this of potential contributors? I know you, Aahz and I have repeatedly told people on c.l.py that LaTeX knowledge is not necessary. Plain text is okay. What do we need to do to squash this meme? Tony other python-dev summarizers (and maybe Cameron Laird for the c.l.py summaries): please make a note of this in your next summary. The I-can't-contribute-because-I-don't-know-LaTeX notion has to die, die, die. Skip ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] status of development documentation
Michael Chermside wrote:¨ Me too. Specifically, I think if you make it really easy to write notes on the docs you will get some helpful documentation content. You will also get lots of things that are too lengthy or exhaustive, to specific to one person's problem, helpdesk style questions, and probably spam. fwiw, the effbot.org useredit mechanism results in nice patches, suggestions, occasional questions, and, in periods, huge amounts of spam (from spammers who treat it as an ordinary wiki). /F ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] documentation comments
On 12/22/05, A.M. Kuchling [EMAIL PROTECTED] wrote: I had lunch with Fred the other day, and he was worried about whether anyone would garden the comments to remove spam. I would help assuming this is easy--meaning a single click to remove a comment. n ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] timeout options in high-level networking modules
Steve Holden wrote: Jim Fulton wrote: Yesterday, I needed to make a web request in a program (actually a test) that could block indefinately, so I needed to set a socket timeout. Unfortunately, AFAICT none of urllib, urllib2, httplib provide options to set the timeout on the sockets they use. I ended up having to roll my own code to make the request. It would be nice if high-level network modules, like the ones mentioned above, had options to provide a timeout. (For example, urlopen could grow an optional timout argument.) Thoughts? If we think this is a good idea, then someone who has time could start chipping away at it. I'm happy to work on this *if* I can find time. This would make a nice easy sprint project at PyCon too. That's a very good idea. At present the only option one has is to set a global socket.defaulttimout() or somehow monkey-patch the modules you want to use, and neither of those options are entirely satisfactory. Dang, I missed that. I could have abused that yesterday. :) Basically any method that can create a new TCP connection should acquire an optional timeout=None parameter, right? Yup, except that None shouldn't be the I didn't pass anything marker, since None is a valid settimeout parameter. Jim -- Jim Fulton mailto:[EMAIL PROTECTED] Python Powered! CTO (540) 361-1714http://www.python.org Zope Corporation http://www.zope.com http://www.zope.org ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] LaTeX and Python doc contributions
On Thu, Dec 22, 2005 at 12:23:03PM -0600, [EMAIL PROTECTED] wrote: Who is asking this of potential contributors? I know you, Aahz and I have repeatedly told people on c.l.py that LaTeX knowledge is not necessary. One comment on a bug to this effect was found. I don't think there's a point in naming names -- the person in question doubtless just wasn't aware of this policy. --amk ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] status of development documentation
On 12/21/05, Barry Warsaw [EMAIL PROTECTED] wrote: On Wed, 2005-12-21 at 20:36 +0100, Fredrik Lundh wrote: I'm not really interested in optimizing for you, I'm interested in optimizing for everyone else. They already know HTML. They don't know ReST, and I doubt they care about it (how many blogs accept ReST for comments?) Sorry, but HTML and (even more so) XML are not human-writable. :) Yeah, we can all do the simple stuff, but I absolutely hate authoring in HTML, and it would be a nightmare if the documentation production system didn't handle lots and lots of magic for you (like weaving in the right footers, css, etc. -- oh wait, that's ht2html!). reST is a fine language but it seems more suitable to simpler linear documents like wiki pages and PEPs, rather than those with complicated nested structure. Maybe it's just because I came in late on this thread, but what exactly is broken about the current LaTeX documentation? -Barry Good point. Nothing is really broken, but it's just not flexible because there is no way to get a solid document model from LaTeX to do some conversion and processing on. i.e. you convert from LaTeX direct to the output. Having the intermediate representation would allow generating nicer output, and in more formats, without necessarily having to reparse the input everytime either. What we need is not necessarily a change of syntax: the problem is not the input, it's the conversion. The input is fine--if someone can't learn the super simple LaTeX macros for the Python docs, I don't want to imagine what kind of prose they would come up with. LaTeX is NOT hard, at least if you limit yourself to the stuff you need to document Python code. About ReST: Somehow there is a recurrent stream of people--include me at some point-- who think that ReST could express any document structure for any task, and that if we use that we will be happy ever after. ReST does an amazing job of inferring generic document structures from text, but for documenting source code, you really want to be able to say This is a function, this is an optional argument, etc. ReST does not provide this kind of functionality, and if you try to stretch the interpreted roles to do this you get an equally ugly syntax as LaTeX input (I would even argue that I prefer the LaTeX source). Also, ReST has many gotchas: if you will infer structures from invisible markup, it's very easy to make mistakes, and there are many cases where it's not clear what the parsed document will be like, you have to learn a lot of how it parses the documents, and the corner cases, by checking with rst2pseudoxml.py. I'm facing this problem with some of my Nabu extractors, which attempts to extract semantically meaningful chunks out of the docutils tree, for example, contact information. If there is a problem it is not the input, it's the toolchain and conversion. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] timeout options in high-level networking modules
Charles Cazabon wrote: It might also be nice if the modules that rely on blocking mode being set on sockets (basically anything using socket.ssl()) actually explicitly set that first. Right now, if you do socket.setdefaulttimeout() to a non-None value and then try to use anything that does SSL (poplib, imaplib), the connections will quickly die. There is a patch for that in python patch tracking system. Just someone needs to recheck it and apply. Charles ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] LaTeX and Python doc contributions
On Thursday 22 December 2005 13:39, Facundo Batista wrote: Very interesting. What I don't know here is how to submit patches... Patches certainly isn't the right word for changes not described as source diffs. I cleaned up some text about that on python.org earlier. I mean, if they were in LaTeX, a diff file would be enough. But in plain text (or ReST), how should people specify the corrections, the position of new paragraphs, etc? In English is fine. I'd expect something like: in the section on imaplib, before the paragraph starting with I often get descriptions like this when people point out typos to the docs at python.org address; it works well, and has almost no barriers to entry at all. I'm really interested in this, we've been discussing about docs in Python Argentina and some people were willing to help (and scared about LaTeX). Hopefully we can make sure it's easy for everyone to contribute. I'm certainly interested in suggestions, though I make all of them happen. -Fred -- Fred L. Drake, Jr. fdrake at acm.org ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] LaTeX and Python doc contributions
On Thursday 22 December 2005 13:23, [EMAIL PROTECTED] wrote: Who is asking this of potential contributors? I know you, Aahz and I have repeatedly told people on c.l.py that LaTeX knowledge is not necessary. Plain text is okay. What do we need to do to squash this meme? As Andrew noted, it doesn't really matter who it was. That person is now aware of what's going on, I think. :-) I've added a note to the developer's intro, and there should probably be a note in the development FAQ as well. Tony other python-dev summarizers (and maybe Cameron Laird for the c.l.py summaries): please make a note of this in your next summary. The I-can't-contribute-because-I-don't-know-LaTeX notion has to die, die, die. An excellent idea! -Fred -- Fred L. Drake, Jr. fdrake at acm.org ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] documentation comments
On Thursday 22 December 2005 13:44, Neal Norwitz wrote: I would help assuming this is easy--meaning a single click to remove a comment. It looks like the system the MySQL folks are using makes it easy, but I've not tried polluting their documentation with tests, just in case. :-) In general, my worry is less with dealing with spam than with ensuring integration of content enhancements before release candidates go out. -Fred -- Fred L. Drake, Jr. fdrake at acm.org ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] reST limitations? (was Re: status of development documentation)
At 04:08 PM 12/22/2005 -0500, Martin Blais wrote: ReST does an amazing job of inferring generic document structures from text, but for documenting source code, you really want to be able to say This is a function, this is an optional argument, etc. ReST does not provide this kind of functionality, and if you try to stretch the interpreted roles to do this you get an equally ugly syntax as LaTeX input (I would even argue that I prefer the LaTeX source). That sounds like a misuse of the tool to me; if you need structured, extractable information from a reST document, fields and directives are probably going to be the way to go. Similarly, I'd suggest that interpreted roles to identify the context of a name probably isn't the best way to go about it either; a link to the definition of the referenced item will be more useful and more uniform. A formatter or intermediate processor can then decide whether it should actually be rendered as a hyperlink, a fully-qualified name, or just the function/method/class name. So, definitions of functions, classes, and other structured stuff would just use fields under a directive, and references to those definitions would just be reST links. Also, ReST has many gotchas: if you will infer structures from invisible markup, it's very easy to make mistakes, and there are many cases where it's not clear what the parsed document will be like, you have to learn a lot of how it parses the documents, and the corner cases, by checking with rst2pseudoxml.py. Huh? I've never used rst2pseudoxml.py, so I don't understand how it's a requirement. Do you mean, if you're writing some kind of reST processor it's helpful to understand how stuff is parsed? Can you list some of these gotchas? I've on maybe two occasions had to add a backslash to something to prevent it being interpreted as markup, and that's about it, although I've written many hundreds of K of Python documentation in reST. (Not the Python core documentation, but other open source projects written in Python.) ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] reST limitations? (was Re: status of development documentation)
On 12/22/05, Phillip J. Eby [EMAIL PROTECTED] wrote: At 04:08 PM 12/22/2005 -0500, Martin Blais wrote: ReST does an amazing job of inferring generic document structures from text, but for documenting source code, you really want to be able to say This is a function, this is an optional argument, etc. ReST does not provide this kind of functionality, and if you try to stretch the interpreted roles to do this you get an equally ugly syntax as LaTeX input (I would even argue that I prefer the LaTeX source). That sounds like a misuse of the tool to me; if you need structured, extractable information from a reST document, fields and directives are probably going to be the way to go. Similarly, I'd suggest that interpreted roles to identify the context of a name probably isn't the best way to go about it either; a link to the definition of the referenced item will be more useful and more uniform. A formatter or intermediate processor can then decide whether it should actually be rendered as a hyperlink, a fully-qualified name, or just the function/method/class name. So, definitions of functions, classes, and other structured stuff would just use fields under a directive, and references to those definitions would just be reST links. So you end up with a document with a bunch of custom directives, like:: .. python-class:: MyClass :arg: comfobulator :arg optional: bliptor My Class description. This does not look significantly better to me than the LaTeX code, and the docutils directives are not as flexible as the commands provided by tex/latex. Also, ReST has many gotchas: if you will infer structures from invisible markup, it's very easy to make mistakes, and there are many cases where it's not clear what the parsed document will be like, you have to learn a lot of how it parses the documents, and the corner cases, by checking with rst2pseudoxml.py. Huh? I've never used rst2pseudoxml.py, so I don't understand how it's a requirement. Do you mean, if you're writing some kind of reST processor it's helpful to understand how stuff is parsed? It is if you're relying on specific document structures to provide information about your special constructs. rst2pseudoxml.py just helps you display that parsed structure. For example, you could write some kind of processor on the docutils document tree that looks for definition lists whose term starts with class and then assumes some other things about what it will find in the body of this definition, e.g. class MyClass Some indented material about the class MyClass (this gets parsed as a ReST definition term/body because of the indented line right after the class MyClass line). I'm doing this kind of processing, albeit in a limited way, to extract book reviews, bookmarks, and contact info from a body of text files that I maintain, using my nabu system (http://furius.ca/nabu/ come to my talk at PyCon for mode details). This might be a better way to hijack ReST than to create a gazillion custom directives, thereby creating more or less another markup language (with a smaller userbase, less tested!). Can you list some of these gotchas? I've on maybe two occasions had to add a backslash to something to prevent it being interpreted as markup, and that's about it, although I've written many hundreds of K of Python documentation in reST. (Not the Python core documentation, but other open source projects written in Python.) Lots. No time to go through the whole list now, but here is an example: - .. Some text - and - .. Some text - Generate the following document structures, respectively: comment xml:space=preserve Some text and comment xml:space=preserve block_quote paragraph Some text One is a comment, the other is an empty comment followed by a block quote. Not very obvious to me, unless you know the rules. Easy to make mistakes. There are *many* other issues just like this one. Pop quiz: what does this generate? - .. Some text Some other text - ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] LaTeX and Python doc contributions
Fred == Fred L Drake, [EMAIL PROTECTED] writes: Fred On Thursday 22 December 2005 13:23, [EMAIL PROTECTED] wrote: Who is asking this of potential contributors? I know you, Aahz and I have repeatedly told people on c.l.py that LaTeX knowledge is not necessary. Plain text is okay. What do we need to do to squash this meme? Fred As Andrew noted, it doesn't really matter who it was. I interpreted Skip's first question as 100% rhetorical.wink I think one aspect of the meme is that projects generally strongly emphasize standard-format patches to source for code. But this is typically less important for documentation, where good and consistent natural language style probably means that the editor applies the patch, and then revises in place rather than requesting a revision from the contributor. I don't know whether that distinction helps with creating a vaccine, though. I don't see an obvious application beyond the suggestion of saying patches aren't necessary more frequently and prominently. -- School of Systems and Information Engineering http://turnbull.sk.tsukuba.ac.jp University of TsukubaTennodai 1-1-1 Tsukuba 305-8573 JAPAN Ask not how you can do free software business; ask what your business can do for free software. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] status of development documentation
Facundo Batista wrote: 2005/12/21, Phillip J. Eby [EMAIL PROTECTED]: 3. Fredrik believes that more people would participate in updating Python documentation if it didn't require a LaTeX toolchain or LaTeX-friendly editor. I'm sure he's right. I'm not talking about any random user that finds a doc bug and wants to generate a patch, here I'm talking of my own experience: I had to correct a few lines in the almost perfect documentation that Raymond generated for Decimal. I fighted with my Linux (at that time, FC1) to be able to compile the docs, and couldn't do it. I ended touching the XML by hand. It worked, but a) Took some time. b) Wasn't really sure that it was well corrected. So, I really think that a more human friendly format will help here. What I do NOT know, if the effort of converting the whole docs to another format is worth it, and that effort should be deviated to something that will help more other users to help with docs (for example, that the official docs could be annotatted, a la MySQL (AMK did something like this, right?)). If I remember rightly, the biggest problem I had in the whole exercise was getting latex2html to run - I actually had to modify the Perl source to get it to work (fortunately, I didn't have to try to *understand* said source first - other people had already figured out the necessary incantations, so I was able to find out how to fix it via a Google search). latex/tex weren't a big problem, because they were in the distro archives - but latex2html was a definite pain. Cheers, Nick. -- Nick Coghlan | [EMAIL PROTECTED] | Brisbane, Australia --- http://www.boredomandlaziness.org ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] status of development documentation
On 22 Dec 2005, at 3:51, Michael Hudson wrote: Fredrik Lundh [EMAIL PROTECTED] writes: Checked the python-list archives lately? If you google c.l.python for the word documentation, you'll find recent megathreads with subjects like bitching about the documentation, opensource documentation problems and python documentation should be better among the top hits. But if you check the bug and patch trackers, you don't find many contributions. Something's definitely broken. Hmm, it's this discussion again! Let me make my point again! Writing good documentation is hard. I can only speak for my own experience, but maybe it will help. I once tried to help fix a piece of the python docs. The description of Py_UNICODE on http://docs.python.org/api/unicodeObjects.html was -- and still is -- incorrect. Looking through my mail archives, I sent a patch on 10 October, which was apparently taken, but never showed up on the web site. I emailed a few reminders, but was eventually told that I should email a third person -- who didn't have an email address. At that point I passed the level of effort I was willing to put in. :) I think I probably put more effort into it than an average person would, so I think the barriers of entry are much higher than they should be. Perhaps something with fast feedback would work a lot better. It seems to work well for Wikipedia. robey ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
