[New-bugs-announce] [issue1653] a couple of documentation issues

[Joseph Armbruster]

New submission from Joseph Armbruster:

I added an option to msi.py (and a support script) that allows the user
to optionally decompile the python30.chm post installation.  In doing
so, I was testing out help() from the interpreter and stumbled upon a
few things that I think are issues.  One of the ways I experimented, was
by typing the following commands at the interpreter, to see what I could
pull up on the global statement:
   help()
   keywords
   global

I had run into the following issues on my way.  Additional eyes /
insight would definitely be helpful.  Just a couple forewords:
- os.environ.get("PYTHONDOCS") returns 'C:\\Python30\\Doc'
- my version of the installer decompiled the Python30.chm as dictated by
pydoc.  So that, c:\Python30\Doc has folders c-api, data, distutils, etc..

If I missed anything basic with these, my apologies in advanced. 

Issue 1: PYTHONDOCS does not appear to be respected.

  * I generated python-3.0.13865.msi and installed
  * post-install I set PYTHONDOCS to C:\python30\doc
  * I fired up a new command prompt
  * Fire up Python3k interpreter and attempt the help() session listed
above.
  * I had to hack at pydoc.py, since the #windows statement never gets
reached.

        join = os.path.join
        if sys.platform=='win32':           #hack
            self.docdir=join(execdir,'doc') #...
        else:                               #...
            for dir in [os.environ.get('PYTHONDOCS'),
                    homedir and os.path.join(homedir, 'doc'),
                    join(execdir, 'doc'), # for Windows

Issue 2: pydoc.py class Helper member keywords contain several invalid
paths.  For instance:

        'global': ('ref/global', 'NAMESPACES'),

Most of the keywords appear to have the ref/ prefixes.

Issue 3:  formatter.py will throw an exception within push_margin /
pop_margin on the lines where a len(fstack) is attempted.  The two lines
look like this:

        self.writer.new_margin(margin, len(fstack))

I do not have a patch for this, since i'm still wandering about through
the whole installer generation stuffs.  When I get home, I will examine
further.

Thoughts?

----------
components: Documentation, Windows
messages: 58751
nosy: JosephArmbruster, loewis, tiran
severity: normal
status: open
title: a couple of  documentation issues
type: crash
versions: Python 3.0

__________________________________
Tracker <report at bugs.python.org>
<http://bugs.python.org/issue1653>
__________________________________