[Python-Dev] Online help scope

[Paul Prescod]

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

>>> help( dir )
dir([object]) -> list of stringsb) 

b) Usage hint

>>> help( dir )
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)

>>> help( dir )
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: 

  >>> import sys
  >>> dir()
  ['sys']
  >>> dir(sys)
  ['argv', 'exit', 'modules', 'path', 'stderr', 'stdin', 'stdout']

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.

> That'S What Some People Think.  I Disagree That It Would Be Either
> Feasible Or A Good Idea To Put All Documentation For A Typical Module
> In Its Doc Strings.

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.

> I said above, and I'll say it again: I think the majority of people
> would prefer to use their standard web browser to read the standard
> docs.  It's not worth the effort to try to make those accessible
> through help().  

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