# Python Tutorial - urllib2

18 messages
Open this post in threaded view
|

## Python Tutorial - urllib2

 By the way (and in the vain (sic) of shameless self-promotion...) there was a suggestion on Dobbs Python-URL that the inclusion of some of my material on urllib2 would be welcome in the tutorial. http://groups.google.com/group/comp.lang.python/browse_frm/thread/1d52898f07b7dfcd/d015de23ad6818faMy tutorial is at : http://www.voidspace.org.uk/python/urllib2.shtmlThe most appropriate sections to include would be on fetching URLs and handling errors, and possibly the basic authentication example. It probably fits best in the 'Brief tour of the standard library'. Would that be welcomed ? It is currently in rest format - and html of course ;-) Is reST acceptable for *someone* to add this material - and if so, what should I do about it ? By the way my vote is -1 on moving to html as the standard markup format and +1 on working on docutils to turn that into an usable input format. Additionally - having a wiki version, or a version that accepts user commentary would be a very useful way of gathering additional information. Of course someone has to maintain this... I think AMK did a simple implementation of this a while ago - although it had usability issues and the resulting data didn't seem to be used. I guess this is all part of the ongoing discussion. All the best, Fuzzyman http://www.voidspace.org.uk/python/index.shtml_______________________________________________ Doc-SIG maillist  -  [hidden email] http://mail.python.org/mailman/listinfo/doc-sig
Open this post in threaded view
|

## Re: Python Tutorial - urllib2

 Michael Foord wrote: > By the way (and in the vain (sic) of shameless self-promotion...) there > was a suggestion on Dobbs Python-URL that the inclusion of some of my > material on urllib2 would be welcome in the tutorial. > > http://groups.google.com/group/comp.lang.python/browse_frm/thread/1d52898f07b7dfcd/d015de23ad6818fa> > My tutorial is at : http://www.voidspace.org.uk/python/urllib2.shtml> Oops... correction : http://www.voidspace.org.uk/python/articles/urllib2.shtmlSorry about that. I *would* be interested in helping with the Python tutorial (and docs where appropriate). it's a question of knowing where to begin... All the best, Fuzzyman http://www.voidspace.org.uk/python/index.shtml> The most appropriate sections to include would be on fetching URLs and > handling errors, and possibly the basic authentication example. It > probably fits best in the 'Brief tour of the standard library'. > > Would that be welcomed ? It is currently in rest format - and html of > course ;-) > > Is reST acceptable for *someone* to add this material - and if so, what > should I do about it ? > > By the way my vote is -1 on moving to html as the standard markup format > and +1 on working on docutils to turn that into an usable input format. > Additionally - having a wiki version, or a version that accepts user > commentary would be a very useful way of gathering additional > information. Of course someone has to maintain this... I think AMK did a > simple implementation of this a while ago - although it had usability > issues and the resulting data didn't seem to be used. I guess this is > all part of the ongoing discussion. > > All the best, > > Fuzzyman > http://www.voidspace.org.uk/python/index.shtml> _______________________________________________ > Doc-SIG maillist  -  [hidden email] > http://mail.python.org/mailman/listinfo/doc-sig> > > _______________________________________________ Doc-SIG maillist  -  [hidden email] http://mail.python.org/mailman/listinfo/doc-sig
Open this post in threaded view
|

## Re: Python Tutorial - urllib2

 In reply to this post by Michael Foord Michael Foord wrote: > By the way my vote is -1 on moving to html as the standard markup format > and +1 on working on docutils to turn that into an usable input format. so how to you plan to achieve the required level of semantic markup in ReST? _______________________________________________ Doc-SIG maillist  -  [hidden email] http://mail.python.org/mailman/listinfo/doc-sig
Open this post in threaded view
|

## Re: Python Tutorial - urllib2

 In reply to this post by Michael Foord On Thu, Dec 22, 2005, Michael Foord wrote: > > Is reST acceptable for *someone* to add this material - and if so, what > should I do about it ? Submit in reST or plain-text and someone will do any necessary conversions.  Really, don't worry about it, Just Do It. -- Aahz ([hidden email])           <*>         http://www.pythoncraft.com/"Don't listen to schmucks on USENET when making legal decisions.  Hire yourself a competent schmuck."  --USENET schmuck (aka Robert Kern) _______________________________________________ Doc-SIG maillist  -  [hidden email] http://mail.python.org/mailman/listinfo/doc-sig
Open this post in threaded view
|

## Re: Python Tutorial - urllib2

Open this post in threaded view
|

## Re: Python Tutorial - urllib2

Open this post in threaded view
|

