From mclay@eeel.nist.gov Wed May 29 14:17:21 1996 From: mclay@eeel.nist.gov (Michael McLay) Date: Wed, 29 May 96 09:17:21 EDT Subject: [PYTHON DOC-SIG] Preparing for IPC-IV In-Reply-To: <199605282121.RAA21104@weyr.CNRI.Reston.Va.US> References: <199605282121.RAA21104@weyr.CNRI.Reston.Va.US> Message-ID: <9605291317.AA03713@acdc.eeel.nist.gov> As the coordinator for the doc-sig, I've been asked to give a presentation on the SIG and to set up the arrangements for the SIG meeting at the conference. If you are on this list and will be attending the conference please send me a note if you will be participating in the SIG discussion. Also indicate which other SIG discussions would take priority over the doc-sig session. There has been some discussion on the format for doc strings. If you have an opinion on this subject, or if you have done some work on tools to process doc strings, please speak up. I'd like to have some slides on the subject for the Tuesday morning presentation on the doc-sig. My initial guess is that we would need no more than 30-45 minutes for a SIG meeting on Thursday. Does anyone think we need more time to discuss issues and plan for future work? Michael ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From jim.fulton@digicool.com Thu May 30 20:13:43 1996 From: jim.fulton@digicool.com (Jim Fulton) Date: Thu, 30 May 1996 15:13:43 -0400 Subject: [PYTHON DOC-SIG] Re: [PROGENV-SIG] Project proposal discussion document References: <199605301838.OAA27273@weyr.CNRI.Reston.Va.US> Message-ID: <31ADF367.824@digicool.com> Fred L. Drake wrote: > > I am advancing a proposal for a project which would benefit from the > input of the members of both doc-sig and progenv-sig. I have prepared a > discussion document describing the project in general terms in more detail > than I present in this message, but a brief summary is appropriate. > > My intention is to produce tools which can analyze Python source code, > potentially as it is imported into a running Python process, and perform > sufficient analysis to create a representation of the object hierarchy > with as much documentation as can be derived from the source text and > documentation strings as possible. The data structure created by the > analysis should allow for programmatic examination as part of an > interactive development or debugging environment or for the generation of > static documentation of a collection of modules. > > My hope is that this project can be a collaborative project of, > primarily, the progenv SIG with the doc SIG providing critical advisory > input and evaluation. As described above, the work appears to be of > sufficient general interest to warrent the involvement of many > contributors. At the same time, the work promises enough modularity that > individuals need not invest huge amounts of time to provide a meaningful > contribution. The most significant investment to be made before > applications may be created within the project framework involves reaching > a consensus on the definable stages of the project and precise definitions > of the underlying data architecture. > > The discussion document is available via the world wide web at: > > http://weyr.cnri.reston.va.us/progenv/ > > Feedback is invited via the SIG mailing lists. I will be attending the > Python conference next week and hope to bring this proposal up at the > doc-sig and progenv-sig working groups. This sounds like an interesting discussion topic for next week. I look forward to it. I have a couple of questions: 1. I couldn't tell from your note or referenced web pages what problems you are trying to solve. Could you elaborate? 2. Why is it necessary to parse sources or manipulate parse trees? This limits the scope to python objects, but browsing C, ILU and other types of objects seems just as interesting to me. Wouldn't it be better to define and implement necessary object protocols for discovery and browsing? What problems require source analysis? Jim -- Jim Fulton Digital Creations jim@digicool.com 540.371.6909 ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From monty@tbyte.com Thu May 30 21:32:01 1996 From: monty@tbyte.com (Monty Zukowski) Date: Thu, 30 May 1996 13:32:01 -0700 Subject: [PYTHON DOC-SIG] RE: [PROGENV-SIG] Project proposal discussion document Message-ID: For what it's worth, the Sorcerer toolkit looks like an excellent approach to parse tree walking and translation. But of course it is in C. The newsgroup for it is comp.compilers.tools.pccts. Also look at . I haven't actually used it myself but I've read the documentation quite a bit and love the LL approach to the problem. This may be useful for the translation of the internal python parse tree into the general framework structures. If only I had the time to spare... >---------- >From: Fred L. Drake[SMTP:fdrake@CNRI.Reston.Va.US] >Sent: Thursday, May 30, 1996 11:38 AM >To: Progenv-SIG Mailing List; Doc-SIG Mailing List >Subject: [PROGENV-SIG] Project proposal discussion document > > I am advancing a proposal for a project which would benefit from the >input of the members of both doc-sig and progenv-sig. I have prepared >a >discussion document describing the project in general terms in more >detail >than I present in this message, but a brief summary is appropriate. > > My intention is to produce tools which can analyze Python source >code, >potentially as it is imported into a running Python process, and >perform >sufficient analysis to create a representation of the object hierarchy >with as much documentation as can be derived from the source text and >documentation strings as possible. The data structure created by the >analysis should allow for programmatic examination as part of an >interactive development or debugging environment or for the generation >of >static documentation of a collection of modules. > > My hope is that this project can be a collaborative project of, >primarily, the progenv SIG with the doc SIG providing critical advisory >input and evaluation. As described above, the work appears to be of >sufficient general interest to warrent the involvement of many >contributors. At the same time, the work promises enough modularity >that >individuals need not invest huge amounts of time to provide a >meaningful >contribution. The most significant investment to be made before >applications may be created within the project framework involves >reaching >a consensus on the definable stages of the project and precise >definitions >of the underlying data architecture. > > ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From anthony.baxter@aaii.oz.au Fri May 31 01:35:45 1996 From: anthony.baxter@aaii.oz.au (anthony baxter) Date: Fri, 31 May 1996 10:35:45 +1000 Subject: [PYTHON DOC-SIG] Internals documentation: what format? Message-ID: <199605310035.KAA04887@alamein> Something else to consider: I'd like the stuff on the python internals(*) that I started yonks ago to be finished up at some point - but I'm really not all that happy with the current format for the text (pod). Does anyone have suggestions for a better format for this stuff? I want to be able to generate HTML, and also something nicer, and I'd also like it to be fairly easy to write. Anyone? Anthony (*) ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From guido@CNRI.Reston.Va.US Fri May 31 16:04:46 1996 From: guido@CNRI.Reston.Va.US (Guido van Rossum) Date: Fri, 31 May 1996 11:04:46 -0400 Subject: [PYTHON DOC-SIG] Internals documentation: what format? In-Reply-To: Your message of "Fri, 31 May 1996 10:35:45 +1000." <199605310035.KAA04887@alamein> References: <199605310035.KAA04887@alamein> Message-ID: <199605311504.LAA01213@monty> > I'd like the stuff on the python internals(*) that I started yonks ago > to be finished up at some point - but I'm really not all that happy with > the current format for the text (pod). Does anyone have suggestions for > a better format for this stuff? I want to be able to generate HTML, and > also something nicer, and I'd also like it to be fairly easy to write. How about doc strings? Jim Fulton continues to threaten to give us tools that will generate the documentation from doc strings, even if they are embedded in C source... --Guido van Rossum (home page: http://www.python.org/~guido/) ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From anthony.baxter@aaii.oz.au Fri May 31 17:51:57 1996 From: anthony.baxter@aaii.oz.au (anthony baxter) Date: Sat, 01 Jun 1996 02:51:57 +1000 Subject: [PYTHON DOC-SIG] Internals documentation: what format? In-Reply-To: Message from Guido van Rossum of 1996-May-31 11:04:46, <199605311504.LAA01213@monty> Message-ID: <199605311651.CAA17386@aaii.oz.au> >>> Guido van Rossum wrote: > > I'd like the stuff on the python internals(*) that I started yonks ago > > to be finished up at some point - but I'm really not all that happy with > > the current format for the text (pod). Does anyone have suggestions for > > a better format for this stuff? I want to be able to generate HTML, and > > also something nicer, and I'd also like it to be fairly easy to write. > How about doc strings? Jim Fulton continues to threaten to give us > tools that will generate the documentation from doc strings, even if > they are embedded in C source... I dont see how doc strings help with the internals docs - sure, for the builtin objects (ints, lists, &c) they might help, but there are other routines that don't lend themselves to doc-string-ification. Anthony PS: any typos are the fault of too much alcohol - hey, no law against emailing whilst drunk :) ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From fdrake@CNRI.Reston.Va.US Thu May 30 19:38:56 1996 From: fdrake@CNRI.Reston.Va.US (Fred L. Drake) Date: Thu, 30 May 1996 14:38:56 -0400 (EDT) Subject: [PYTHON DOC-SIG] Project proposal discussion document Message-ID: <199605301838.OAA27273@weyr.CNRI.Reston.Va.US> I am advancing a proposal for a project which would benefit from the input of the members of both doc-sig and progenv-sig. I have prepared a discussion document describing the project in general terms in more detail than I present in this message, but a brief summary is appropriate. My intention is to produce tools which can analyze Python source code, potentially as it is imported into a running Python process, and perform sufficient analysis to create a representation of the object hierarchy with as much documentation as can be derived from the source text and documentation strings as possible. The data structure created by the analysis should allow for programmatic examination as part of an interactive development or debugging environment or for the generation of static documentation of a collection of modules. My hope is that this project can be a collaborative project of, primarily, the progenv SIG with the doc SIG providing critical advisory input and evaluation. As described above, the work appears to be of sufficient general interest to warrent the involvement of many contributors. At the same time, the work promises enough modularity that individuals need not invest huge amounts of time to provide a meaningful contribution. The most significant investment to be made before applications may be created within the project framework involves reaching a consensus on the definable stages of the project and precise definitions of the underlying data architecture. The discussion document is available via the world wide web at: http://weyr.cnri.reston.va.us/progenv/ Feedback is invited via the SIG mailing lists. I will be attending the Python conference next week and hope to bring this proposal up at the doc-sig and progenv-sig working groups. -Fred -- Fred L. Drake, Jr. fdrake@cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 22091 ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org =================