classification
Title: pydoc on cgi.escape lacks info that are in www docs
Type: Stage:
Components: Documentation Versions:
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: skip.montanaro Nosy List: georg.brandl, nkour, pterk, skip.montanaro
Priority: normal Keywords:

Created on 2005-07-23 12:33 by nkour, last changed 2005-08-25 21:45 by georg.brandl. This issue is now closed.

Messages (5)
msg25847 - (view) Author: Nikos Kouremenos (nkour) Date: 2005-07-23 12:33
WWW:

escape(  	s[, quote])
    Convert the characters "&", "<" and ">" in string s
to HTML-safe sequences. Use this if you need to display
text that might contain such characters in HTML. If the
optional flag quote is true, the double-quote character
(""") is also translated; this helps for inclusion in
an HTML attribute value, as in <A HREF="...">. If the
value to be quoted might include single- or
double-quote characters, or both, consider using the
quoteattr() function in the xml.sax.saxutils module
instead.


pydoc
cgi.escape = escape(s, quote=None)
    Replace special characters '&', '<' and '>' by SGML
entities.


why? ;(

moreover pydoc doesn't even say what quote is!!
msg25848 - (view) Author: Peter van Kampen (pterk) Date: 2005-07-24 12:55
Logged In: YES 
user_id=174455

The documentation from pydoc is generated from doc-strings
in the python source. Not only does this limit what you can
do with it (hence the need for more elaborate
documentation), it is also reasonable that this
documentation remains terse. You should consider it more as
a quick reference in stead of full-on documentation. 

I have submitted a small patch (1243910) to include a
comment in the doc-string about quote.
msg25849 - (view) Author: Nikos Kouremenos (nkour) Date: 2005-07-24 13:20
Logged In: YES 
user_id=865368

pterk, thank you
msg25850 - (view) Author: Skip Montanaro (skip.montanaro) * (Python committer) Date: 2005-08-02 02:54
Logged In: YES 
user_id=44345

I expanded the cgi.escape docstring a bit (v 1.84).  In general though, the
online doc can't really be a complete substitute for the reference
documentation.  It should be treated more as a hint for usage.
msg25851 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2005-08-25 21:45
Logged In: YES 
user_id=1188172

Closing, then.
To the OP: If you have any more instances where the
docstring misses crucial information, please open a new report.
History
Date User Action Args
2005-07-23 12:33:27nkourcreate