OK, so I talked with Sam about this, and he's written some pretty good introductory material... but here's the thing... USING asyncore and asynchat requires a brain adjustment for most people, which seems to be outside the realm of the reference manual, so how to deal with this? Should I just document the class and ignore the issue of ideology? I know, this is a great topic for a HOWTO, and I'm meaning to reformat Sam's introduction into one, but... that doesn't fix the library manual. Also, I was thinking... perhaps there should be a way to note that there's something in the source code INTENTIONALLY undocumented that might be of trivial use to someone maybe oneday? DOn't know... there's some things in asyncore like that, you might be interested, but... Chris -- | Christopher Petrilli ``Television is bubble-gum for | petrilli@amber.org the mind.''-Frank Lloyd Wright
OK, so I talked with Sam about this, and he's written some pretty good introductory material... but here's the thing... USING asyncore and asynchat requires a brain adjustment for most people, which seems to be outside the realm of the reference manual, so how to deal with this? Should I just document the class and ignore the issue of ideology? I know, this is a great topic for a HOWTO, and I'm meaning to reformat Sam's introduction into one, but... that doesn't fix the library manual.
I'm not sure why it wouldn't fit in the library manual. For example the profiler and debugger chapters have some tutorial style material in them, and there are some others.
Also, I was thinking... perhaps there should be a way to note that there's something in the source code INTENTIONALLY undocumented that might be of trivial use to someone maybe oneday? DOn't know... there's some things in asyncore like that, you might be interested, but...
I'm not sure what you are talking about here -- to indicate that something is not intended to be documented a comment in the source should be sufficient. Documenting seems to be an oximoron ("there's this really nify undocumented printindex() method in this class that you're not supposed to use but could nevertheless be real handy one day" ???). --Guido van Rossum (home page: http://www.python.org/~guido/)
On Wed, Feb 24, 1999 at 12:09:11PM -0500, Guido van Rossum wrote:
OK, so I talked with Sam about this, and he's written some pretty good introductory material... but here's the thing... USING asyncore and asynchat requires a brain adjustment for most people, which seems to be outside the realm of the reference manual, so how to deal with this? Should I just document the class and ignore the issue of ideology? I know, this is a great topic for a HOWTO, and I'm meaning to reformat Sam's introduction into one, but... that doesn't fix the library manual.
I'm not sure why it wouldn't fit in the library manual. For example the profiler and debugger chapters have some tutorial style material in them, and there are some others.
My fear was that while the profiler/debuggers have "tutorials", the async programming idea requires more like 10-15 pages of stuff to really get it across to people in a sane way they can understand... it's just too different for most people's mindset. Anyway, what I'm thinkin is just document it a'la a regular library with a 1-2 paragraph introduction as to WHAT async sockets are meant to provide, and then say 2 examples of small size which show it being used (probably Sam's proxy example being one). a HOWTO could then delve into it more deeply.
Also, I was thinking... perhaps there should be a way to note that there's something in the source code INTENTIONALLY undocumented that might be of trivial use to someone maybe oneday? DOn't know... there's some things in asyncore like that, you might be interested, but...
I'm not sure what you are talking about here -- to indicate that something is not intended to be documented a comment in the source should be sufficient. Documenting seems to be an oximoron ("there's this really nify undocumented printindex() method in this class that you're not supposed to use but could nevertheless be real handy one day" ???).
Ignore that, i"m not sure what I was talking about :-) I think I was reffering to there being some aspects of libraries that shouldn't be twiddled with without a deep understanding of the working code. My later comment about "dangerous" things might fit in better with that. Looking back, I must have been suffering from some drug (legal) induced stupor! Chris -- | Christopher Petrilli ``Television is bubble-gum for | petrilli@amber.org the mind.''-Frank Lloyd Wright
On Wed, Feb 24, 1999 at 12:09:11PM -0500, Guido van Rossum wrote:
I'm not sure why it wouldn't fit in the library manual. For example the profiler and debugger chapters have some tutorial style material in them, and there are some others.
Christopher G. Petrilli writes:
My fear was that while the profiler/debuggers have "tutorials", the async programming idea requires more like 10-15 pages of stuff to
I think we can spare a few pages of introductory material, and good, succinct examples are always welcome. Longer, tutorial style material can be a separate document, and I'll be glad for the standard docs to refer to such a beast, *if* I can have reference material in the library manual! Perhaps my policy should be "If you write it, I will \input." ;-) -Fred -- Fred L. Drake, Jr. <fdrake@acm.org> Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191
participants (3)
-
Christopher G. Petrilli -
Fred L. Drake -
Guido van Rossum