## Re: Python Tutorial - urllib2

 > >>By the way my vote is -1 on moving to html as the standard markup format > >>and +1 on working on docutils to turn that into an usable input format. > >>Additionally - having a wiki version, or a version that accepts user > >>commentary would be a very useful way of gathering additional > >>information. Of course someone has to maintain this... I think AMK did a > >>simple implementation of this a while ago - although it had usability > >>issues and the resulting data didn't seem to be used. I guess this is > >>all part of the ongoing discussion. > > > > > > There was a long and detailed discussion about using ReST as an input > > format for documentation a while ago.  The consensus was that ReST > > does not allow sufficient markup for technical documentation, which is > > necessary for this kind of document. > > > > Doesn't currently - or can't ? I thought it was just the current state > that was a problem. I'd be disappointed if it was never likely to be > possible to create the python docs with reST. Well, be disappointed. It does not currently, and most likely won't. As much as we all would like some kind of magic silver bullet text format that just "knows" what we mean and want to express, it is rather unlikely that ReST develops to become that for every kind of domain.  ReST does a fair amount of *generic* structure inference, and that is its scope.  The amount of ugly directives and markup being regularly proposed on the docutils mailing-list indicates that ReST may have already reached its potential in terms of automatically guessing structure from simple text files.  Even if this is not the case, extending ReST to include keywords for functions, variables, classes, lists of arguments, etc.  would render it into just an equally ugly form of input equivalent to the current LaTeX sources, ... and without the power of expression of TeX macros! You see, for the technical docs we NEED to indicate the nature of the identifiers, not just to render them consistently, but for generating indexes, and cross-references, and for plenty of fother reasons.  You can't do that in ReST (well, the interpreted roles do take you part of the way, but not enough).  At some point you have to tell the computer all the information that is in your head, and the ReST format simply does not stretch that far, and LaTeX is a great tool for this at the moment. What sucks now is the inflexibliity of the produced document: the tools to convert from the LaTeX sources to other formats are nothing short of wizardry (i.e. LaTeX2html).  What would be great IMO is if we could obtain some kind of meaningful intermediate representation from the source, from which we could then generate various output formats (a bit like how docutils is structured).  I saw some project like that a while ago, generating XML from LaTeX sources, never had time to check it out more seriously. cheers, _______________________________________________ Doc-SIG maillist  -  [hidden email] http://mail.python.org/mailman/listinfo/doc-sig
Open this post in threaded view
|

## Re: Python Tutorial - urllib2

 In reply to this post by Martin Blais-2 On Thu, Dec 22, 2005 at 10:06:48AM -0500, Martin Blais wrote: > Your tutorial is great.  Read it a while ago.  Would love to see it > along the other tutorials or even in the library docs for the module > (as the urllib2 docs are a bit thin on explanations). There's also the Doc/howto directory.  It's not part of the standard documentation set yet, but it already includes one reST document (unicode.rst), so your tutorial could just be added as a urllib2 HOWTO without any conversion.  (At that point we probably *should* be thinking of building the HOWTOs as part of the docset.) --amk _______________________________________________ Doc-SIG maillist  -  [hidden email] http://mail.python.org/mailman/listinfo/doc-sig
Open this post in threaded view
|

## Re: Python Tutorial - urllib2

 A.M. Kuchling wrote: > On Thu, Dec 22, 2005 at 10:06:48AM -0500, Martin Blais wrote: > >>Your tutorial is great.  Read it a while ago.  Would love to see it >>along the other tutorials or even in the library docs for the module >>(as the urllib2 docs are a bit thin on explanations). > > > There's also the Doc/howto directory.  It's not part of the standard > documentation set yet, but it already includes one reST document > (unicode.rst), so your tutorial could just be added as a urllib2 HOWTO > without any conversion.  (At that point we probably *should* be > thinking of building the HOWTOs as part of the docset.) > My source document uses some macros - e.g. to colorize the python code examples. I'm happy to clean it up for inclusion as a "HOWTO Fetch Internet Resources Using urllib2". I don't have unrestricted internet access here (ironically enough) - so could you email me the unicode.rst source so I can give it a similar format. Should I privately email you the result for you to assess ? I could probably complete this tonight... The risk it that it will duplicate some of the material which should be (soon) included in the urllib2 documentation. Again, I could wait until Fred has done this and see if a fuller tutorial is appropriate ? Many Thanks Fuzzyman http://www.voidspace.org.uk/python/index.shtml> --amk > _______________________________________________ > Doc-SIG maillist  -  [hidden email] > http://mail.python.org/mailman/listinfo/doc-sig> > > _______________________________________________ Doc-SIG maillist  -  [hidden email] http://mail.python.org/mailman/listinfo/doc-sig
