#10961: Pydoc touchups in new 3.2 Web server

[merwok, 2011-01-21 18:46:01]

Some comments.  Haven’t tested the patch yet.

http://codereview.appspot.com/4090042/diff/1/Lib/pydoc.py
File Lib/pydoc.py (right):

http://codereview.appspot.com/4090042/diff/1/Lib/pydoc.py#newcode2507
Lib/pydoc.py:2507: <div style='overflow:auto'>
Does this work fine with common Web browsers, including not-most-recent
versions, and various resolutions?  (“fine” being defined as “not worse than
before the patch”)

http://codereview.appspot.com/4090042/diff/1/Lib/pydoc.py#newcode2591
Lib/pydoc.py:2591: return '<a href="topic?key=%s.html">%s</a>' % (name, name)
I see no reason for polluting the key value with “.html”

http://codereview.appspot.com/4090042/diff/1/Lib/pydoc.py#newcode2713
Lib/pydoc.py:2713: raise TypeError('unknown content type %r' % ([url,
content_type]))
You can remove the extraneous parens around the list.

http://codereview.appspot.com/4090042/diff/1/Lib/test/test_pydoc.py
File Lib/test/test_pydoc.py (right):

http://codereview.appspot.com/4090042/diff/1/Lib/test/test_pydoc.py#newcode431
Lib/test/test_pydoc.py:431: ("", "PyDoc: Index of Modules"),
I’m not sure “PyDoc” is better than “Python”.  What about “Python Doc”?  Very
clear and still short.

[ron3200, 2011-01-21 22:24:38]

http://codereview.appspot.com/4090042/diff/1/Lib/pydoc.py
File Lib/pydoc.py (right):

http://codereview.appspot.com/4090042/diff/1/Lib/pydoc.py#newcode2507
Lib/pydoc.py:2507: <div style='overflow:auto'>
On 2011/01/21 18:46:01, merwok wrote:
> Does this work fine with common Web browsers, including not-most-recent
> versions, and various resolutions?  (“fine” being defined as “not worse than
> before the patch”)

Works with ie, firefox and chromium. If you have something else, please test it,
and let me know.

http://codereview.appspot.com/4090042/diff/1/Lib/pydoc.py#newcode2591
Lib/pydoc.py:2591: return '<a href="topic?key=%s.html">%s</a>' % (name, name)
On 2011/01/21 18:46:01, merwok wrote:
> I see no reason for polluting the key value with “.html”

This is consistent with the other *?key* requests. All of these can be changed
in 3.3 if it's desirable to do so.

http://codereview.appspot.com/4090042/diff/1/Lib/pydoc.py#newcode2713
Lib/pydoc.py:2713: raise TypeError('unknown content type %r' % ([url,
content_type]))
On 2011/01/21 18:46:01, merwok wrote:
> You can remove the extraneous parens around the list.

OK, will do.

http://codereview.appspot.com/4090042/diff/1/Lib/test/test_pydoc.py
File Lib/test/test_pydoc.py (right):

http://codereview.appspot.com/4090042/diff/1/Lib/test/test_pydoc.py#newcode431
Lib/test/test_pydoc.py:431: ("", "PyDoc: Index of Modules"),
On 2011/01/21 18:46:01, merwok wrote:
> I’m not sure “PyDoc” is better than “Python”.  What about “Python Doc”?  Very
> clear and still short.

"Python" and "Python Docs" is too general.  PyDoc is instantly recognizable for
what it is.  If pydoc generated pages are put on line, the "PyDoc" title will be
clearer and help distinguish pydoc pages from other python doc pages.  Keep in
mind pydoc may also be used to generate third party documentation, not just
python documentation.
(This could be done later if it seems questionable.)

[merwok, 2011-01-22 18:29:45]

>> Does this work fine with common Web browsers, including not-most-recent
>> versions, and various resolutions?  (“fine” being defined as “not worse than
>> before the patch”) 
> Works with ie, firefox and chromium. If you have something else, please test
it,
> and let me know.

What versions did you test with?  (I don’t have other browsers.)

>> I see no reason for polluting the key value with “.html” 
> This is consistent with the other *?key* requests. All of these can be changed
> in 3.3 if it's desirable to do so.

Okay.

>> I’m not sure “PyDoc” is better than “Python”.  What about “Python Doc”?  Very
>> clear and still short. 
> "Python" and "Python Docs" is too general.  PyDoc is instantly recognizable
for
> what it is.

If you already know what it is.

> If pydoc generated pages are put on line, the "PyDoc" title will be
> clearer and help distinguish pydoc pages from other python doc pages.  Keep in
> mind pydoc may also be used to generate third party documentation, not just
> python documentation.

Ah, good argument.  +0 for PyDoc then, +0.1 for Pydoc.

[ron3200, 2011-01-22 20:25:45]

On 2011/01/22 18:29:45, merwok wrote:
 
> What versions did you test with?  (I don’t have other browsers.)
Firefox 3.6 and google Chrome(Chromium 8) on Ubuntu, IE6 on Windows XP.

I can also fix the overflow by putting another '<div clear="all">&nbsp;</div>'
at the end of the header.  I think these should be "both" instead of "all". 
"all" works, but "both" seems to be more correct.

What do you suggest?

> Ah, good argument.  +0 for PyDoc then, +0.1 for Pydoc.

Pydoc will work.

[merwok, 2011-01-29 19:12:13]

> Firefox 3.6 and google Chrome(Chromium 8) on Ubuntu, IE6 on Windows XP.
I think Firefox 3.5 is still widely used, maybe older version too.  For Windows,
I guess IE 7 and 8 are used too.  Opera seems to be compliant, so a good test;
on Mac OS X, I understand other browsers are used.

> I can also fix the overflow by putting another '<div clear="all">&nbsp;</div>'
> at the end of the header.  I think these should be "both" instead of "all". 
> "all" works, but "both" seems to be more correct.
I’m afraid my Web skills are a bit rusty; I don’t know anymore the various
quirks of various browsers and required kludges.  If you’re making a patch, you
should do the research :)


> http://codereview.appspot.com/4090042/diff/1/Lib/pydoc.py#newcode2591
> Lib/pydoc.py:2591: return '<a href="topic?key=%s.html">%s</a>' % (name, name)
> On 2011/01/21 18:46:01, merwok wrote:
>> I see no reason for polluting the key value with “.html”
> 
> This is consistent with the other *?key* requests. All of these can be changed
> in 3.3 if it's desirable to do so.

Thinking again about that: The other ?key request you mention have been added in
3.2, right?  If there is no released version with those ?thing=spam.html
request, I repeat my -1 on appending .html.