[Python-Dev] Documentation for ability to execute zipfiles & directories

[Steve Holden]

Paul Moore wrote:
> On 04/03/2008, Nick Coghlan <ncoghlan at gmail.com> wrote:
>> Do we need a new appendix to the tutorial which goes into detail about
>> the CPython interpreter's command line options, environment variables
>> and details on what can be executed?
> 
> There is a Python man page, which covers the command line usage.
> However, it's separate from the documentation, and it isn't bundled
> with the Windows installers - both of which are a real pain (for me,
> at least).
> 
> I'd suggest taking the man page, adding the information about
> executing zip files and directories, and putting the whole lot into
> the formal documentation.
> 
> The big problem is that there isn't really anywhere in the docs which
> is formally CPython-specific. My preference would be to put it in the
> language reference, as a new chapter (between the current chapters 1
> and 2) called "Invoking the Python Interpreter".
> 
> You could also make the manpage a new document, called "Invoking
> Python", but it's a bit small to warrant a ful document.
> 
> An appendix to the Tutorial is OK, I guess, but personally I never
> think of looking at the tutorial (I've been using Python too long to
> feel that I need a tutorial any more, although the quality of my code
> probably says otherwise :-))
> 
While I hesitate to suggest a change of such magnitude, there's 
something to recommend the old IBM mainframe approach of separating out 
"Principles of Operation" (which would be the reference manuals, in 
Python's case the Language and Library refs) from "Users' Guide" which 
contains the practical stuff you need to actually make use of a product.

I've always found it rather counter-intuitive that you have to go to the 
Library Reference manual to find information about Python's built-in 
types, for example. I though the whole point of libraries was that they 
*aren't* built in, and represent baggage that should only be carried on 
necessary trips.

And let's not get started on the import statement. I have just spent 
some time trying to work out how we might get rid of the embarrassing 
"XXX can't be bothered to spell this out right now ..." mess, and have 
come to the conclusion that a thorough review and a complete rewrite is 
the only thing that will do the topic justice.

I can only hope that Brett plans to make a start on this as a part of 
his rework of the import code (and if you're reading, Brett, I'd like to 
help). It doesn't help my motivation that the import mechanism is about 
to change yet again, though I am happy that it will be more regular and 
easier to understand after the next change.

I believe with 3.0 the biggest improvement we could make to the language 
for newcomers would be to reorganize our documentation so that things 
live in the places they belong rather than the place they landed and got 
stuck over time.

Please note this isn't a rant, in the sense that I believe there are 
perfectly comprehensible reasons for how the docs got to be the shape 
they are. But I fear that we are possibly blinded to their inappropriate 
nature by our closeness to and familiarity with them, and I think a 
major effort to revise their structure (and to a lesser degree their 
content) could pay itself back many times over in increased user 
friendliness.

Georg's recent revision of the technology puts us in a better position 
to prepare for this, but it would still be a major project.

regards
  Steve
-- 
Steve Holden        +1 571 484 6266   +1 800 494 3119
Holden Web LLC              http://www.holdenweb.com/