DOC BUG: os.chdir() (was Re: Simple Qu: Changing directory)

[Aahz Maruch]

[posted & e-mailed]

In article <14217.63931.75257.566266 at weyr.cnri.reston.va.us>,
Fred L. Drake <fdrake at acm.org> wrote:
>Aahz Maruch writes:
>>
>> I think I understand how it happened: os.getcwd() is (probably
>> rightfully) documented there, so someone thought os.chdir() belonged
>> there, too.  AFAICT, that's the only mistake in that area of the docs,
>> though I could make a case that os.getcwd() should be moved (or at least
>> have a pointer in "F&D").
>
>  Are you saying that (either of) these are in the wrong place?  The
>notion of "current directory" is tied only to the entry in the process 
>table; should it be documented otherwise?
>  The "Process Parameters" section contains functions with provide any
>direct access to the process table entry, both queries and changes, so
>I think it really is the right place for these two functions.
>  I can easily add a textual reference to the right place within the
>"Files and Directories" section, but you'll need to explain very
>clearly why the descriptions should be moved.

It depends how you define "wrong place".  On the one hand, putting
os.chdir() and os.getcwd() in with the process parameters is a
*technically* correct decision, because they are associated with process
information.  OTOH, someone who is not familiar with the way processes
work will *NOT* look in that section; zie would expect to find the
information with all the other functions dealing with files and
directories -- after all, on the surface layer, these two functions deal
with directories, not processes.

Given that one of Python's goals is to be accessible to non-CS geeks,
os.chdir() and os.getcwd() *must* be documented in the section dealing
with files and directories.  As I said originally, I think a reasonable
compromise is to leave the process parameter docs alone and add a
pointer to that area in the files & directories docs (possibly with an
explanation of why they are documented somewhere else).
--
                      --- Aahz (@netcom.com)

Androgynous poly kinky vanilla queer het    <*>      http://www.rahul.net/aahz/
Hugs and backrubs -- I break Rule 6  (if you want to know, do some research)