OpenSource documentation problems

[Bryan Olson]

Fredrik Lundh wrote:
 > Bryan Olson wrote:
 >> >>>>import pydoc
 >> >>>>help is pydoc.help
 >> >
 >> > False
 >>
 >>Say Fredrik, if you're going to proclaim "False"
 >
 > oh, I didn't proclaim anything.  Python 2.4 did.

False. ;)  That was all you.

 > let's see what
 > Python 2.2 has to say about this:
 >
 > $ python2.2
 > Python 2.2.1 (#2, Jul 17 2002, 13:11:01)
 > [GCC 2.96 20000731 (Red Hat Linux 7.1 2.96-98)] on linux2
 > Type "help", "copyright", "credits" or "license" for more information.
 >
 >>>>import pydoc
 >>>>help is pydoc.help
 >
 > 0

You might look at what Mr. Kutching actually wrote:

     help *is* pydoc.help, or at least a trivial wrapper around it

or how I quoted that:

     Since "help *is* pydoc.help, or at least...", the call could

Missed that 'or' did you?

Since 'or' is a Python keyword, let's follow your procedure, and
see if Python (the current version this time) can clue us in as
to what it means.

     >>> help('or')

     Sorry, topic and keyword documentation is not available
     because the Python HTML documentation files could not be
     found.  If you have installed them, please set the
     environment variable PYTHONDOCS to indicate their location.

Darn. I just did the standard Windows install, so I kinda hoped
it would set things up the way it needs them. Oh, well I'll push
on and set the environment variable.

Hmmm... no joy. Same message. What's going on? Well, let's look
up the pydoc module.

     http://docs.python.org/lib/module-pydoc.html

     Module docs for core modules are assumed to reside in
     http://www.python.org/doc/current/lib/. This can be
     overridden by setting the PYTHONDOCS environment variable to
     a different URL or to a local directory containing the
     Library Reference Manual pages.

Odd, it looks like setting the PYTHONDOCS variable isn't even
supposed to be required.

O.K. Next the source: <try ... inspect ... test ...>; Ah,
problem in pydoc.Helper.__init__:

     for dir in [os.environ.get('PYTHONDOCS'),
                 homedir and os.path.join(homedir, 'doc'),
                 os.path.join(execdir, 'doc'),
                 '/usr/doc/python-docs-' + split(sys.version)[0],
                 '/usr/doc/python-' + split(sys.version)[0],
                 '/usr/doc/python-docs-' + sys.version[:3],
                 '/usr/doc/python-' + sys.version[:3],
                 os.path.join(sys.prefix, 
'Resources/English.lproj/Documentation')]:
         if dir and os.path.isdir(os.path.join(dir, 'lib')):
             self.docdir = dir

Obviously that's not going to find the URL.

Still, it looks like it's trying to find the doc/ directory in
the PYTHONDOCS environment variable. I'm not sure why it's
looking for 'lib' as a subdirectory when the pydoc documentation
said to set the environment variable to the directory with the
library doc. (Also, I can't quite fathom why the loop goes on
searching after it finds what it seem to be looking for.)

Next thing to check is whether the doc/ directory has a 'lib/'
subdirectory as the code seems to expect.  Aha: no such
subdirectory. On the Windows install, doc/ contains one file:
'Python24.chm' and no subdirectories. Probably one of those out-
of-sync change issues.

I submitted the bug report at Sourceforge.


 > I do, however, find it a bit funny when someone reads
 >
 >     Type "help", "copyright", "credits" or "license" for more 
information.
 >
 > as
 >
 >     Type "help(help)" /.../
 >
 > and then starts ranting about how "help(help)" isn't quite as helpful
 > as "help" (or "help()", for that matter -- which is what a plain "help"
 > tells you to use).

Is it your baby that's ugly this time? Sorry, but snipping and
pretending people said what they didn't is a low-class move.

 > it's a little like the people who type "google" into the google search
 > field, and then complain that the "I feel lucky" button doesn't seem
 > to work.

Googling Google works fine. Python's doc, not so much.


-- 
--Bryan