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

[Georg Brandl]

Steve Holden schrieb:
> 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.

Look no further: http://docs.python.org/dev/using/cmdline.html
There's even more platform-specific stuff at
http://docs.python.org/dev/using/.

>> 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".

The "Using Python" documentation section could be marked as CPython
specific very well.

>> 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.

You speak my mind. For ages I've wanted to put the builtins together with
the language reference into a new document called "Python Core Language".
I've just never had the time to draft a serious proposal.

> 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.

I fully agree.

Georg