help( dir )
help( dir )
help( dir )
I think Guido and I are pretty far apart on the scope and requirements of this online help thing so I'd like some clarification and opinions from the peanut gallery. Consider these scenarios a) Signature dir([object]) -> list of stringsb) b) Usage hint dir([object]) -> list of stringsb) Return an alphabetized list of names comprising (some of) the attributes of the given object. Without an argument, the names in the current scope are listed. With an instance argument, only the instance attributes are returned. With a class argument, attributes of the base class are not returned. For other types or arguments, this may list members or methods. c) Complete documentation, paged(man-style) dir([object]) -> list of stringsb) Without arguments, return the list of names in the current local symbol table. With an argument, attempts to return a list of valid attribute for that object. This information is gleaned from the object's __dict__, __methods__ and __members__ attributes, if defined. The list is not necessarily complete; e.g., for classes, attributes defined in base classes are not included, and for class instances, methods are not included. The resulting list is sorted alphabetically. For example:
d) Complete documentation in a user-chosen hypertext window
help( dir ) (Netscape or lynx pops up)
I'm thinking that maybe we need two functions: * help * pythondoc pythondoc("dir") would launch the Python documentation for the "dir" command.
Java and Perl people do it regularly. I think that in the greater world of software development, the inline model has won (or is winning) and I don't see a compelling reason to fight the tide. There will always be out-of-line tutorials, discussions, books etc. The canonical module documentation could be inline. That improves the liklihood of it being maintained. The LaTeX documentation is a major bottleneck and moving to XML or SGML will not help. Programmers do not want to learn documentation systems or syntaxes. They want to write code and comments.
No matter what we decide on the issue above, reusing the standard documentation is the only practical way of populating the help system in the short-term. Right now, today, there is a ton of documentation that exists only in LaTeX and HTML. Tons of modules have no docstrings. Keywords have no docstrings. Compare the docstring for urllib.urlretrieve to the HTML documentation. In fact, you've given me a good idea: if the HTML is not available locally, I can access it over the web. Paul Prescod
[Paul Prescod]
Guido's style guide has a lot to say about docstrings, suggesting that they were intended to support two scenarios: #a+#b together (the first line of a multi-line docstring), and #c+#d together (the entire docstring). In this respect I think Guido was (consciously or not) aping elisp's conventions, up to but not including the elisp convention for naming the arguments in the first line of a docstring. The elisp conventions were very successful (simple, and useful in practice), so aping them is a good thing. We've had stalemate ever since: there isn't a single style of writing docstrings in practice because no single docstring processor has been blessed, while no docstring processor can gain momentum before being blessed. Every attempt to date has erred by trying to do too much, thus attracting so much complaint that it can't ever become blessed. The current argument over PEP 233 appears more of the same. The way to break the stalemate is to err on the side of simplicity: just cater to the two obvious (first-line vs whole-string) cases, and for existing docstrings only. HTML vs plain text is fluff. Paging vs non-paging is fluff. Dumping to stdout vs displaying in a browser is fluff. Jumping through hoops for functions and modules whose authors didn't bother to write docstrings is fluff. Etc. People fight over fluff until it fills the air and everyone chokes to death on it <0.9 wink>. Something dirt simple can get blessed, and once *anything* is blessed, a million docstrings will bloom. [Guido]
I'm with Paul on this one: that's what module.__doc__ is for, IMO (Javadoc is great, Eiffel's embedded doc tools are great, Perl POD is great, even REBOL's interactive help is great). All Java, Eiffel, Perl and REBOL have in common that Python lacks is *a* blessed system, no matter how crude. [back to Paul]
Then write tools to automatically create docstrings from the LaTeX and HTML, but *check in* the results (i.e., add the docstrings so created to the codebase), and keep the help system simple.
Keywords have no docstrings.
Neither do integers, but they're obvious too <wink>.
Tim Peters <tim.one@home.com>:
[Paul Prescod]
Keywords have no docstrings.
Neither do integers, but they're obvious too <wink>.
Oh, I don't know, it could be useful.
help(2) The first prime number.
help(2147483647) sys.maxint, the largest Python small integer.
Greg Ewing, Computer Science Dept, +--------------------------------------+ University of Canterbury, | A citizen of NewZealandCorp, a | Christchurch, New Zealand | wholly-owned subsidiary of USA Inc. | greg@cosc.canterbury.ac.nz +--------------------------------------+
I started replying but I think Tim's said it all. Let's do something dead simple. --Guido van Rossum (home page: http://www.python.org/~guido/)
[Paul Prescod]
Guido's style guide has a lot to say about docstrings, suggesting that they were intended to support two scenarios: #a+#b together (the first line of a multi-line docstring), and #c+#d together (the entire docstring). In this respect I think Guido was (consciously or not) aping elisp's conventions, up to but not including the elisp convention for naming the arguments in the first line of a docstring. The elisp conventions were very successful (simple, and useful in practice), so aping them is a good thing. We've had stalemate ever since: there isn't a single style of writing docstrings in practice because no single docstring processor has been blessed, while no docstring processor can gain momentum before being blessed. Every attempt to date has erred by trying to do too much, thus attracting so much complaint that it can't ever become blessed. The current argument over PEP 233 appears more of the same. The way to break the stalemate is to err on the side of simplicity: just cater to the two obvious (first-line vs whole-string) cases, and for existing docstrings only. HTML vs plain text is fluff. Paging vs non-paging is fluff. Dumping to stdout vs displaying in a browser is fluff. Jumping through hoops for functions and modules whose authors didn't bother to write docstrings is fluff. Etc. People fight over fluff until it fills the air and everyone chokes to death on it <0.9 wink>. Something dirt simple can get blessed, and once *anything* is blessed, a million docstrings will bloom. [Guido]
I'm with Paul on this one: that's what module.__doc__ is for, IMO (Javadoc is great, Eiffel's embedded doc tools are great, Perl POD is great, even REBOL's interactive help is great). All Java, Eiffel, Perl and REBOL have in common that Python lacks is *a* blessed system, no matter how crude. [back to Paul]
Then write tools to automatically create docstrings from the LaTeX and HTML, but *check in* the results (i.e., add the docstrings so created to the codebase), and keep the help system simple.
Keywords have no docstrings.
Neither do integers, but they're obvious too <wink>.
Tim Peters <tim.one@home.com>:
[Paul Prescod]
Keywords have no docstrings.
Neither do integers, but they're obvious too <wink>.
Oh, I don't know, it could be useful.
help(2) The first prime number.
help(2147483647) sys.maxint, the largest Python small integer.
Greg Ewing, Computer Science Dept, +--------------------------------------+ University of Canterbury, | A citizen of NewZealandCorp, a | Christchurch, New Zealand | wholly-owned subsidiary of USA Inc. | greg@cosc.canterbury.ac.nz +--------------------------------------+
I started replying but I think Tim's said it all. Let's do something dead simple. --Guido van Rossum (home page: http://www.python.org/~guido/)
participants (4)
-
Greg Ewing -
Guido van Rossum -
Paul Prescod -
Tim Peters