[Doc-SIG] Python Tutorial - urllib2

[Michael Foord]

Martin Blais wrote:
> On 12/22/05, Michael Foord <mike at pcblokes.com> 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
>>
>>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 ;-)
> 
> 
> 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).
> 
> 
> 
>>Is reST acceptable for *someone* to add this material - and if so, what
>>should I do about it ?
> 
> 
> Convert it to LaTeX (it's easy) and submit it.
> 

One of the docutils output forms is LayTeX - but the Python
documentation LayTeX is pretty specific ?

Anyway, that *aside* - it looks like Fred has taken on 'TeXifying' the
relevant part I submitted as a patch to the urllib2 docs. (Many thanks).

I'll probably wait and see how that reads and evaluate if a longer entry
in the tutorial is appropriate. If it *is* then I'll customise
appropriately.

If I was to do this - what *is* the appropriate way to submit ? Via
sourceforge ?


> 
> 
>>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.


All the best,

Fuzzyman
http://www.voidspace.org.uk/python/index.shtml

> The LaTeX input format using the macros from the python docs is very
> simple.  Converting your document should be easy.
> 
> cheers,
> 
> 
>