[Python-Dev] Documentation for ability to execute zipfiles & directories
Georg Brandl
g.brandl at gmx.net
Tue Mar 4 20:21:52 CET 2008
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
More information about the Python-Dev
mailing list