Documentation suggestions
A.M. Kuchling
one big suggestion.
The tutorial seems to be in pretty good shape because Raymond
Hettinger has been keeping it up to date. It doesn't cover
everything, but it's a solid introduction, and if people don't find it
works for them, they have lots of alternative books. No suggestions
here.
There are endless minor bugs in the library reference, but that seems
unavoidable. It documents many different and shifting modules, and
what to document is itself a contentious issue, so I don't think the
stream of small problems will ever cease.
There's another struggle within the LibRef: is it a reference or a
tutorial? Does it list methods in alphabetical order so you can look
them up, or does it list them in a pedagogically useful order? I
think it has to be a reference; if each section were to be a tutorial,
the manual would be huge. Here I think the solution is to encourage
separate tutorials and HOWTOs, and link to them from the LibRef.
The library reference has so many modules that the table of contents
is very large. Again, not really a problem that we can fix; splitting
it up into separate manuals doesn't seem like it would help.
The Extending/Embedding manual isn't great, but only advanced users
will come in contact with it, so I don't think it's a critical factor.
(Michael Hudson's new manual is a promising replacement.)
I suspect the Achilles' heel of the docs is the Language Reference.
Put aside the fact that it's not up to date with new-style classes and
other stuff; that would be fixable with some effort.
To some degree, the guide is trying to be very formal; it's written
like a specification for an implementor, not a document that people
would read through. But there's no other way for people to learn
about all the special object methods like __add__; the tutorial can't
cover them all, and the LibRef doesn't describe them. So the newbie
is stuck.
For example, I noticed this passing reference in Tim Bray's weblog:
http://www.tbray.org/ongoing/When/200x/2005/08/27/Ruby
Based on first impressions and light exposure (a basis that
matters a lot) Ruby seems better-documented and easier to get
into than Python. I've actually written (a little)
production code in Python, but I always had the feeling that
there was lots of stuff going on I didn't understand; a
couple of days in, I think I have a better grasp on what
Ruby's up to, even where I'm not looking.
I don't know exactly what Bray meant, but suspect that a more readable
reference guide would have helped him understand what was going on.
Perhaps we need a friendlier counterpart to the RefGuide, something
like the 20-page introduction to Python at the beginning of Beazley's
Essential Reference:
* go over the statements one-by-one
* go over the basic types and their methods
* go over object semantics
* cover some of the lexical material in chapter 2 of the RefGuide
* overarching principles: go into a fair bit of detail, but
not every corner case; make the text readable, not meticulously
precise.
(I should point out: this suggestion is not entirely different from
some of the suggestions that X*h L** has made. He (?) makes his
suggestions in a venomous style, and with his own eccentric
terminology, but that doesn't mean he's always wrong, e.g. his
complaints about the re module's documentation are well-placed in the
main.)
One problem with such a friendly document: it might make the Ref Guide
even more irrelevant, if we always updated the friendly document
(which is easy) and left the RefGuide to drift even further out of
date (because it's hard to update). I don't know if this is an
argument for not having a friendly guide, or for dumping the RefGuide
entirely.
Dumping the RefGuide means there isn't a more formal-style description
of Python's semantics. I don't know if this matters. In theory, the
implementors of Jython or IronPython could be using the RefGuide to
know what they need to implement, but in practice I suspect
implementors use the test suite and existing library as checks. Maybe
we don't really need a tediously precise description of Python.
What do people think?
--amk
Ben Sizer
> The tutorial seems to be in pretty good shape because Raymond
> Hettinger has been keeping it up to date. It doesn't cover
> everything, but it's a solid introduction, and if people don't find it
> works for them, they have lots of alternative books. No suggestions
> here.
The last time I looked at it, I thought the tutorial was the weakest
part of the documentation, because it assumed you were coming at Python
from another language, and often assumed that language was C. I mean,
the very first line says, "If you ever wrote a large shell script"...
which most people never have. The second page assumes you're using Unix
and throws in Windows as an afterthought. The third page demonstrates
string literals using the term "just as you would do in C". This is a
bit pointless because anyone familiar with C is probably bright enough
to make the connection for themselves, and anyone who isn't will not
appreciate what is being explained. This sort of theme continues
throughout.
Once upon a time I expect nearly all Python programmers came from C,
but today, I doubt that is true, especially since most universities
seem to prefer teaching Java over C++. In short, the tutorial is quite
outdated for today's prospective Python programmers. Admission: I once
offered to help clean it up, but by the time I got a reply from
do...@python.org, I had started a new job and no longer had time. Sorry.
As for the alternative books comment, I think this is very wrong...
people are surely far more likely to buy a comprehensive reference to a
language they're already hooked on by a good tutorial, than they are to
buy an entry-level text for a language they don't quite understand but
which seems to boast good reference material!
> There are endless minor bugs in the library reference, but that seems
> unavoidable. It documents many different and shifting modules, and
> what to document is itself a contentious issue, so I don't think the
> stream of small problems will ever cease.
Make the docs like PHP's docs. Users can post addendums and corrections
to the documentation, then all one of the official maintainers has to
do is fold in those corrections later.
> There's another struggle within the LibRef: is it a reference or a
> tutorial? Does it list methods in alphabetical order so you can look
> them up, or does it list them in a pedagogically useful order? I
> think it has to be a reference; if each section were to be a tutorial,
> the manual would be huge.
I agree: reference foremost. However, all but the most trivial
libraries should have a short example, preferably on the first page of
their docs, so that you can quickly get an idea of whether this does
what you want it to do, and how the code is going to look. Some
libraries don't (ConfigParser comes to mind, Threading is another)
which make using them a bit of a chore to begin with. Again, if web
users could contribute examples as comments on the docs as with PHP,
they can be added in later.
> The library reference has so many modules that the table of contents
> is very large. Again, not really a problem that we can fix; splitting
> it up into separate manuals doesn't seem like it would help.
Personally I'd be happy to see a lot of those modules removed from the
distribution, but I expect few will agree with me. ;)
--
Ben Sizer
Ian Bicking
> Here are some thoughts on reorganizing Python's documentation, with
> one big suggestion.
Thanks for bringing this up...
> There are endless minor bugs in the library reference, but that seems
> unavoidable. It documents many different and shifting modules, and
> what to document is itself a contentious issue, so I don't think the
> stream of small problems will ever cease.
Since the topic of php.net-style comments comes up often, I thought I'd
note I've been working on a comment system:
http://pythonpaste.org/comment/commentary/ -- this might be useful for
collecting and managing small updates and fixes to the documentation.
> There's another struggle within the LibRef: is it a reference or a
> tutorial? Does it list methods in alphabetical order so you can look
> them up, or does it list them in a pedagogically useful order? I
> think it has to be a reference; if each section were to be a tutorial,
> the manual would be huge. Here I think the solution is to encourage
> separate tutorials and HOWTOs, and link to them from the LibRef.
We don't have a clear place to put that material. People's personal
pages leave the potential for material disappearing, and since that
stuff usually doesn't have a clear license we can't necessarily be sure
we can move it elsewhere if the original disappears or becomes out of
date. The Wiki would probably work, and maybe we should just say that
contributions on the Wiki are the preferred form for tutorials and
howtos. Then, of course, we have to link to them. With a commenting
system that can happen more organically.
> The library reference has so many modules that the table of contents
> is very large. Again, not really a problem that we can fix; splitting
> it up into separate manuals doesn't seem like it would help.
There's a lot of dumb modules in there. I'd love if there was a module
index that excluded modules that were not useful. Like, say,
MimeWriter or flp. I think alphabetical or categorized doesn't matter
that much, compared to just a shorter list. Or maybe categorized, but
layed out so that it still all fits on one screen; the main library ToC
is simply too long because it doesn't fit on a screen, but the
categories can still be useful.
> I suspect the Achilles' heel of the docs is the Language Reference.
> Put aside the fact that it's not up to date with new-style classes and
> other stuff; that would be fixable with some effort.
>
> To some degree, the guide is trying to be very formal; it's written
> like a specification for an implementor, not a document that people
> would read through. But there's no other way for people to learn
> about all the special object methods like __add__; the tutorial can't
> cover them all, and the LibRef doesn't describe them. So the newbie
> is stuck.
Definitely; there's a problem for a newcomer, where the "language" is
documented one place (and hard to find), and the standard library
someplace else. As a newcomer it can be hard to know which is which.
Also, things like the functions in builtins are particularly hard to
find IMHO. I usually use pydoc for these things now, but not because I
particularly want to.
> Perhaps we need a friendlier counterpart to the RefGuide, something
> like the 20-page introduction to Python at the beginning of Beazley's
> Essential Reference:
>
> * go over the statements one-by-one
> * go over the basic types and their methods
> * go over object semantics
> * cover some of the lexical material in chapter 2 of the RefGuide
> * overarching principles: go into a fair bit of detail, but
> not every corner case; make the text readable, not meticulously
> precise.
I think that an example-based reference could be more useful than the
current layout. The corner cases *are* important, and it's valuable to
be able to read documentation to fully understand one particular
feature. Like, say, exceptions (which are undercovered right now).
But it can be easier to understand those with a series of examples
meant to demonstrate the behavior, than with a formal description.
> One problem with such a friendly document: it might make the Ref Guide
> even more irrelevant, if we always updated the friendly document
> (which is easy) and left the RefGuide to drift even further out of
> date (because it's hard to update). I don't know if this is an
> argument for not having a friendly guide, or for dumping the RefGuide
> entirely.
>
> Dumping the RefGuide means there isn't a more formal-style description
> of Python's semantics. I don't know if this matters. In theory, the
> implementors of Jython or IronPython could be using the RefGuide to
> know what they need to implement, but in practice I suspect
> implementors use the test suite and existing library as checks. Maybe
> we don't really need a tediously precise description of Python.
A test suite seems far more useful to implementors than any guide,
especially where the accuracy of that guide is not completely assured.
A series of examples seems more concrete than a formal description, and
as such can be not just more helpful, but also a more accurate in how
it transfers knowledge.
sk...@pobox.com
amk> The library reference has so many modules that the table of
amk> contents is very large. Again, not really a problem that we can
amk> fix; splitting it up into separate manuals doesn't seem like it
amk> would help.
I've been meaning to tackle this with a wiki macro. It would remember the
most frequently requested modules (say, the 10-20 most requested) and
display them in a separate alphabetical section ahead of the normal massive
module index. That would then become the module index I bookmark. I just
haven't had the time to implement it.
amk> I suspect the Achilles' heel of the docs is the Language Reference.
amk> Put aside the fact that it's not up to date with new-style classes
amk> and other stuff; that would be fixable with some effort.
On a day-to-day basis I don't use the Language Reference at all. Once every
couple months perhaps. I think most people who have absorbed the basic
syntax and semantics of the language will be in the same boat. It's the
Library Reference that requires the most effort I think.
amk> To some degree, the guide is trying to be very formal; it's written
amk> like a specification for an implementor, not a document that people
amk> would read through. But there's no other way for people to learn
amk> about all the special object methods like __add__; the tutorial
amk> can't cover them all, and the LibRef doesn't describe them. So the
amk> newbie is stuck.
I think if the newbie has outgrown the Tutorial, they should be able to
approach various bits of the Language Reference. Perhaps some bits of its
subject matter should be tutorialized and added to the Tutorial
amk> I don't know exactly what Bray meant, but suspect that a more
amk> readable reference guide would have helped him understand what was
amk> going on.
I think it would be difficult to produce a more readable reference manual
that doesn't introduce some vagueness that will be more difficult for
implementers. The Global Index has this to say about various docs:
Which Manual Target Audience
------------ ---------------
Library Reference keep this under your pillow
Language Reference for language lawyers
Extending and Embedding tutorial for C/C++ programmers
Python/C API reference for C/C++ programmers
I think those comments are about right.
amk> One problem with such a friendly document: it might make the Ref
amk> Guide even more irrelevant, if we always updated the friendly
amk> document (which is easy) and left the RefGuide to drift even
amk> further out of date (because it's hard to update).
Somehow I think Guido would eventually put his (16-ton) foot down. ;-)
amk> Dumping the RefGuide means there isn't a more formal-style
amk> description of Python's semantics. I don't know if this matters.
amk> In theory, the implementors of Jython or IronPython could be using
amk> the RefGuide to know what they need to implement, but in practice I
amk> suspect implementors use the test suite and existing library as
amk> checks. Maybe we don't really need a tediously precise description
amk> of Python.
I think you need something precise, if for no other reason than to
distinguish the language definition from the canonical CPython
implementation (or in the future to arbitrate disagreements betwee CPython,
PyPy, IronPython or some other newcomer).
Maybe we have the cart before the horse w.r.t. documenting changes to the
language. When a new feature goes into the language proper it is generally
discussed on python-dev and written up in a PEP then approved by Guido.
We've generally accepted the PEP as informal documentation, but PEP's aren't
really part of the formal documentation set. Perhaps all we need to do is
be more stringent in requiring Language Reference updates before PEP
acceptance.
Skip
D H
>>There are endless minor bugs in the library reference, but that seems
>>unavoidable. It documents many different and shifting modules, and
>>what to document is itself a contentious issue, so I don't think the
>>stream of small problems will ever cease.
>
>
> Since the topic of php.net-style comments comes up often, I thought I'd
> note I've been working on a comment system:
> http://pythonpaste.org/comment/commentary/ -- this might be useful for
> collecting and managing small updates and fixes to the documentation.
Yes, do it the way php's documentation is done, Xah Lee's recent trolls
aside.
sk...@pobox.com
Ben> Make the docs like PHP's docs.
Easier said than done. There is still - I think - a project in the works to
redo the python.org website, but I have no idea if it means to retain
ht2html+latex2html as the page builders or move to something else. Neither
ht2html nor latex2html support in inline annotation feature. It would need
to be added.
What was the comment here the other day? Python has more web application
frameworks than keywords. PHP only has one. ;-)
Skip
sk...@pobox.com
Ian> A test suite seems far more useful to implementors than any guide,
Of course, test cases can be modified or ignored. I'd agree with you if we
had a test suite that was more strongly cast in stone.
Skip
Fredrik Lundh
> There's another struggle within the LibRef: is it a reference or a
> tutorial? Does it list methods in alphabetical order so you can look
> them up, or does it list them in a pedagogically useful order? I
> think it has to be a reference; if each section were to be a tutorial,
> the manual would be huge. Here I think the solution is to encourage
> separate tutorials and HOWTOs, and link to them from the LibRef.
I've proposed adding support for semi-automatic linking to external
documents, based on a simple tagging model, a couple of times, e.g.
http://mail.python.org/pipermail/python-list/2005-May/280751.html
http://mail.python.org/pipermail/python-list/2005-May/280755.html
http://effbot.org/zone/idea-seealso.htm
but as I mentioned last time
iirc, [I] only got "wikis rulez" and "enough with that comp.sci crap"
responses.
which makes me think that some people still are more interested in com-
plaining than using the stuff that's actually out there...
</F>
Fredrik Lundh
> > There's another struggle within the LibRef: is it a reference or a
> > tutorial? Does it list methods in alphabetical order so you can look
> > them up, or does it list them in a pedagogically useful order? I
> > think it has to be a reference; if each section were to be a tutorial,
> > the manual would be huge. Here I think the solution is to encourage
> > separate tutorials and HOWTOs, and link to them from the LibRef.
>
> We don't have a clear place to put that material. People's personal
> pages leave the potential for material disappearing
so ? this "if we don't own it, we won't even pretend it exists" attitude
of the PSF is beginning to get a bit boring.
(the standard library suffers from the same problem)
</F>
A.M. Kuchling
sk...@pobox.com <sk...@pobox.com> wrote:
> Somehow I think Guido would eventually put his (16-ton) foot down. ;-)
Maybe, but he hasn't put his foot down on new-style classes yet, which
were added in 2.2. It would be all to the good if the BDFL (or the
release manager -- not sure whose decision this is) said that 2.5
can't be released until the docs are up-to-date.
--amk
BartlebyScrivener
Amen. This is why people buy the books: The good ones have lots of
examples. The wizards glance at them in passing and think, "Duh." And
the rest of us (including the intermediate folks, I'll bet) are
grateful for the chance to see a real live example.
rd
Ian Bicking
> I've proposed adding support for semi-automatic linking to external
> documents, based on a simple tagging model, a couple of times, e.g.
>
> http://mail.python.org/pipermail/python-list/2005-May/280751.html
> http://mail.python.org/pipermail/python-list/2005-May/280755.html
> http://effbot.org/zone/idea-seealso.htm
I'm unclear what the workflow is that you are proposing. Given a
<seealso> chunk, how does it get into the documentation? Do you submit
it via the bug tracker, and a committer puts it in the repository, and
the build process puts it into the HTML? Does it get submitted like a
trackback, and the website automatically displays it without human
intervention?
Incidentally, I was noticing on microformats.org that they were talking
about a rev attribute
(http://www.microformats.org/blog/2005/12/01/rel-vs-rev/) which might
work like:
<a href="http://python.org/doc/current/lib/module-atexit.html"
rev="example">
And would be embedded in your page on that module. Then you might
simply notify python.org that the page exists, and it would parse out
the relation to the documentation based on this. Anyway, I was just
reading about rev yesterday, so it came to mind, but it's otherwise an
aside.
Ian Bicking
Well, I ain't the PSF, so my comment here doesn't really indicate
anything with respect to that. There are already links in the
reference document to external documents. But if we start getting a
half dozen links for each page (which is not an unreasonable number)
the maintenance of trimming dead links and pages that are out of date
becomes more significant. And there's no particular coordination, or
any simple feedback process that can be applied to all content.
I don't think there should be any policy discouraging external links;
there's a lot of sources like the Python Cookbook, some free online
books (e.g., Dive Into Python, or Think Like A Computer Scientist), and
stable personal pages that should be linked in . But I do think that
we should encourage some specific process for new or revised
tutorial/howto contributions, like encouraging people put such material
in the wiki.
Ian
Michael Spencer
> Here are some thoughts on reorganizing Python's documentation, with
> one big suggestion.
>
Thanks for raising this topic, and for your on-going efforts in this field.
I use the compiled html help file provided by PythonWin, which includes all the
core documentation. I usually use the index interface, not the table of
contents (the main exception is the LibRef, see below). In this form, the
structure of the documentation is less important than how good the index is.
Unfortunately, the "additional documentation', including, in particular, your re
HowTo is linked, but not indexed and is therefore less accessible.
> The tutorial seems to be in pretty good shape because Raymond
...
Agreed, but as you say below, there may be friendlier forms available for the
first-timer.
...
> There's another struggle within the LibRef: is it a reference or a
> tutorial?
I want it to help answer questions of the form "What's in the the library that
might help me do x?" For this case, some of the current section structure is
not that helpful. "Miscellaneous Services", in particular, gives no clue to
treasures it contains. I would prefer, for example, to see the data structure
modules: collections, heapq, array etc... given their own section.
Documentation/testing, cmd/options might be other candidates to draw together
currently related material more meaningfully.
Does it list methods in alphabetical order so you can look
> them up, or does it list them in a pedagogically useful order? I
> think it has to be a reference;
A reference, yes, but not necessarily alphabetical if another organization is
more communicative. itertools is a good example where alphabetic presentation
makes perfect sense, since the functions are more-or-less peers; the math
functions are usefully classified by topic; textwrap presents most commonly-used
functions first; several modules document classes before convenience functions.
Each of these has its merits, and I don't see a lot of mileage in trying to
standardize them, given how varied modules are. However, whatever the reference
structure, examples add significantly to the value to me.
...
> I suspect the Achilles' heel of the docs is the Language Reference.
> Put aside the fact that it's not up to date with new-style classes and
> other stuff; that would be fixable with some effort.
>
> To some degree, the guide is trying to be very formal; it's written
> like a specification for an implementor, not a document that people
> would read through. But there's no other way for people to learn
> about all the special object methods like __add__; the tutorial can't
> cover them all, and the LibRef doesn't describe them. So the newbie
> is stuck.
I find very little of value to me in the Language Ref. Special methods are the
crucial exception. Perhaps they, together with a description of class semantics
(including metaclasses and descriptors) could be moved to the Built-in types
section of the LibRef, where some related material is already.
I don't know whether the rest of the Language reference is of use to
implementers, but given the proliferation of implementations beyond Cpython
(Jython, IronPython, pypy) I would speculate that a formal specification is now
more important rather than less. However, perhaps it would be possible to
express the specification more succinctly via tests instead of a manual.
...
>
> Perhaps we need a friendlier counterpart to the RefGuide, something
> like the 20-page introduction to Python at the beginning of Beazley's
> Essential Reference:
I did't know this source, but I just skimmed it at
http://www.amazon.com/gp/reader/0735709017/ref=sib_dp_pt/103-1276064-0751851#reader-page
(not sure if this is a session link), and I agree it's a very clear
introduction. Probably better first reading than the existing tutorial.
...
Michael
A.M. Kuchling
> documents, based on a simple tagging model, a couple of times, e.g.
>
> http://mail.python.org/pipermail/python-list/2005-May/280751.html
Very interesting. There could be a manually-maintained list of feed
URLs stored in a file in the Doc/ subdirectory. That way, anyone with
Python SVN access could add a feed, and it's not trapped in some
database on python.org that half the pydotorg group doesn't know
about.
A Makefile target could then update the list of available examples,
and check timestamps to only update the list every 24 hours or so,
avoiding hitting the feeds every time you do "make lib". Fred Drake
would have some "make updatefeed" target for forcing an update when he
makes the release tarballs.
ISTM getting the example into the HTML is the hard bit. Maybe the
simplest solution is to put
% start auto-feeds
% end auto-feeds
into LaTeX source files, and have a script insert the examples between
the markers with the right LaTeX markup.
Hm, but then 'svn diff' will show lots of changes. Maybe an '\input
<modulename>-examples could be used instead, storing the examples in a
separate file. Something like
'\InputFileExists{examples/select.tex}'... Having some examples be
for'atexit' and some specifically for 'atexit.register' seems
difficult with this approach.
Assembling a patch for this would make an interesting evening's
project.
--amk
sk...@pobox.com
>>> A series of examples seems more concrete than a formal description,<<
rd> Amen. This is why people buy the books: The good ones have lots of
rd> examples. The wizards glance at them in passing and think, "Duh."
rd> And the rest of us (including the intermediate folks, I'll bet) are
rd> grateful for the chance to see a real live example.
ISTR that comment was made in reference to the Language Reference, which as
written is intended for "language lawyers". Examples there seem
counterproductive.
Skip
A.M. Kuchling
> stable personal pages that should be linked in . But I do think that
> we should encourage some specific process for new or revised
> tutorial/howto contributions, like encouraging people put such material
> in the wiki.
To this end, I've moved the howtos off their separate SourceForge
project, and into Doc/howto in Python SVN. The sorting howto seemed
small enough and incomplete enough that it would be better as a wiki.
There's another small one, doanddont.tex, that might also be good as a
wiki page. I'm currently not planning to convert any of the larger
documents, such as the curses or regex ones, to wiki format.
--amk
Carl Friedrich Bolz
hum. a test suite like that would have to be constructed very carefully.
The current CPython testsuite tests quite some things that are obviously
implementation details. For example test_itertools.py checks that izip
reuses tuples (which means changing them) when the refcount is 1. This
is something which does not quite work in an implementation using a
different GC :-)
Although on the other hand a short poll revealed that the reference
manual was not considered to be the most useful source among the PyPy
developpers :-)
Cheers,
Carl Friedrich Bolz
Aahz
A.M. Kuchling <a...@amk.ca> wrote:
>
>There's another struggle within the LibRef: is it a reference or a
>tutorial? Does it list methods in alphabetical order so you can look
>them up, or does it list them in a pedagogically useful order? I
>think it has to be a reference; if each section were to be a tutorial,
>the manual would be huge. Here I think the solution is to encourage
>separate tutorials and HOWTOs, and link to them from the LibRef.
Here's a question that kind of gets to the heart of a lot of the
problem: where does ``print`` get documented? If we can come up with a
good process for answering that question, we can probably fix a lot of
other problems. (Note emphasis on the word "process".)
--
Aahz (aa...@pythoncraft.com) <*> http://www.pythoncraft.com/
"Don't listen to schmucks on USENET when making legal decisions. Hire
yourself a competent schmuck." --USENET schmuck (aka Robert Kern)
Steve Holden
I proposed a documentation sprint for PyCon a couple of years ago, but
nobody thought it was important enough to work on. It would be a good
idea next year, too.
regards
Steve
--
Steve Holden +44 150 684 7255 +1 800 494 3119
Holden Web LLC www.holdenweb.com
PyCon TX 2006 www.python.org/pycon/
sk...@pobox.com
>> Of course, test cases can be modified or ignored. I'd agree with you
>> if we had a test suite that was more strongly cast in stone.
Carl> hum. a test suite like that would have to be constructed very
Carl> carefully. The current CPython testsuite tests quite some things
Carl> that are obviously implementation details.
No disagreement there. The current CPython test suite would not cut the
mustard as a test for Python specification compliance.
Skip
Ian Bicking
> Here's a question that kind of gets to the heart of a lot of the
> problem: where does ``print`` get documented? If we can come up with a
> good process for answering that question, we can probably fix a lot of
> other problems. (Note emphasis on the word "process".)
Good point; the language reference and the tutorial is the only place
we currently keep this kind of documentation, and neither provides the
kind of reference that new users need. I'd also note that the
distinction between builtins and syntax isn't meaningful to a new user.
So, for instance, that "exec" and "eval" are documented in very
different places is confusing. And that the "print" statement and the
"write" method are also differently placed.
I think it would be very useful if there was reference (not just
tutorial) documentation for all the syntax, special semantics like
magic methods, and all the functions and objects in builtins. To a new
user these are all the same thing. Even to an experienced users these
are all about the same thing. I don't think such a document would be
all that long or hard to write.
On a usability note, I'd want every name a user might encounter to show
up in an index or table of contents. Basically all the keywords, magic
methods, exceptions, builtin functions, builtin types, and at least
somewhere the methods of builtin types should also be available.
Colin J. Williams
I would vote for the latter.
Colin W.
>
> Cheers,
>
> Carl Friedrich Bolz
>
Colin J. Williams
> A.M. Kuchling wrote:
>
>> Here are some thoughts on reorganizing Python's documentation, with
>> one big suggestion.
>>
>
> Thanks for raising this topic, and for your on-going efforts in this field.
>
> I use the compiled html help file provided by PythonWin, which includes
> all the core documentation. I usually use the index interface, not the
> table of contents (the main exception is the LibRef, see below). In
> this form, the structure of the documentation is less important than how
> good the index is. Unfortunately, the "additional documentation',
> including, in particular, your re HowTo is linked, but not indexed and
> is therefore less accessible.
>
>> The tutorial seems to be in pretty good shape because Raymond
>
> Agreed, but as you say below, there may be friendlier forms available
> for the first-timer.
>
>
>> There's another struggle within the LibRef: is it a reference or a
>> tutorial?
>
>
> I want it to help answer questions of the form "What's in the the
> library that might help me do x?" For this case, some of the current
> section structure is not that helpful. "Miscellaneous Services", in
> particular, gives no clue to treasures it contains. I would prefer, for
> example, to see the data structure modules: collections, heapq, array
> etc... given their own section. Documentation/testing, cmd/options might
> be other candidates to draw together currently related material more
> meaningfully.
>
> Does it list methods in alphabetical order so you can look
>
>> them up, or does it list them in a pedagogically useful order? I
>> think it has to be a reference;
>
>
> A reference, yes, but not necessarily alphabetical if another
> organization is more communicative. itertools is a good example where
> alphabetic presentation makes perfect sense, since the functions are
> more-or-less peers; the math functions are usefully classified by topic;
> textwrap presents most commonly-used functions first; several modules
> document classes before convenience functions. Each of these has its
> merits, and I don't see a lot of mileage in trying to standardize them,
> given how varied modules are. However, whatever the reference
> structure, examples add significantly to the value to me.
>
>
>> I suspect the Achilles' heel of the docs is the Language Reference.
>> Put aside the fact that it's not up to date with new-style classes and
>> other stuff; that would be fixable with some effort.
>>
>
>> To some degree, the guide is trying to be very formal; it's written
>> like a specification for an implementor, not a document that people
>> would read through. But there's no other way for people to learn
>> about all the special object methods like __add__; the tutorial can't
>> cover them all, and the LibRef doesn't describe them. So the newbie
>> is stuck.
>
>
> I find very little of value to me in the Language Ref. Special methods
> are the crucial exception. Perhaps they, together with a description of
> class semantics (including metaclasses and descriptors) could be moved
> to the Built-in types section of the LibRef, where some related material
> is already.
>
> I don't know whether the rest of the Language reference is of use to
> implementers, but given the proliferation of implementations beyond
> Cpython (Jython, IronPython, pypy) I would speculate that a formal
> specification is now more important rather than less. However, perhaps
> it would be possible to express the specification more succinctly via
> tests instead of a manual.
>
>
>>
>> Perhaps we need a friendlier counterpart to the RefGuide, something
>> like the 20-page introduction to Python at the beginning of Beazley's
>> Essential Reference:
>
>
> I did't know this source, but I just skimmed it at
> http://www.amazon.com/gp/reader/0735709017/ref=sib_dp_pt/103-1276064-0751851#reader-page
>
> (not sure if this is a session link), and I agree it's a very clear
> introduction. Probably better first reading than the existing tutorial.
>
>
>
> Michael
>
I like the approach but more would be helpful for a current Python,
especially with respect to types/classes. The book is based on Python 2.1.
Colin W.
sk...@pobox.com
Ian> I think it would be very useful if there was reference (not just
Ian> tutorial) documentation for all the syntax, special semantics like
Ian> magic methods, and all the functions and objects in builtins.
It's pretty common to have a User's Guide as well as a Reference Manual for
many applications. Python has always lacked a User's Guide.
I find it hard to imagine any one person having the time to simply sit down
and bat out such a tome though. I'm partial to using wikis as collaborative
environments. (They more readily admit a group of people to the process
without a formal registration process as would doing the whole thing via
Python's svn repository.) Creating a UsersGuide section of the Python wiki
with reST as the markup might be a good place to work on such a beast with
the goal that it would be a stepping stone to a more standalone document.
Skip
ru...@yahoo.com
Most of the issues regarding issues like where to "print" and
"sys.write", etc results from a wrong assumtion: that the
Lang ref as only for "language lawyers". My sense is the
many people see the Lang ref as a Syntax manual. It doesn't
have to be only that.
My suggestions:
- Keep the basic organization of the Lang Ref the same
but make the entries more accessible to people new to
Python. If is a reference, keep the BNF, details, etc.
Add (brief, terse!) explanatory material where confusion
may occur. Add examples!! (not 1 in 10000 writers can
write clearly enough to do without examples)
- Move Section 2 (builtin types) from the Lib Ref to the
Lang Ref. This section documents data types, builtin
objects, methods, etc. These are all language things,
not library things.
- Distinction between Lib and Lang is easy: if you import
it, it goes in Lib. otherwise it's in Lang. (If it ain't got ints,
string, None, etc, it ain't the python language. It could be
python without pprint.)
- Make an exception for sys (document in both, or maybe
full doc in Lib, enough doc in Lang to support the needed
references in Lang, or maybe all in Lang as an exception?)
If the Lang ref is made a ref for the language, the
Lib ref for the library, make them both accessible, then
they both get used as they should.
To me, the difference between tutorial and reference is:
Organization:
+ Ref: organised depth-first. Each topic is treated fully
(in complete depth) before the next.
+ Tut: organised breadth-first: broad sweeps are made
accross the subject matter, then again a greater death,
then again, etc.
Audience:
+ Ref: material in a section can assume knowlage level
determined by the material. (description of metaclass
stuff can assume user knows basics of class stuff.)
+ Tut: Knowlage level assumed depends on material's
position in the doc (assumes knowlage of previously
presented material.)
Purpose:
+ Tut: Teach the language to a user.
+ Ref: Allow the user to find out information about the language
Style:
+ Tut: Often chatty: "Now that we've seen how iterators
work, lets put that to work"
+ Ref: Terse: "examples:" (but not TOO terse. Idea is to
transfer info to reader as effectively a possible. If it takes
reader (of the assumed level) 5 minutes of thinking to
say "oh, now I see" something's wrong.)
Both tutorial material and reference material are desirable but
if resources allow only one reference is better.
A user guide would be great but just an update of the tutorial
and some reorganiztion and expansion of the two primary
references would improve things a lot in the interim.
(sorry for the rough shape this posting is but I've got to run.)
Terry Hancock
"A.M. Kuchling" <a...@amk.ca> wrote:
> Here are some thoughts on reorganizing Python's
> documentation, with one big suggestion.
> There's another struggle within the LibRef: is it a
> reference or a tutorial?
REFERENCE! :-)
> Does it list methods in
> alphabetical order so you can look them up, or does it
> list them in a pedagogically useful order?
But, I like the *subject* categorization of modules. I would
be disappointed by a flat listing of modules (i.e. only
having the module index). IOW, I'm happy with the current
organizational outline (more or less, I'm sure I would make
small changes if I thought about it long enough).
> The library reference has so many modules that the table
> of contents is very large. Again, not really a problem
> that we can fix; splitting it up into separate manuals
> doesn't seem like it would help.
I would propose adding an alternate top-level page that has
only the major headings, like this:
# Front Matter
# Contents
# 1. Introduction
# 2. Built-In Objects
# 3. Python Runtime Services
# 4. String Services
...
# 22. MS Windows Specific Services
# A. Undocumented Modules
# B. Reporting Bugs
# C. History and License
# Module Index
# Index
# About this document ...
I would imagine this could be automatically generated pretty
easily from what already exists.
My reasoning is that each of the sections has grown due to
the addition of new modules, so that the large-scale
structure is getting hard to see by just looking at the
existing index page (which lists sub-headings under each of
the above).
A possible alternative would be to leave section 2
(built-ins) expanded, as that section is disproportionately
useful.
Using this index page would require you to drill down two
layers to get to individual module documentation (which is
less convenient for frequent users), but it would give a
better synoptic view at the top level (which is desireable
for people new to Python's standard library), making the
structure of the library documentation easier to figure out.
It would also reduce the feeling of information overload
that the new user experiences when encountering that page,
which would reduce "throwing up hands in disgust" and
turning to the mailing list to ask questions that ought to
be RTFM class.
I would prefer this synoptic page to be the default index
page, particularly for the benefit of newbies. But of
course, there's no reason why the existing index couldn't
exist alongside it (needs an extra link in the navbar).
The intermediate pages that the top index would link to
are already in the Python Library Reference, so the only
change is the creation of a top level page with less
information on it.
> I suspect the Achilles' heel of the docs is the Language
> Reference. Put aside the fact that it's not up to date
> with new-style classes and other stuff; that would be
> fixable with some effort.
> Perhaps we need a friendlier counterpart to the RefGuide,
> something like the 20-page introduction to Python at the
> beginning of Beazley's Essential Reference:
>
> * go over the statements one-by-one
> * go over the basic types and their methods
> * go over object semantics
> * cover some of the lexical material in chapter 2
> of the RefGuide * overarching principles: go into
> a fair bit of detail, but
> not every corner case; make the text readable,
> not meticulously precise.
That sounds like a fairly good idea.
Priorities:
"Magic methods"
data model: objects, classes, types, methods, etc.
> One problem with such a friendly document: it might make
> the Ref Guide even more irrelevant, if we always updated
> the friendly document (which is easy) and left the
> RefGuide to drift even further out of date (because it's
> hard to update). I don't know if this is an argument for
> not having a friendly guide, or for dumping the RefGuide
> entirely.
Well, who needs the Reference Guide? (not a rhetorical
question). Maybe it should be optimized for those users.
> Dumping the RefGuide means there isn't a more formal-style
> description of Python's semantics.
I'm not a language implementor, so my vote shouldn't
count that much on that point. OTOH, I *would* be a user of
the "friendlier" Language Reference, so I'm in favor of
that.
Cheers,
Terry
--
Terry Hancock (han...@AnansiSpaceworks.com)
Anansi Spaceworks http://www.AnansiSpaceworks.com
BartlebyScrivener
through the eyes of a curious Windows user who wants to learn
programming and is trying to decide whether to take up Perl, Ruby,
Python, or Visual Basic, let's say.
On the home page, the first link that catches the eye for this user is:
"Beginner's Guide to Programming - <bold> start here if you're new to
programming </bold>." That's me. Click.
Now you are on a page with promising-looking links that all start with
"BeginnersGuide," but the first three are not warm welcomes, they are
housekeeping matters about where you can take courses or how to
download Python for people who don't know whether they want to or not
yet, or there's one that says "examples" which will take you to the
ActiveState Cookbook site so you can get really confused.
Then you hit the link that says "BeginnersGuide/Nonprogrammers" Ah!
That's me. <click>
The first prominent link says: "Python Tutorial" along with a notice at
the top of the page that tells you if you've never programmed before
this is the page for you.
Click on Python Tutorial. Some official business to start off. Then you
see, "Whetting Your Appetite" Ah, I am ready for that. <click>
The first sentence reads:
"If you ever wrote a large shell script, you probably know this
feeling: you'd love to add yet another feature, but it's already so
slow, and so big, and so complicated; or the feature involves a system
call or other function that is only accessible from C ...Usually the
problem at hand isn't serious enough to warrant rewriting the script in
C; perhaps the problem requires variable-length strings or other data
types (like sorted lists of file names) that are easy in the shell but
lots of work to implement in C, or perhaps you're not sufficiently
familiar with C."
Most of the site has been laid out by programmers, for programmers, who
apparently want to keep it that way, based upon what I've seen.
Peter Hansen
> Here's a question that kind of gets to the heart of a lot of the
> problem: where does ``print`` get documented? If we can come up with a
> good process for answering that question, we can probably fix a lot of
> other problems. (Note emphasis on the word "process".)
Sometimes a poor or missing process can be supplemented with improved
technology. If the prospective audience can always answer the question
"where _was_ ``print`` documented?" it would somewhat lessen the
importance of having said good process.
I mention this (admittedly obvious) point only because (a) sometimes
debates about process are fruitless, and (b) having _both_ would fix
even more problems than just having a good process.
-Peter
Paul Rubin
> I proposed a documentation sprint for PyCon a couple of years ago, but
> nobody thought it was important enough to work on. It would be a good
> idea next year, too.
IMO this should definitely be done. That nobody thought docs were
important enough to work on, explains a lot of why the docs have such
problems. Generating better docs and keeping them up to date needs
more than keystrokes--it needs an attitude change. So the first thing
to do is decide for real that good docs are important. Until that's
decided and taken to heart, no amount of piddling around will affect
the problem much.
Rhamphoryncus
> Here are some thoughts on reorganizing Python's documentation, with
> one big suggestion.
Throwing in my own 2¢.. I think the language reference should be
disseminated into the rest of the documentation. Some of the stuff
(operator precedence anybody?) could be done directly, while more
technical aspects could be put in boxes with green[0] backgrounds
saying "technical details". Thinks specific to one implementation
could further be given a blue[0] background.
I don't expect everything to make the transition. Are discussions of
"atoms" and fragments of BNF really better than calling them
expressions and linking to CPython's Grammar file?
--
Adam Olsen, aka Rhamphoryncus
[0] Colors pulled off the top of my head
Fredrik Lundh
> > I've proposed adding support for semi-automatic linking to external
> > documents, based on a simple tagging model, a couple of times, e.g.
> >
> > http://mail.python.org/pipermail/python-list/2005-May/280751.html
> > http://mail.python.org/pipermail/python-list/2005-May/280755.html
> > http://effbot.org/zone/idea-seealso.htm
>
> I'm unclear what the workflow is that you are proposing. Given a
> <seealso> chunk, how does it get into the documentation? Do you submit
> it via the bug tracker, and a committer puts it in the repository, and
> the build process puts it into the HTML?
yep. you can view the seealso file as a collection of all trackbacks you
might have sent.
see andrew's post for an implementation outline.
> Incidentally, I was noticing on microformats.org that they were talking
> about a rev attribute
> (http://www.microformats.org/blog/2005/12/01/rel-vs-rev/) which might
> work like:
>
> <a href="http://python.org/doc/current/lib/module-atexit.html"
> rev="example">
>
> And would be embedded in your page on that module. Then you might
> simply notify python.org that the page exists, and it would parse out
> the relation to the documentation based on this. Anyway, I was just
> reading about rev yesterday, so it came to mind, but it's otherwise an
> aside.
the problem with rev is that it's a 1:1 relation between the two pages.
the seealso file is more about linking your pages to a "virtual target
domain", so that anyone that's interested can build their own service
on top of it. web 2.0, you know...
</F>
Fredrik Lundh
> > I've proposed adding support for semi-automatic linking to external
> > documents, based on a simple tagging model, a couple of times, e.g.
> >
> > http://mail.python.org/pipermail/python-list/2005-May/280751.html
>
> Very interesting. There could be a manually-maintained list of feed
> URLs stored in a file in the Doc/ subdirectory. That way, anyone with
> Python SVN access could add a feed, and it's not trapped in some
> database on python.org that half the pydotorg group doesn't know
> about.
>
> A Makefile target could then update the list of available examples,
> and check timestamps to only update the list every 24 hours or so,
> avoiding hitting the feeds every time you do "make lib". Fred Drake
> would have some "make updatefeed" target for forcing an update when he
> makes the release tarballs.
exactly.
> ISTM getting the example into the HTML is the hard bit. Maybe the
> simplest solution is to put
>
> % start auto-feeds
> % end auto-feeds
>
> into LaTeX source files, and have a script insert the examples between
> the markers with the right LaTeX markup.
or just add a marker (in some for me unknown way), and postprocess
the HTML files. I'm not sure the links does necessarily belong in e.g.
PDF renderings of the documentation, but that's of course up to the
documentation maintainers.
> Hm, but then 'svn diff' will show lots of changes. Maybe an '\input
> <modulename>-examples could be used instead, storing the examples in a
> separate file. Something like
> '\InputFileExists{examples/select.tex}'... Having some examples be
> for'atexit' and some specifically for 'atexit.register' seems
> difficult with this approach.
linking on module level only should definitely be good enough for a first
iteration.
> Assembling a patch for this would make an interesting evening's
> project.
if anyone wants some data to play with, I've posted a simple seealso file
here:
http://effbot.org/librarybook/seealso.xml
</F>
Steve Holden
fair criticism. It would be really nice if a total beginner did actually
see a usable path through the web to their first working Python program.
sk...@pobox.com
Adam> I don't expect everything to make the transition. Are discussions
Adam> of "atoms" and fragments of BNF really better than calling them
Adam> expressions and linking to CPython's Grammar file?
Actually, yes. The actual Grammar file isn't designed for explanation
(mostly it's more complex, but it also has extra productions) and is
somewhat (maybe a lot) different than the BNF in the ref manual.
Skip
Iain King
> is very large. Again, not really a problem that we can fix; splitting
> it up into separate manuals doesn't seem like it would help.
I like the Global Module Index in general - it allows quick access to
exactly what I want.
I would like a minor change to it though - stop words starting with a
given letter rolling over to another column (for example, os.path is at
the foot of one column, while ossaudiodev is at the head of the next),
and provide links to each initial letter at the top of the page.
Iain
sk...@pobox.com
>> The library reference has so many modules that the table of contents
>> is very large. Again, not really a problem that we can fix;
>> splitting it up into separate manuals doesn't seem like it would
>> help.
Iain> I like the Global Module Index in general - it allows quick access
Iain> to exactly what I want. I would like a minor change to it though
Iain> - stop words starting with a given letter rolling over to another
Iain> column (for example, os.path is at the foot of one column, while
Iain> ossaudiodev is at the head of the next), and provide links to each
Iain> initial letter at the top of the page.
I know it's not what you asked for, but give
http://staging.musi-cal.com/modindex/
a try. See if by dynamically migrating the most frequently requested
modules to the front of the section it becomes more manageable.
Skip
Iain King
Well, the point of the GMI is to lookup whatever module you are
currently having to use for the first time (at least it is for me).
Giving easy access to the modules I've already had to look up (because
they are common) doesn't really help - I've already accessed those.
It'll be nice when I have to find some obscure feature I haven't used
in them before, but really, all I'd like is an easy to use index :)
Iain
Adam Olsen
IMO the only people who are going to appreciate BNF used for
explanation are those working on language implementations, and they'll
need to understand the Grammar file anyway. The rest of us need a
simpler explanation involving examples.
Having a large and detailed language specification, although an
admirable ideal, is a waste of time when the target audience is
perhaps a few dozen people. Make it useful for everybody and it'll be
worth maintaining.
sk...@pobox.com
Iain> Well, the point of the GMI is to lookup whatever module you are
Iain> currently having to use for the first time (at least it is for
Iain> me). Giving easy access to the modules I've already had to look
Iain> up (because they are common) doesn't really help - I've already
Iain> accessed those. It'll be nice when I have to find some obscure
Iain> feature I haven't used in them before, but really, all I'd like is
Iain> an easy to use index :)
Reorganizing the global module index isn't all that straightforward. It is
generated by latex2html. To change its layout would probaly require some
additional markup and mods to latex2html (not a pretty piece of code as I
understand it).
OTOH, I find myself returning to the same module docs over and over again to
look up function arguments, regular expression syntax, that sort of thing.
Having to page down past dozens and dozens of modules I don't care about to
click on "sys" or "datetime" motivated me to write my little hack.
Skip
sk...@pobox.com
Adam> Having a large and detailed language specification, although an
Adam> admirable ideal, is a waste of time when the target audience is
Adam> perhaps a few dozen people.
Just because that audience is small doesn't mean they are unimportant.
There are currently four actively maintained/developed implementations of
Python. A common language reference manual is important for them, and
indirectly for the people who use the four implementations.
I'm not trying to discount the value of a good Users Guide.
Skip
Iain King
Argh, you made me look at the html again - at least now I know *why* it
is so disgusting. I understand there's a new version coming out soon,
hopefully in html 4 strict or xhtml. I'm sure at that point it'll be
easier to use. I can wait. :)
Iain
Adam Olsen
> Adam> admirable ideal, is a waste of time when the target audience is
> Adam> perhaps a few dozen people.
>
> Just because that audience is small doesn't mean they are unimportant.
> There are currently four actively maintained/developed implementations of
> Python. A common language reference manual is important for them, and
> indirectly for the people who use the four implementations.
What I meant is that a small audience is not going to draw enough
attention to get the effort it requires. I agree absolutely that the
material it contains is important. That's why I feel it should be
merged with the other documents, to ensure that it really does get
maintained.
A.M. Kuchling
Michael Spencer <ma...@telcopartners.com> wrote:
> not that helpful. "Miscellaneous Services", in particular, gives no clue to
> treasures it contains. I would prefer, for example, to see the data
> structure modules: collections, heapq, array etc... given their own section.
> Documentation/testing, cmd/options might be other candidates to draw together
> currently related material more meaningfully.
You're right; "Miscellaneous Services" is a grab-bag of stuff, and so
are 'Generic OS Services' and 'Optional OS Services'. These chapters
should be rearranged into more, smaller chapters.
A patch for a draft reorganization is at http://www.python.org/sf/1375417
--amk
Steven Bethard
> Iain> I like the Global Module Index in general - it allows quick access
> Iain> to exactly what I want. I would like a minor change to it though
> Iain> - stop words starting with a given letter rolling over to another
> Iain> column (for example, os.path is at the foot of one column, while
> Iain> ossaudiodev is at the head of the next), and provide links to each
> Iain> initial letter at the top of the page.
>
> I know it's not what you asked for, but give
>
> http://staging.musi-cal.com/modindex/
>
> a try. See if by dynamically migrating the most frequently requested
> modules to the front of the section it becomes more manageable.
That's pretty cool. What I don't know is how it would look after
thousands of people using it. I know that I probably only have 10
modules or so that I consistently need to check the docs for. Your hack
above would conveniently place those all at the top if I was the only
user. But are those 10 modules the same 10 modules that other folks
need? I don't know...
Of course, the only way to find out is to try...
STeVe
Rocco Moretti
> There's another struggle within the LibRef: is it a reference or a
> tutorial? Does it list methods in alphabetical order so you can look
> them up, or does it list them in a pedagogically useful order? I
> think it has to be a reference; if each section were to be a tutorial,
> the manual would be huge. Here I think the solution is to encourage
> separate tutorials and HOWTOs, and link to them from the LibRef.
I actually like the conversational, tutorial style the current LibRef
has -- in fact I consider that style one of the Python Docs strengths.
All too often I see manuals that consist of only fuction by fuction &
class by class breakdowns. That's fine if the module is just a
collection of independant functions, but falls short whenever you want
to use multiple functions & classes in a module together. Function by
function documentation tends to ignore the "big picture," how all the
functions & classes work together, and the philosophy behind their use.
*That's* what I feel it is important to document - if I want to know
parameters, return values and side-effects, I'll just look at the doc
strings.
Certainly you could go for the User Manual/Reference Manual dichotomy,
but in my experience, the User Manual tends to get short shrift - the
experts writing it tend to think that it's just for "n00bs", and leave
out the complex and esoteric items, thinking that the Reference Manual
suffices. Unfortunately, the background and philosophy are needed *more*
for the complex/esoteric functions than for the simple ones, merely
because you're less likely to understand them from a "takes a,b,c, sets
the froz flag, and returns x,y,z" type description.
And to expand on what Michael Spencer said, a lot of the time when I'm
digging throught the LibRef, I'm looking for a module that'll help me do
'X'. Most of the "Reference Manuals" I've seen tend to assume you know
what fuction you're looking for, and don't give you any direction in the
forest of function descriptions. With the current tone/level and
categorical grouping of the LibRef, it's easy to browse through and look
for things that might help (at least easier than it would be with, say,
a strict alphabetical list).
Aahz
<sk...@pobox.com> wrote:
>
>OTOH, I find myself returning to the same module docs over and over
>again to look up function arguments, regular expression syntax, that
>sort of thing. Having to page down past dozens and dozens of modules I
>don't care about to click on "sys" or "datetime" motivated me to write
>my little hack.
That's why I use Lynx! ;-) ("/]re" takes me right to regex docs)
--
Aahz (aa...@pythoncraft.com) <*> http://www.pythoncraft.com/
"Don't listen to schmucks on USENET when making legal decisions. Hire
yourself a competent schmuck." --USENET schmuck (aka Robert Kern)
A.M. Kuchling
Fredrik Lundh <fre...@pythonware.com> wrote:
> or just add a marker (in some for me unknown way), and postprocess
> the HTML files. I'm not sure the links does necessarily belong in e.g.
> PDF renderings of the documentation, but that's of course up to the
> documentation maintainers.
I'm just scared of hacking the LaTeX2HTML translator customizations,
and would rather do things to the LaTeX input.
> if anyone wants some data to play with, I've posted a simple seealso file
> here:
Thanks! I've written a little parser and output script; they're in
Python SVN at sandbox/trunk/seealso. (Browseable at
http://svn.python.org/view/sandbox/trunk/seealso/).
With a patch to the Makefile and the module's *.tex file, it's
possible to use these scripts to pull in examples. Modifying all the
*.tex files is tedious, but I suspect we can make it an automatic part
of the seealso environment. I'll talk to Fred about it and begin
assembling a patch.
--amk
Kent Johnson
> BartlebyScrivener wrote:
>> Now you are on a page with promising-looking links that all start with
>> "BeginnersGuide," but the first three are not warm welcomes, they are
>> housekeeping matters about where you can take courses or how to
>> download Python for people who don't know whether they want to or not
>> yet, or there's one that says "examples" which will take you to the
>> ActiveState Cookbook site so you can get really confused.
<snip many more valid criticisms>
> I think the Python community as a whole should take this on board as
> fair criticism. It would be really nice if a total beginner did actually
> see a usable path through the web to their first working Python program.
OK I'll bite. That Beginners Guide page has bugged me for a long time.
It's a wiki page but it is marked as immutable so I can't change it.
Here are some immediate suggestions:
- get rid of the 1-7 list at the top it is very confusing and does not
present information in a useful form or order. All of these links except
the help link appear in the body text in more useful form.
- Change the sentence "Read BeginnersGuide/Overview to learn the key
points." to "Read BeginnersGuide/Overview to learn what makes Python
special." Or maybe get rid of it completely - I'm not sure evangelism
belongs on this page.
- Add a sentence at the end of the paragraph that starts, "Once you've
read a tutorial" that says, "Many other resources are listed in
BeginnersGuide/Help."
On the BeginnersGuide/NonProgrammers page, I agree, Guido's tutorial
probably shouldn't be listed first even with the disclaimer. It goes way
to fast for a beginner. Alan Gauld's tutorial is very popular on the
tutor list, so is A Byte of Python (which is not listed on the
NonProgrammers page). I would list them first. Or maybe take a vote on
the tutor list for favorite beginner's tutorial.
That should help a little, maybe we won't confuse the newbies before
they even get to an interpreter prompt.
Kent
PS I am aware of the usual SF bug report procedure for docs, does it
apply to these pages? I don't know, they don't have the usual "About
this document" link at the bottom. I'm happy to submit a patch if that
will help. Otherwise I'm not sure what "the Python community as a whole
[taking] this on board" should look like.
sk...@pobox.com
>> http://staging.musi-cal.com/modindex/
Steven> What I don't know is how it would look after thousands of people
Steven> using it. I know that I probably only have 10 modules or so
Steven> that I consistently need to check the docs for. Your hack above
Steven> would conveniently place those all at the top if I was the only
Steven> user. But are those 10 modules the same 10 modules that other
Steven> folks need? I don't know...
Is suspect most people need help with a fairly common module subset on a
regular basis. This won't provide a cache with a 100% hit rate, but the
cost of a cache miss isn't all that high. Also, you might discover some
useful modules you hadn't used before simply because they are frequently
referenced.
Skip
BartlebyScrivener
people know who he is and are able to understand him.
> Alan Gauld's tutorial is very popular on the
> tutor list, so is A Byte of Python (which is not listed on the
> NonProgrammers page). I would list them first. Or maybe take a vote on
> the tutor list for favorite beginner's tutorial.
And perhaps How To Think Like A Computer Scientist. Then maybe
introduce them with a single sentence like:
"Python is so easy to learn and immediately useful that many popular
tutorials use Python to teach computer programming."
sk...@pobox.com
Kent> OK I'll bite. That Beginners Guide page has bugged me for a long
Kent> time. It's a wiki page but it is marked as immutable so I can't
Kent> change it.
That's because for some reason it is one of the top two or three most
frequently defaced pages on the wiki. We got tired of having to revert
changes to it every day or two. I'll take a look at incorporating your
suggestions.
Skip
BartlebyScrivener
"Many popular tutorials use Python to teach computer programming,
because Python is free, easy to learn, immediately useful, and fun!"
Mark Jackson
Or you can just look up the module you need to write a 'bot to
constantly look up the docs for your favorite 10 modules. . . .
--
Mark Jackson - http://www.alumni.caltech.edu/~mjackson
If it made sense, that would be a very powerful idea.
- Bruce Eric Kaplan
A.M. Kuchling
sk...@pobox.com <sk...@pobox.com> wrote:
> Just because that audience is small doesn't mean they are unimportant.
> There are currently four actively maintained/developed implementations of
> Python. A common language reference manual is important for them, and
> indirectly for the people who use the four implementations.
They're not unimportant, but I don't think the reference manual *is*
important to them because they've gotten this far with an outdated
one; the code may be resource enough. This is why I think that the
effort expended to update a document aimed at them might be better
spent on something more widely useful.
I remembered another problem from the weekend with documenting
new-style classes. It seemed reasonable to begin with PEP 252, and
see if any bits of the PEP can be migrated into the RefGuide, but then
I found this comment in the abstract:
[Editor's note: the ideas described in this PEP have been
incorporated into Python. The PEP no longer accurately
describes the implementation.]
So now we're *really* stuck. The RefGuide doesn't describe the rules;
the PEP no longer describes them either; and probably only Guido can
write the new text for the RefGuide. (Or are the semantics the same
and only some trivial details are different?)
--amk
Michael Spencer
I experimented with some more re-organization, but I don't see away to attach
the resulting file in the SF comments, so I'll post it here instead.
Michael
% experimental re-organization of lib.tex,
% from http://www.python.org/sf/1375417
\tableofcontents
% Chapter title:
\input{libintro} % Introduction
% =============
% BUILT-INs
% =============
\input{libobjs} % Built-in Types, Exceptions and Functions
\input{libfuncs}
\input{libstdtypes}
\input{libexcs}
\input{libconsts}
% =============
% BASIC/GENERAL-PURPOSE OBJECTS
% =============
% General object services
\input{libtypes}
\input{libnew}
\input{libweakref}
\input{libcopy}
\input{libpprint}
\input{librepr}
% Strings
\input{libstrings} % String Services
\input{libstring}
\input{libre}
\input{libreconvert}
\input{libstruct} % also/better in File Formats?
\input{libdifflib}
\input{libfpformat}
\input{libstringio}
\input{libtextwrap}
\input{libcodecs}
\input{libunicodedata}
\input{libstringprep}
% Data types and structures
%\input{libdata} % Data types and structures
\input{libdatetime}
\input{libcalendar}
\input{libcollections}
\input{libheapq}
\input{libarray}
\input{libsets}
\input{libsched}
\input{libmutex}
\input{libqueue}
\input{libuserdict} % From runtime. What happened to UserList and UserString?
% Numeric/Mathematical modules
\input{libdecimal}
\input{libmath}
\input{libcmath}
\input{librandom}
\input{libbisect} % is this needed here - more useful in Data types, like heapq?
% Functions, Functional, Generators and Iterators
\input{libitertools}
\input{libfunctional}
\input{liboperator} % from runtime - better with itertools and functional
%\input{libmisc} % Miscellaneous Services
% =============
% DATA FORMATS
% =============
% % File formats
\input{libcfgparser}
\input{libnetrc}
\input{librobotparser}
\input{libcsv}
\input{libstruct} % and in string?
% Big move - include all the markup and internet formats here
% MIME & email stuff
\input{email}
\input{libmailcap}
\input{libmailbox}
\input{libmhlib}
\input{libmimetools}
\input{libmimetypes}
\input{libmimewriter}
\input{libmimify}
\input{libmultifile}
\input{librfc822}
% encoding stuff
\input{libbase64}
\input{libbinascii}
\input{libbinhex}
\input{libquopri}
\input{libuu}
\input{libxdrlib}
\input{markup} % Structured Markup Processing Tools
\input{libhtmlparser}
\input{libsgmllib}
\input{libhtmllib}
\input{libpyexpat}
\input{xmldom}
\input{xmldomminidom}
\input{xmldompulldom}
\input{xmlsax}
\input{xmlsaxhandler}
\input{xmlsaxutils}
\input{xmlsaxreader}
% \input{libxmllib}
\input{libcrypto} % Cryptographic Services
\input{libhmac}
\input{libhashlib}
\input{libmd5}
\input{libsha}
% =============
% FILE & DATABASE STORAGE
% =============
\input{liballos} % File-system services (XXX change header)
\input{libos}
\input{libposixpath} % os.path
\input{libfileinput}
\input{libstat}
\input{libstatvfs}
\input{libfilecmp}
\input{libtempfile}
\input{libglob}
\input{libfnmatch}
\input{liblinecache}
\input{libshutil}
\input{libdircache}
% % Data compression and archiving
\input{libzlib}
\input{libgzip}
\input{libbz2}
\input{libzipfile}
\input{libtarfile}
%\input{libpersistence} % Persistent storage
\input{libpickle}
\input{libcopyreg} % really copy_reg % from runtime...
\input{libshelve}
\input{libmarshal}
\input{libanydbm}
\input{libwhichdb}
\input{libdbm}
\input{libgdbm}
\input{libdbhash}
\input{libbsddb}
\input{libdumbdbm}
% =============
% OS
% =============
\input{liballos} % Generic Operating System Services
\input{libtime}
\input{libgetpass}
\input{libcurses}
\input{libascii} % curses.ascii
\input{libcursespanel}
\input{libplatform}
\input{liberrno}
% % Interprocess communication/networking
\input{libsubprocess}
\input{libsocket}
\input{libsignal}
\input{libpopen2}
\input{libasyncore}
\input{libasynchat}
\input{libsomeos} % Optional Operating System Services
\input{libselect}
\input{libthread}
\input{libthreading}
\input{libdummythread}
\input{libdummythreading}
\input{libmmap}
\input{libreadline}
\input{librlcompleter}
\input{libunix} % UNIX Specific Services
\input{libposix}
\input{libpwd}
\input{libspwd}
\input{libgrp}
\input{libcrypt}
\input{libdl}
\input{libtermios}
\input{libtty}
\input{libpty}
\input{libfcntl}
\input{libpipes}
\input{libposixfile}
\input{libresource}
\input{libnis}
\input{libsyslog}
\input{libcommands}
% =============
% NETWORK & COMMUNICATIONS
% =============
\input{internet} % Internet Protocols
\input{libwebbrowser}
\input{libcgi}
\input{libcgitb}
\input{liburllib}
\input{liburllib2}
\input{libhttplib}
\input{libftplib}
\input{libgopherlib}
\input{libpoplib}
\input{libimaplib}
\input{libnntplib}
\input{libsmtplib}
\input{libsmtpd}
\input{libtelnetlib}
\input{liburlparse}
\input{libsocksvr}
\input{libbasehttp}
\input{libsimplehttp}
\input{libcgihttp}
\input{libcookielib}
\input{libcookie}
\input{libxmlrpclib}
\input{libsimplexmlrpc}
\input{libdocxmlrpc}
\input{netdata} % Internet Data Handling
\input{libformatter}
% =============
% MULTIMEDIA
% =============
\input{libmm} % Multimedia Services
\input{libaudioop}
\input{libimageop}
\input{libaifc}
\input{libsunau}
\input{libwave}
\input{libchunk}
\input{libcolorsys}
\input{librgbimg}
\input{libimghdr}
\input{libsndhdr}
\input{libossaudiodev}
% =============
% PROGRAM FRAMEWORKS/OPTIONS/GUI
% =============
\input{libgetopt}
\input{liboptparse}
\input{libcmd}
\input{libshlex}
\input{liblogging}
\input{tkinter}
% % Internationalization
\input{libgettext}
% =============
% DEVELOPMENT TOOLS
% =============
% % Software development support
\input{libpydoc}
\input{libdoctest}
\input{libunittest}
\input{libtest}
\input{libpdb} % The Python Debugger
\input{libprofile} % The Python Profiler
\input{libhotshot} % New profiler
\input{libtimeit}
% =============
% PYTHON ENGINE
% =============
\input{libpython} % Python Runtime Services
% Runtime services
\input{libsys}
\input{libbltin} % really __builtin__
\input{libmain} % really __main__
\input{libtraceback}
\input{libinspect}
\input{libgc}
% Custom interpreter
\input{libcode}
\input{libcodeop}
\input{librestricted} % Restricted Execution
\input{librexec}
\input{libbastion}
% Runtime environment
\input{libfpectl}
\input{libatexit}
\input{libsite}
\input{libuser}
\input{libfuture} % really __future__
\input{libwarnings}
\input{liblocale} % also in Internationalization
% modules
\input{libimp}
\input{libzipimport}
\input{libpkgutil}
\input{libmodulefinder}
% =============
% PYTHON LANGUAGE & COMPILER
% =============
\input{language} % Python Language Services
\input{libparser}
\input{libsymbol}
\input{libtoken}
\input{libkeyword}
\input{libtokenize}
\input{libtabnanny}
\input{libpyclbr}
\input{libpycompile} % really py_compile
\input{libcompileall}
\input{libdis}
\input{libpickletools}
\input{distutils}
\input{compiler} % compiler package
% =============
% OTHER PLATFORM-SPECIFIC STUFF
% =============
%\input{libamoeba} % AMOEBA ONLY
%\input{libstdwin} % STDWIN ONLY
\input{libsgi} % SGI IRIX ONLY
\input{libal}
\input{libcd}
\input{libfl}
\input{libfm}
\input{libgl}
\input{libimgfile}
\input{libjpeg}
%\input{libpanel}
\input{libsun} % SUNOS ONLY
\input{libsunaudio}
\input{windows} % MS Windows ONLY
\input{libmsvcrt}
\input{libwinreg}
\input{libwinsound}
\appendix
\input{libundoc}
%\chapter{Obsolete Modules}
%\input{libcmpcache}
%\input{libcmp}
%\input{libni}
%\input{libregex}
%\input{libregsub}
\chapter{Reporting Bugs}
\input{reportingbugs}
\chapter{History and License}
\input{license}
Aahz
A.M. Kuchling <a...@amk.ca> wrote:
>
>So now we're *really* stuck. The RefGuide doesn't describe the rules;
>the PEP no longer describes them either; and probably only Guido can
>write the new text for the RefGuide. (Or are the semantics the same
>and only some trivial details are different?)
Raymond Hettinger (and/or maybe one of the metaclass wizards) can
probably also write it, with Guido editing after. That might produce
even more accuracy in the end.
ru...@yahoo.com
"Michael Spencer" <ma...@telcopartners.com> wrote:
> A.M. Kuchling wrote:
> > On Tue, 06 Dec 2005 10:29:33 -0800,
> > Michael Spencer <ma...@telcopartners.com> wrote:
> >> not that helpful. "Miscellaneous Services", in particular, gives no clue to
> >> treasures it contains. I would prefer, for example, to see the data
> >> structure modules: collections, heapq, array etc... given their own section.
> >> Documentation/testing, cmd/options might be other candidates to draw together
> >> currently related material more meaningfully.
> >
> > You're right; "Miscellaneous Services" is a grab-bag of stuff, and so
> > are 'Generic OS Services' and 'Optional OS Services'. These chapters
> > should be rearranged into more, smaller chapters.
> >
> > A patch for a draft reorganization is at http://www.python.org/sf/1375417
> >
> > --amk
> Thanks! That looks like a good start.
>
> I experimented with some more re-organization, but I don't see away to attach
> the resulting file in the SF comments, so I'll post it here instead.
>
> Michael
> % =============
> % BUILT-INs
> % =============
>
> \input{libobjs} % Built-in Types, Exceptions and Functions
> \input{libfuncs}
> \input{libstdtypes}
> \input{libexcs}
> \input{libconsts}
Is this intended as a standalone short term bandaid, or as
part of a more serious attempt to fix the doc problems?
The builtins section should be moved to the language
reference manual. The material it documents is part
of the language definition, not part of an add-on library.
Worse, if it stays in the library reference manual, it will
make it very difficult to fix the language reference manual,
since core parts of the discussion of the language need
to reference these builtins. Rather like a book on the
history of World War 2 saying "For information on the
D-day invasion, please refer to ...". Workable perhaps
but not likely to impress anyone with the competance
of its authors.
There is long history of established prior art when it
comes to documenting computer languages. Is it
really necessary for Python to blaze new ground here?
ru...@yahoo.com
A language reference manual and a language specification
are two different things, and the existence of bnf/grammar info
in a language reference manual need to turn it into some
inpenaterable ISO-spec like document.
I know that I sometimes want to know if some unusual syntax
is legal or not, particularly when learning a language. The
bnf/grammar stuff is relatively small and if sections are
organised consistently, easily skipped over by readers with
no interest it it.
Fredrik Lundh
> The builtins section should be moved to the language
> reference manual. The material it documents is part
> of the language definition, not part of an add-on library.
the standard library is not an add-on. you're confused.
</F>
ru...@yahoo.com
I think this is pretty cool. But...
Is this only for the online docs? Would documentaion shipped with
Python exclude this, or have a frozen version of it?
My experience with other machine systems that try to guess what
I will want, is they usually get it wrong, and become more of a burdon
than a help.
Often what I like best is consistency. I think I'd find it irritating
if
I got used to clicking on one of the frequently used links, and then
discovered it had been bumped. Even it's changing position might
be irritating.
ru...@yahoo.com
Your probably talking about internal implementation.
I'm talking about user's perception. A "python" that
had a different set of builtins would not be python.
That makes it more useful to view it as part of the
language, not a library even if it happens to be
implemented that way.
Ian Bicking
I think the point is that there is the core language, and from a user's
perspective builtins and statements and syntax are all the same thing.
When you import a module, it's more-or-less obvious where you find
information about the module (the module index, of course). But
"print", "sorted", and "list" are all equally "built in" in the mind of
a new user. And frankly, though with experience I understand the
categorization, I don't find it particularly compelling.
A new and improved language reference document should deal with all of
these together, I think.
Ian
Fredrik Lundh
> Fredrik Lundh wrote:
> > ru...@yahoo.com wrote:
> >
> > > The builtins section should be moved to the language
> > > reference manual. The material it documents is part
> > > of the language definition, not part of an add-on library.
> >
> > the standard library is not an add-on. you're confused.
>
> Your probably talking about internal implementation.
> I'm talking about user's perception. A "python" that
> had a different set of builtins would not be python.
> That makes it more useful to view it as part of the
> language, not a library even if it happens to be
> implemented that way.
no, I'm talking about how things are used, not how things
happen to look inside your head.
you seem to think that everything that lives in the __builtin__
module are fundamental parts of the language, but that any-
thing that can be explicitly imported into a user module is an
"add-on".
that's not how things work. if you want to move "fundamental
parts" to a different document, you have to move a lot more
than just the functions in the __builtin__ module.
</F>
sk...@pobox.com
>> http://staging.musi-cal.com/modindex/
rurpy> Is this only for the online docs?
Yes. I don't see that it would be helpful for static docs. Presumably they
will get reorganized. I want something for the many times I return to the
global module index looking for help with a particular module.
rurpy> My experience with other machine systems that try to guess what I
rurpy> will want, is they usually get it wrong, and become more of a
rurpy> burdon than a help.
This isn't guessing. It's more like voting (or like rating systems such as
the Internet Movie Database).
S
Fredrik Lundh
> > the standard library is not an add-on. you're confused.
>
> I think the point is that there is the core language, and from a user's
> perspective builtins and statements and syntax are all the same thing.
> When you import a module, it's more-or-less obvious where you find
> information about the module (the module index, of course). But
> "print", "sorted", and "list" are all equally "built in" in the mind of
> a new user.
so are many standard modules (don't tell me that any real user will
learn all the builtins before she writes her first import statement...)
> A new and improved language reference document should deal with all of
> these together, I think.
wasn't the idea to get rid of the language reference altogether, and
replace it with a better introduction ?
</F>
sk...@pobox.com
Ian> I think the point is that there is the core language, and from a
Ian> user's perspective builtins and statements and syntax are all the
Ian> same thing. When you import a module, it's more-or-less obvious
Ian> where you find information about the module (the module index, of
Ian> course).
I suspect I'd have a harder time living without the sys module than with
many of the builtins. Then there's os, re, math, ... Some modules, like
thread and sys, have to be linked into the interpreter. Are they "core" or
"add on"? Once you start migrating stuff from the "add on" manual (Library
Reference) to the "core" manual (Language Reference), where do you stop?
Skip
ru...@yahoo.com
I think a natural dividing line is "import". If you import it, it
is in the Library refrence. If you don't, it is in the Language
reference. The exception is sys, which could be
- documented fully in the Language ref. as an exception.
- documented as necessary in the Languge ref, and fully in
the Library ref.
Thread would be documented in the Library reference because
- the fact that is is linked in the interpreter is invisable to me
(the user).
- I have to do "import thread" to use it.
Sorry about the term "add-on". I know that is the wrong
word, but couldn't think of anything better.
ru...@yahoo.com
Fredrik Lundh wrote:
> Ian Bicking wrote:
>
> > > the standard library is not an add-on. you're confused.
> >
> > I think the point is that there is the core language, and from a user's
> > perspective builtins and statements and syntax are all the same thing.
> > When you import a module, it's more-or-less obvious where you find
> > information about the module (the module index, of course). But
> > "print", "sorted", and "list" are all equally "built in" in the mind of
> > a new user.
>
> so are many standard modules (don't tell me that any real user will
> learn all the builtins before she writes her first import statement...)
If this is a reference manual (as opposed by a tutorial)
then the order information is presented in is not guided
by a user's order of use. It just needs to be presented
coherently (so you can find what they want quickly (with
the relevant material all together), and hopefuly in an
order that minimizes forward references (so it can be
read sequentially if desired). This order had been
worked out by many previous language manuals and
I think is equally usable for Python.
> > A new and improved language reference document should deal with all of
> > these together, I think.
>
> wasn't the idea to get rid of the language reference altogether, and
> replace it with a better introduction ?
Can an introduction provide the information the language
reference provides (or maybe I am misunderstanding what
you mean by introduction.)
Steven Bethard
> In article <x9udndsHOJA...@speakeasy.net>,
> A.M. Kuchling <a...@amk.ca> wrote:
>
>>So now we're *really* stuck. The RefGuide doesn't describe the rules;
>>the PEP no longer describes them either; and probably only Guido can
>>write the new text for the RefGuide. (Or are the semantics the same
>>and only some trivial details are different?)
>
> Raymond Hettinger (and/or maybe one of the metaclass wizards) can
> probably also write it, with Guido editing after. That might produce
> even more accuracy in the end.
I'm not a metaclass wizard, but I have submitted a few doc patches
trying to address some of the inaccuracies in the description of
new-style classes and related matters:
http://www.python.org/sf/1123716
http://www.python.org/sf/1163367
The problem is that they don't seem to get accepted (even when
accompanied by positive comments). And unfortunately, I don't currently
have time to do the 5 reviews for 1 deal offered by some of the
python-dev folks.
STeVe
Fredrik Lundh
> > wasn't the idea to get rid of the language reference altogether, and
> > replace it with a better introduction ?
>
> Can an introduction provide the information the language
> reference provides (or maybe I am misunderstanding what
> you mean by introduction.)
from the post that opened this thread:
"Perhaps we need a friendlier counterpart to the RefGuide, something
like the 20-page introduction to Python at the beginning of Beazley's
Essential Reference:
* go over the statements one-by-one
* go over the basic types and their methods
* go over object semantics
* cover some of the lexical material in chapter 2 of the RefGuide
* overarching principles: go into a fair bit of detail, but
not every corner case; make the text readable, not meticulously
precise."
</F>
Bengt Richter
I think discussion of python reference materials is not complete without
mentioning the quick-reference at (e.g. for python 2.4)
http://rgruet.free.fr/PQR24/PQR2.4.html
which BTW is accessible from the python.org docs page (http://www.python.org/doc/)
via the "Quick Reference Guide (off-site)" link to the quikc ref home page (other goodies too).
http://rgruet.free.fr/#QuickRef
IMO the first link above (or for whatever current version) would be nice to find
on the documentation sidebar of python's home page (http://www.python.org/),
maybe right below the "Beginner's Guide" link.
(it's gotten nicer, so maybe I'll snag me a fresh offline-usable copy, and
update my Start>Help menu ;-)
Regards,
Bengt Richter
Ben Sizer
> s...@pobox.com wrote:
> > I suspect I'd have a harder time living without the sys module than with
> > many of the builtins. Then there's os, re, math, ... Some modules, like
> > thread and sys, have to be linked into the interpreter. Are they "core" or
> > "add on"? Once you start migrating stuff from the "add on" manual (Library
> > Reference) to the "core" manual (Language Reference), where do you stop?
>
> I think a natural dividing line is "import". If you import it, it
> is in the Library refrence.
Exactly. I'm surprised this is even open to debate. Any built-in which
will work without an import statement - no matter how it's implemented
- should be documented as if it was part of the core language. And
anything you have to explicitly ask for using import, should be in the
library reference under the name of the module or package you're
importing. In terms of knowing where to look for information on a
feature, this is the most sensible approach. In no other language would
I look to the library reference for something which does not appear on
the surface to come from a library.
As an aside, personally I rarely touch the sys module. I use re,
random, threading, and even xml.dom.minidom more than sys.
--
Ben Sizer
A.M. Kuchling
Iain King <iain...@gmail.com> wrote:
> Argh, you made me look at the html again - at least now I know *why* it
> is so disgusting. I understand there's a new version coming out soon,
> hopefully in html 4 strict or xhtml. I'm sure at that point it'll be
> easier to use. I can wait. :)
A new version of LaTeX2HTML, you mean? Can you provide a pointer?
--amk
A.M. Kuchling
Kent Johnson <ke...@kentsjohnson.com> wrote:
> OK I'll bite. That Beginners Guide page has bugged me for a long time.
> It's a wiki page but it is marked as immutable so I can't change it.
> Here are some immediate suggestions:
Good suggestions; thanks! I've applied most of them.
> - Change the sentence "Read BeginnersGuide/Overview to learn the key
> points." to "Read BeginnersGuide/Overview to learn what makes Python
> special." Or maybe get rid of it completely - I'm not sure evangelism
> belongs on this page.
Yes, it does; fairly often the webmaster alias receives e-mails that
ask "so what is Python?"
--amk
A.M. Kuchling
Michael Spencer <ma...@telcopartners.com> wrote:
> I experimented with some more re-organization, but I don't see away
> to attach the resulting file in the SF comments, so I'll post it
> here instead.
I've attached your file to the patch. Some comments:
> \input{libstruct} % also/better in File Formats?
Struct operates on string input and produces string output, so I think
it belongs in the string chapter where you've placed it. We need to
add more cross-references, so File Formats should mention struct as a
related module.
> % Functions, Functional, Generators and Iterators
> \input{libitertools}
> \input{libfunctional}
> \input{liboperator} % from runtime - better with itertools and functional
> % encoding stuff
...
> \input{libxdrlib}
XDR is really more similar to struct or marshal, I think, but on the
other hand it is an Internet RFC (#1014). Not sure where it should go...
> \input{internet} % Internet Protocols
I wonder if the Internet chapter should be split into "HTTP/Web Tools"
(webbrowser, cgi, cgitb, httplib, urllib) and "Non-Web Protocols"
(ftplib, gopherlib, smtp, all the rest).
> \input{distutils}
Distutils should probably be in Program Frameworks. Or it could just
have a chapter of its own, or maybe there are enough modules for an
"Application Support" chapter.
--amk
BartlebyScrivener
The site changes for the new-to-Python person are a big improvement in
terms of the sequence of exposures, but from a marketing perspective,
the first thing they read about Python is still aimed at a programmer.
The bulleted points in BeginnersGuide/Overview are, again, things that
are important to programmers ("Automatic garbage collection frees you
from the hassles of memory management" means nothing to me, even now
after reading a Python book and several tutorials).
I wish there were some sort of sexy exposure to Python before hitting
them with the download. Again you purport to be making a page for
someone who's never programmed before, so almost certainly a Windows
user. And a Windows user is not going to download any program until
he's absolutely sure it won't destabilize his fragile system or infect
it. So nobody new to programming and new to Python is going to download
at the point you present them with that opportunity. Too bad there
isn't something like what Ruby does with the "Try Ruby In Your Browser"
thing, which is a very effective marketing tool (although obviously I
chose Python).
The other thing I vividly recall struggling with was: Do I download
this Python.org version for my Windows XP machine, because it's the
official one, or do I use the one from ActiveState because others say
it comes with all sorts of goodies for Windows users? I don't know what
the politics are there, but if I were you I'd take a stand and put it
on the download page to help the new person out, who is uncertain about
what to do.
Ultimately I downloaded ActiveState because I found their site easier
to understand (again speaking as a person relatively new to programming
and absolutely new to Python).
Thanks,
rpd
"I read part of it all the way through."--Samuel Goldwyn
Kent Johnson
> On Wed, 07 Dec 2005 12:10:18 -0500,
> Kent Johnson <ke...@kentsjohnson.com> wrote:
>
>>OK I'll bite. That Beginners Guide page has bugged me for a long time.
>>It's a wiki page but it is marked as immutable so I can't change it.
>>Here are some immediate suggestions:
>
>
> Good suggestions; thanks! I've applied most of them.
Thanks, this is a big improvement. Here are a few more ideas:
- change "Next, you need to get the Python interpreter installed on your
computer." to "Next, install the Python interpreter on your computer."
(active voice)
- move and rewrite the "You'll want to select a [WWW] text editor..."
sentence. For a raw beginner, this is not the next step and the page it
links to will not be helpful. Tutorials generally start out at the
interpreter prompt, not writing programs in an editor. Whatever editor
is handy and familiar is probably fine for a first program when the time
comes. Here is a suggested rewrite:
"When you are ready to write your first program you will need a text
editor. To get started you can use any editor you are familiar with such
as NotePad or <insert names of other common editors>. As you gain
experience you may want to use a text editors with features that help
you write Python programs. A comprehensive list is here <link>."
I think I would put this before the paragraph beginning "Once you've
read a tutorial".
- Move the "Need to know how to run Python programs on Windows?"
sentence to the last bullet of the list in the next paragraph and
rewrite it to
"Most tutorials assume you know how to run a program on your computer.
If you are using Windows and need help with this, see <link>."
- Change "Next, you're going to want to read a tutorial" to "Next, read
a tutorial"
With these changes the first links on this page are BG/Overview,
BG/Download and BG/NonProgrammers. The second link on BG/NonProgrammers
is a reasonable tutorial and the first link is pretty obviously one to
skip. So a beginner is guided through the necessary steps with nothing
extra or distracting or overwhelming intervening.
>>- Change the sentence "Read BeginnersGuide/Overview to learn the key
>>> points." to "Read BeginnersGuide/Overview to learn what makes Python
>>> special." Or maybe get rid of it completely - I'm not sure evangelism
>>> belongs on this page.
>
>
> Yes, it does; fairly often the webmaster alias receives e-mails that
> ask "so what is Python?"
Direct them to the "What is Python?" link on the front page maybe? ISTM
the material in BG/Overview belongs on the pages linked from "What is
Python?"
Thanks,
Kent
A.M. Kuchling
A.M. Kuchling <a...@amk.ca> wrote:
> of the seealso environment. I'll talk to Fred about it and begin
> assembling a patch.
Patch #1376361: http://www.python.org/sf/1376361 . I still need to talk
to Fred about this.
--amk
Fredrik Lundh
> > of the seealso environment. I'll talk to Fred about it and begin
> > assembling a patch.
>
> Patch #1376361: http://www.python.org/sf/1376361 . I still need to talk
> to Fred about this.
cool. can you post a sample page somewhere?
</F>
sk...@pobox.com
amk> I wonder if the Internet chapter should be split into "HTTP/Web
amk> Tools" (webbrowser, cgi, cgitb, httplib, urllib) and "Non-Web
amk> Protocols" (ftplib, gopherlib, smtp, all the rest).
Note that cgitb works just fine in a non-web environment. I would actually
prefer it be renamed ("fancytb"?) and then stuck wherever the traceback
module docs go.
>> \input{distutils}
amk> Distutils should probably be in Program Frameworks. Or it could just
amk> have a chapter of its own, or maybe there are enough modules for an
amk> "Application Support" chapter.
There are currently 46 module index entries for the various parts of
distutils. I think it would be helpful to reduce that number a bit...
Skip
Mike Meyer
> Too bad there
> isn't something like what Ruby does with the "Try Ruby In Your Browser"
> thing, which is a very effective marketing tool (although obviously I
> chose Python).
>
> http://tryruby.hobix.com/
I've seen things like this for other language as well. Doing it in
for Python isn't all that hard.
The question is how do you keep the system that the Python code is
actually running on safe? Ruby may have a real bastion mode, but
Python doesn't.
<mike
--
Mike Meyer <m...@mired.org> http://www.mired.org/home/mwm/
Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
Aahz
>"BartlebyScrivener" <rpdo...@gmail.com> writes:
>>
>> Too bad there
>> isn't something like what Ruby does with the "Try Ruby In Your Browser"
>> thing, which is a very effective marketing tool (although obviously I
>> chose Python).
>>
>> http://tryruby.hobix.com/
>
>I've seen things like this for other language as well. Doing it in
>for Python isn't all that hard.
>
>The question is how do you keep the system that the Python code is
>actually running on safe? Ruby may have a real bastion mode, but
>Python doesn't.
Just run the Python code chrooted.
--
Aahz (aa...@pythoncraft.com) <*> http://www.pythoncraft.com/
"Don't listen to schmucks on USENET when making legal decisions. Hire
yourself a competent schmuck." --USENET schmuck (aka Robert Kern)
Trent Mick
> "BartlebyScrivener" <rpdo...@gmail.com> writes:
> > Too bad there
> > isn't something like what Ruby does with the "Try Ruby In Your Browser"
> > thing, which is a very effective marketing tool (although obviously I
> > chose Python).
> >
> > http://tryruby.hobix.com/
>
> I've seen things like this for other language as well. Doing it in
> for Python isn't all that hard.
>
> The question is how do you keep the system that the Python code is
> actually running on safe? Ruby may have a real bastion mode, but
> Python doesn't.
Nah, the Try Ruby thing is mostly faking it (I believe) rather than
running an actually Ruby interactive session ("bastion'ed" or not).
Trent
--
Trent Mick
Tre...@ActiveState.com
sk...@pobox.com
Mike> The question is how do you keep the system that the Python code is
Mike> actually running on safe? Ruby may have a real bastion mode, but
Mike> Python doesn't.
User Mode Linux? chroot?
Skip
sk...@pobox.com
Trent> Nah, the Try Ruby thing is mostly faking it (I believe) rather
Trent> than running an actually Ruby interactive session ("bastion'ed"
Trent> or not).
I don't think so. I tried typing some stuff at the prompt that it wasn't
asking for, like "x = [1,2,3]" followed by "x * 5" when it was asking me to
type "2 + 6". It evaluated both properly as far as I could tell. OTOH, it
hung when I entered "def fib(n)". Never got to the next prompt. Looking at
the Javascript, it appears to be some sort of Ajaxian thing...
Skip
Terry Hancock
Mike Meyer <m...@mired.org> wrote:
> "BartlebyScrivener" <rpdo...@gmail.com> writes:
> > Too bad there
> > isn't something like what Ruby does with the "Try Ruby
> > In Your Browser" thing, which is a very effective
> > marketing tool (although obviously I chose Python).
> >
> > http://tryruby.hobix.com/
>
> I've seen things like this for other language as well.
> Doing it in for Python isn't all that hard.
>
> The question is how do you keep the system that the Python
> code is actually running on safe? Ruby may have a real
> bastion mode, but Python doesn't.
Should be able to use Jython and run on the visitor's
machine, shouldn't you?
--
Terry Hancock (han...@AnansiSpaceworks.com)
Anansi Spaceworks http://www.AnansiSpaceworks.com
BartlebyScrivener
that it would very seductive to a prospective Pythoner, and you avoid
the problem of making them download before they can try out a tutorial.
Thanks for looking at it.
rd
Trent Mick
>
> Trent> Nah, the Try Ruby thing is mostly faking it (I believe) rather
> Trent> than running an actually Ruby interactive session ("bastion'ed"
> Trent> or not).
>
> I don't think so. I tried typing some stuff at the prompt that it wasn't
> asking for, like "x = [1,2,3]" followed by "x * 5" when it was asking me to
> type "2 + 6". It evaluated both properly as far as I could tell.
Yah. My guess at what he is doing (and the way I'd probably do this for
Python) is to compile each statement, only allow certain constructs
(like assigning to a variable, defining literals, basic operator usage,
maybe some control flow statements -- although I didn't get that far)
and then execute those.
> OTOH, it
> hung when I entered "def fib(n)". Never got to the next prompt.
Punted on continued/multi-line statements maybe?
> Looking at
> the Javascript, it appears to be some sort of Ajaxian thing...
Yup.
A.M. Kuchling
Fredrik Lundh <fre...@pythonware.com> wrote:
> cool. can you post a sample page somewhere?
It's not terribly interesting at the moment. The generated LaTeX looks like
this:
\seeurl{http://effbot.org/librarybook/zlib.htm}{The zlib module}
And that gets formatted like other URL links.
BThe associated text currently isn't very helpful, but I'm not sure how
to make it better. Maybe it could be "'<item-title>', from '<dc:title>'
by <dc:creator>". Then the text for your file would be "'The zlib module',
from '(the eff-bot guide to) The Standard Python Library' by Fredrik Lundh."
Can I safely treat the dc:identifier field as the URL for the work as
a whole? Then I could turn the book title into a hyperlink.
--amk
Mike Meyer
> [sk...@pobox.com wrote]
>> Trent> Nah, the Try Ruby thing is mostly faking it (I believe) rather
>> Trent> than running an actually Ruby interactive session ("bastion'ed"
>> Trent> or not).
>> I don't think so. I tried typing some stuff at the prompt that it wasn't
>> asking for, like "x = [1,2,3]" followed by "x * 5" when it was asking me to
>> type "2 + 6". It evaluated both properly as far as I could tell.
> Yah. My guess at what he is doing (and the way I'd probably do this for
> Python) is to compile each statement, only allow certain constructs
> (like assigning to a variable, defining literals, basic operator usage,
> maybe some control flow statements -- although I didn't get that far)
> and then execute those.
I'm working on puttingn this up for Python. I'm planning on using AJAX
to pass the input string to eval on the server. I.e. - you'll be
limited to expressions, which is what it seems like the Ruby thing is
limited to.
On the other hand, with iterators, generators and list comprehensions,
you can do quite a lot with eval.
If anyone else is contemplating putting up something like this, let me
know so we can avoijd duplicating the effort.
Paul Rubin
> I'm working on puttingn this up for Python. I'm planning on using AJAX
> to pass the input string to eval on the server. I.e. - you'll be
> limited to expressions, which is what it seems like the Ruby thing is
> limited to.
>
> On the other hand, with iterators, generators and list comprehensions,
> you can do quite a lot with eval.
How will you stop the server from getting hosed?
Mike Meyer
Still working on that. If I can't, it won't happen.
BartlebyScrivener
This is probably a dumb thing to suggest, but I'm interested in knowing
why it's dumb, if that makes sense?
Could you use one of those free VMWare players? It makes a virtual
operating system within an operating system as I understand it.
http://www.vmware.com/products/player/
I just think it's cool that somebody tries to make a Try Python In Your
Browser toy. You'll convert the multitudes to Python.
Let me know if you want any help creating the messages for the complete
idiot
"The question is not whether machines think, but whether men do."--B.F.
Skinner
Fredrik Lundh
> BThe associated text currently isn't very helpful, but I'm not sure how
> to make it better. Maybe it could be "'<item-title>', from '<dc:title>'
> by <dc:creator>". Then the text for your file would be "'The zlib module',
> from '(the eff-bot guide to) The Standard Python Library' by Fredrik Lundh."
that should work.
if it turns out that this doesn't scale (has anyone put up that library
reference wiki yet? ;-), you can always add an override option to the
file that holds the seealso URL list.
> Can I safely treat the dc:identifier field as the URL for the work as
> a whole? Then I could turn the book title into a hyperlink.
that should be safe.
the DC documentation is a bit convoluted, but if I understand things
correctly, the dc:identifier field should, by default, contain an URI.
(doing a full type check involves checking the xsi:type attribute for
dcterms:URI (evil!), but simply stripping the whitespace and checking
that the rest starts with "http://" should be good enough.)
</F>
Fredrik Lundh
> if it turns out that this doesn't scale (has anyone put up that library
> reference wiki yet? ;-)
if anyone's interested, here's a seealso file for the python library
reference:
http://effbot.org/zone/seealso-python-library.xml
this was generated from the global module index by this script:
http://effbot.org/zone/seealso-python-library.htm
still waiting for that wiki ;-)
</F>
A.M. Kuchling
Fredrik Lundh <fre...@pythonware.com> wrote:
>> to make it better. Maybe it could be "'<item-title>', from '<dc:title>'
>> by <dc:creator>". Then the text for your file would be "'The zlib module',
>> from '(the eff-bot guide to) The Standard Python Library' by Fredrik Lundh."
>
> that should work.
Now implemented in SVN.
> the DC documentation is a bit convoluted, but if I understand things
> correctly, the dc:identifier field should, by default, contain an URI.
That's what I assumed. You could theoretically supply something like
urn:isbn:1234567890, but then what are you linking to? I implemented
your suggested check.
I've written Fred Drake about this, but haven't received a reply yet.
Fred is in the same area as me, so I'm hoping we can talk about
various doc things over coffee (example links being one of them).
--amk
A.M. Kuchling
> The bulleted points in BeginnersGuide/Overview are, again, things that
> are important to programmers ("Automatic garbage collection frees you
> from the hassles of memory management" means nothing to me, even now
> after reading a Python book and several tutorials).
I've reworked Overview to use more straightforward language, and to
break out the programming-language features into a separate list.
Maybe that will help.
--amk