Open this post in threaded view
|

## Re: Python Tutorial - urllib2

 In reply to this post by Aahz On Thursday 22 December 2005 09:57, Aahz wrote:  > Submit in reST or plain-text and someone will do any necessary  > conversions.  Really, don't worry about it, Just Do It. For the record, I've assigned Fuzzyman's issue to myself, but we should make it easier for other Python project members to refer issues to the LaTeX-willing as needed.  At least better document the policy in general and make sure project members know how to get someone to handle TeXification.   -Fred -- Fred L. Drake, Jr.   _______________________________________________ Doc-SIG maillist  -  [hidden email] http://mail.python.org/mailman/listinfo/doc-sig
Open this post in threaded view
|

## Re: Python Tutorial - urllib2

 In reply to this post by Martin Blais-2 On Thursday 22 December 2005 10:06, Martin Blais wrote:  > Convert it to LaTeX (it's easy) and submit it. Or just submit as ReST, and request conversion.  I like spending my time in XEmacs.  :-)  > The LaTeX input format using the macros from the python docs is very  > simple.  Converting your document should be easy. This is mostly true; some LaTeXishness can be subtle.  If someone does want to do their own LaTeX, that's fine, and I try to make the documentation for the Python-specific macros fairly complete ("Documenting Python": http://docs.python.org/doc/doc.html).  If there are questions after reading that, I'm glad to answer them and improve that document as well.   -Fred -- Fred L. Drake, Jr.   _______________________________________________ Doc-SIG maillist  -  [hidden email] http://mail.python.org/mailman/listinfo/doc-sig
Open this post in threaded view
|

## Re: Python Tutorial - urllib2

 In reply to this post by Martin Blais-2 On Thursday 22 December 2005 10:47, Martin Blais wrote:  > Well, be disappointed.  > It does not currently, and most likely won't. Yes and no. Docutils provides support for creating new directives ("dot-dot things") and interpreted text roles (":colon: things").  These would go a long way to doing what we want, and some experimentation was done toward this specifically to support documenting Python modules in a style similar to the standard library documentation.  This is somewhere in the docutils sandbox.  > guessing structure from simple text files.  Even if this is not the  > case, extending ReST to include keywords for functions, variables,  > classes, lists of arguments, etc.  would render it into just an  > equally ugly form of input equivalent to the current LaTeX sources,  > ... and without the power of expression of TeX macros! Whether :function:os.popen() is any uglier than \function{os.popen()} is largely a matter of what you're used to.  I will note that the LaTeX version is one character shorter.  :-) I think there are appealing qualities to both the TeX macros and the availability of the docutils document object model.  Both allow for lots of neat things.  > What sucks now is the inflexibliity of the produced document: the  > tools to convert from the LaTeX sources to other formats are nothing  > short of wizardry (i.e. LaTeX2html).  What would be great IMO is if we  > could obtain some kind of meaningful intermediate representation from Yes, that is the biggest source of pain.  > the source, from which we could then generate various output formats  > (a bit like how docutils is structured).  I saw some project like that  > a while ago, generating XML from LaTeX sources, never had time to  > check it out more seriously. I should get back to that; as someone else noted, the code is really old, and doesn't support everything in the current LaTeX markup.   -Fred -- Fred L. Drake, Jr.   _______________________________________________ Doc-SIG maillist  -  [hidden email] http://mail.python.org/mailman/listinfo/doc-sig
Open this post in threaded view
|

## Re: Python Tutorial - urllib2

 On 12/22/05, Fred L. Drake, Jr. <[hidden email]> wrote: > On Thursday 22 December 2005 10:47, Martin Blais wrote: >  > Well, be disappointed. >  > It does not currently, and most likely won't. > > Yes and no. > > Docutils provides support for creating new directives ("dot-dot things") and > interpreted text roles (":colon: things").  These would go a long way to > doing what we want, and some experimentation was done toward this > specifically to support documenting Python modules in a style similar to the > standard library documentation.  This is somewhere in the docutils sandbox. It would still not be significantly better than using LaTeX. if it's not better, why change? >  > guessing structure from simple text files.  Even if this is not the >  > case, extending ReST to include keywords for functions, variables, >  > classes, lists of arguments, etc.  would render it into just an >  > equally ugly form of input equivalent to the current LaTeX sources, >  > ... and without the power of expression of TeX macros! > > Whether :function:os.popen() is any uglier than \function{os.popen()} is > largely a matter of what you're used to.  I will note that the LaTeX version > is one character shorter.  :-) It's not just that: the LaTeX macro call allows variations (e.g. optional arguments) that the ReST form does not allow.   It's more powerful. Also, the dot-dot directives impose constraints on the layout contents (has to be indented), which for some uses can make them awkward to use.  The LaTeX model (delimiting with {}, not caring about whitespace) is more flexible. > I think there are appealing qualities to both the TeX macros and the > availability of the docutils document object model.  Both allow for lots of > neat things. Apart from the syntax and a little less markup, I would like to know are those qualities is that thing that are better with ReST than in the LaTeX model.  The only thing I can see is the ease of conversion. Everything else is less convenient. >  > What sucks now is the inflexibliity of the produced document: the >  > tools to convert from the LaTeX sources to other formats are nothing >  > short of wizardry (i.e. LaTeX2html).  What would be great IMO is if we >  > could obtain some kind of meaningful intermediate representation from > > Yes, that is the biggest source of pain. > >  > the source, from which we could then generate various output formats >  > (a bit like how docutils is structured).  I saw some project like that >  > a while ago, generating XML from LaTeX sources, never had time to >  > check it out more seriously. > > I should get back to that; as someone else noted, the code is really old, and > doesn't support everything in the current LaTeX markup. Oh, you did that?  What a wizard :-) _______________________________________________ Doc-SIG maillist  -  [hidden email] http://mail.python.org/mailman/listinfo/doc-sig
