Steve Holden schrieb:
Paul Moore wrote:
On 04/03/2008, Nick Coghlan
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