Paul Moore wrote:
On 04/03/2008, Nick Coghlan firstname.lastname@example.org 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.