Open this post in threaded view
|

## Re: reStructuredText v. LaTeX

 Note the new subject line; it's a not-so-subtle hint that this is a dying thread. :-) On Thursday 22 December 2005 11:53, Martin Blais wrote:  > It would still not be significantly better than using LaTeX.  > if it's not better, why change? I'm not proposing change.  Just noting what's been considered.  (I'm also not ruling out change; my priority on the matter is high-quality documentation, not toolchain.)  > It's not just that: the LaTeX macro call allows variations (e.g.  > optional arguments) that the ReST form does not allow.   It's more  > powerful. Yes, it is.  Sometimes that's good.  > Also, the dot-dot directives impose constraints on the layout contents  > (has to be indented), which for some uses can make them awkward to  > use.  The LaTeX model (delimiting with {}, not caring about  > whitespace) is more flexible. Yes.  I think that's a bigger problem for the Python documentation.  > Apart from the syntax and a little less markup, I would like to know  > are those qualities is that thing that are better with ReST than in  > the LaTeX model.  The only thing I can see is the ease of conversion.  > Everything else is less convenient. The benefit of ReST is the document object model that's available.  Tools can be written to use that to create new features (such as navigational aids).  > Oh, you did that?  What a wizard :-) Either that, or a lunatic.  ;-)   -Fred -- Fred L. Drake, Jr.   _______________________________________________ Doc-SIG maillist  -  [hidden email] http://mail.python.org/mailman/listinfo/doc-sig
Open this post in threaded view
|

## Re: Python Tutorial - urllib2

 In reply to this post by Michael Foord Is there a list somewhere of exactly what it is that would need to be added to ReST in order to support writing Python documentation in ReST? Laura _______________________________________________ Doc-SIG maillist  -  [hidden email] http://mail.python.org/mailman/listinfo/doc-sig
Open this post in threaded view
|

## Re: Python Tutorial - urllib2

 In reply to this post by Fred Drake-3 Fred L. Drake, Jr. wrote: > Whether :function:os.popen() is any uglier than \function{os.popen()} is > largely a matter of what you're used to.  I will note that the LaTeX version > is one character shorter.  :-) javadoc's     {@link os.popen} is even shorter. hmm.  maybe a combination of rest/html/whatever and pythondoc markup would be the ultimate tool for the library reference... _______________________________________________ Doc-SIG maillist  -  [hidden email] http://mail.python.org/mailman/listinfo/doc-sig
Open this post in threaded view
|

## Re: Python Tutorial - urllib2

 On 12/22/05, Fredrik Lundh <[hidden email]> wrote: > Fred L. Drake, Jr. wrote: > > > Whether :function:os.popen() is any uglier than \function{os.popen()} is > > largely a matter of what you're used to.  I will note that the LaTeX version > > is one character shorter.  :-) > > javadoc's > >     {@link os.popen} > > is even shorter. > > hmm.  maybe a combination of rest/html/whatever and pythondoc markup > would be the ultimate tool for the library reference... <* heavy clapping sound of my footsteps while running away screaming in fear *> _______________________________________________ Doc-SIG maillist  -  [hidden email] http://mail.python.org/mailman/listinfo/doc-sig