From janssen@parc.xerox.com Wed Nov 6 20:33:12 1996 From: janssen@parc.xerox.com (Bill Janssen) Date: Wed, 6 Nov 1996 12:33:12 PST Subject: [PYTHON DOC-SIG] Re: [PYTHON MATRIX-SIG] Alpha release of new tutorial for 1.0a5 In-Reply-To: <199611061853.NAA02216@monty> References: <199610231721.NAA22272@maigret> <199611061853.NAA02216@monty> Message-ID: Excerpts from direct: 6-Nov-96 Re: [PYTHON DOC-SIG] Re: [P.. Guido van Rossum@cnri.re (539) > One short-term solution would be to use conditional inclusion. I > believe texinfo supports this -- you can have one version of a > paragraph/sentence/word for one back-end (e.g. TeX), and another for > the others. I *think*... Yes; here's the relevant section from the TeXinfo manual: Using Ordinary TeX Commands =========================== Inside a region delineated by `@iftex' and `@end iftex', you can embed some PlainTeX commands. Info will ignore these commands since they are only in that part of the file which is seen by TeX. You can write the TeX commands as you would write them in a normal TeX file, except that you must replace the `\' used by TeX with an `@'. For example, in the `@titlepage' section of a Texinfo file, you can use the TeX command `@vskip' to format the copyright page. (The `@titlepage' command causes Info to ignore the region automatically, as it does with the `@iftex' command.) However, many features of PlainTeX will not work, as they are overridden by features of Texinfo. You can enter PlainTeX completely, and use `\' in the TeX commands, by delineating a region with the `@tex' and `@end tex' commands. (The `@tex' command also causes Info to ignore the region, like the `@iftex' command.) For example, here is a mathematical expression written in PlainTeX: @tex $$ \chi^2 = \sum_{i=1}^N \left (y_i - (a + b x_i) \over \sigma_i\right)^2 $$ @end tex The output of this example will appear only in a printed manual. If you are reading this in Info, you will not see anything after this paragraph. ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From skip@calendar.com (Skip Montanaro) Thu Nov 7 02:19:44 1996 From: skip@calendar.com (Skip Montanaro) (Skip Montanaro) Date: Wed, 6 Nov 1996 21:19:44 -0500 (EST) Subject: [PYTHON DOC-SIG] Re: [PYTHON MATRIX-SIG] Where to go (was Numerical Recipes) In-Reply-To: <199610211441.JAA00648@darwin.rsoc.rockwell.com> References: <199610211441.JAA00648@darwin.rsoc.rockwell.com> Message-ID: <199611070219.VAA16356@dolphin.automatrix.com> Robin Friedrich writes: It should be made clear that the Language Reference and Tutorial are the only docs converted to FrameMaker. It should also be made clear that restricting those docs to FrameMaker makes it doubly difficult to get any help updating them... (In case it's not clear, I still think migrating to FM is a mistake for documentation of free software.) Skip Montanaro | Musi-Cal: http://concerts.calendar.com/ skip@calendar.com | Conference Calendar: http://conferences.calendar.com/ (518)372-5583 | Python: http://www.python.org/ Annoyed with coverage of WWW? http://www.automatrix.com/~skip/diatribe.html ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From janssen@parc.xerox.com Thu Nov 7 02:34:40 1996 From: janssen@parc.xerox.com (Bill Janssen) Date: Wed, 6 Nov 1996 18:34:40 PST Subject: [PYTHON DOC-SIG] Re: [PYTHON MATRIX-SIG] Where to go (was Numerical Recipes) In-Reply-To: <199611070219.VAA16356@dolphin.automatrix.com> References: <199610211441.JAA00648@darwin.rsoc.rockwell.com> <199611070219.VAA16356@dolphin.automatrix.com> Message-ID: Excerpts from ext.python: 6-Nov-96 [PYTHON DOC-SIG] Re: [PYTHO.. Skip Montanaro@automatri (826) > (In case it's not clear, I still think migrating to FM is a mistake for > documentation of free > software.) Yes, I tend to agree. Bill ================= 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 Thu Nov 7 03:23:17 1996 From: guido@CNRI.Reston.Va.US (Guido van Rossum) Date: Wed, 06 Nov 1996 22:23:17 -0500 Subject: [PYTHON DOC-SIG] Re: [PYTHON MATRIX-SIG] Where to go (was Numerical Recipes) In-Reply-To: Your message of "Wed, 06 Nov 1996 21:19:44 EST." <199611070219.VAA16356@dolphin.automatrix.com> References: <199610211441.JAA00648@darwin.rsoc.rockwell.com> <199611070219.VAA16356@dolphin.automatrix.com> Message-ID: <199611070323.WAA04501@monty> > It should also be made clear that restricting those docs to FrameMaker makes > it doubly difficult to get any help updating them... (In case it's not > clear, I still think migrating to FM is a mistake for documentation of free > software.) Unfortunately, the only help I tend to get for the reference manual and the tutorial is people pointing out typos or complaining about unclarities. Often with page number references only. And lately, most people refer to the HTML versions... I doubt that this kind of feedback will disappear when the manuals are in FrameMaker. To the contrary, I received much help from Robin Friedrich with the FrameMaker version of the reference manual. I also received an offer of other manuals converted to FrameMaker -- so there is clearly a demand for FrameMaker, too! The manual for which I got the most help in the form of new sections or chapters is the library reference manual -- which will remain in LaTeX or be converted to TIM. The same holds for the (embryonic :-( ) part of the extensions manual that documents individual API functions -- this will be a separate manual like the library reference. Note that most people want either something they can view on their screen, or something they can print. The former is best served by HTML, which we provide. For the Unix world, the PostScript on the ftp site provides a printable form. For the PC world, FrameMaker is more likely to be available in some form than LaTeX, which is reputedly difficult to install. --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 amk@magnet.com Thu Nov 7 17:48:53 1996 From: amk@magnet.com (Andrew Kuchling) Date: Thu, 7 Nov 1996 12:48:53 -0500 (EST) Subject: [PYTHON DOC-SIG] Re: Inclusion of contributed modules In-Reply-To: <199611070344.WAA04726@monty> from "Guido van Rossum" at Nov 6, 96 10:44:52 pm Message-ID: <199611071748.MAA14352@lemur.magnet.com> Guido van Rossum wrote (in comp.lang.python): > A good start would probably to have a standard infrastructure to build > third-party extensions. How about having them inside a subdirectory > Extensions in the Python toplevel directory, if they are relatively IMHO, all non-standard modules should live in such an Extensions/ subdirectory; I've tried to do this with the sizable extensions that I write. ILU's really a rare special case, since it's much more than simply a Python module. Another important point to consider is documentation for extension modules; if possible, lib*.tex files should be automatically included in the library reference. I hate the fact that many modules come with READMEs The following script looks through the directories in sys.path for anything that can be imported, cross-references them with the files in Doc/, and produces TeX code for a customized library reference. The only thing needed is to have it walk through subdirectories of Extensions/, find any lib*.tex files, and generate appropriate TeX code. (Perhaps it shouldn't list the standard modules at all; then adding a new module won't require reprinting the entire Library Reference, but only a much smaller custom modules document.) Andrew Kuchling amk@magnet.com # Generate custlib.tex, which is a site-specific library document. # Phase I: list all the things that can be imported import glob, os, sys, string modules={} for modname in sys.builtin_module_names: modules[modname]=modname for dir in sys.path: # Look for *.py files filelist=glob.glob(os.path.join(dir, '*.py')) for file in filelist: path, file = os.path.split(file) base, ext=os.path.splitext(file) modules[string.lower(base)]=base # Look for shared library files filelist=(glob.glob(os.path.join(dir, '*.so')) + glob.glob(os.path.join(dir, '*.sl')) + glob.glob(os.path.join(dir, '*.o')) ) for file in filelist: path, file = os.path.split(file) base, ext=os.path.splitext(file) if base[-6:]=='module': base=base[:-6] modules[string.lower(base)]=base # Minor oddity: the types module is documented in libtypes2.tex if modules.has_key('types'): del modules['types'] ; modules['types2']=None # Phase II: find all documentation files (lib*.tex) # and eliminate modules that don't have one. docs={} filelist=glob.glob('lib*.tex') for file in filelist: modname=file[3:-4] docs[modname]=modname mlist=modules.keys() mlist=filter(lambda x, docs=docs: docs.has_key(x), mlist) mlist.sort() mlist=map(lambda x, docs=docs: docs[x], mlist) modules=mlist # Phase III: write custlib.tex # Write the boilerplate # XXX should be fancied up. print """\documentstyle[twoside,11pt,myformat]{report} \\title{Python Library Reference} \\input{boilerplate} \\makeindex % tell \\index to actually write the .idx file \\begin{document} \\pagenumbering{roman} \\maketitle \\input{copyright} \\begin{abstract} \\noindent This is a customized version of the Python Library Reference. \\end{abstract} \\pagebreak {\\parskip = 0mm \\tableofcontents} \\pagebreak\\pagenumbering{arabic}""" for modname in mlist: print "\\input{lib%s}" % (modname,) # Write the end print """\\input{custlib.ind} % Index \\end{document}""" ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From janssen@parc.xerox.com Thu Nov 7 21:17:40 1996 From: janssen@parc.xerox.com (Bill Janssen) Date: Thu, 7 Nov 1996 13:17:40 PST Subject: [PYTHON DOC-SIG] Re: [PYTHON MATRIX-SIG] Where to go (was Numerical Recipes) In-Reply-To: <199611070323.WAA04501@monty> References: <199610211441.JAA00648@darwin.rsoc.rockwell.com> <199611070219.VAA16356@dolphin.automatrix.com> <199611070323.WAA04501@monty> Message-ID: Excerpts from ext.python: 6-Nov-96 Re: [PYTHON DOC-SIG] Re: [P.. Guido van Rossum@cnri.re (1751) > To the contrary, I received much help from Robin Friedrich with the > FrameMaker version of the reference manual. I also received an offer > of other manuals converted to FrameMaker -- so there is clearly a > demand for FrameMaker, too! Perhaps we could do a Texinfo->FrameMaker-MIF converter? I once had one for the precursor to TIM, but it would take some real digging to reconstruct it. Bill ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From janssen@parc.xerox.com Thu Nov 7 02:34:40 1996 From: janssen@parc.xerox.com (Bill Janssen) Date: Wed, 6 Nov 1996 18:34:40 PST Subject: [PYTHON DOC-SIG] Re: [PYTHON MATRIX-SIG] Where to go (was Numerical Recipes) In-Reply-To: <199611070219.VAA16356@dolphin.automatrix.com> References: <199610211441.JAA00648@darwin.rsoc.rockwell.com> <199611070219.VAA16356@dolphin.automatrix.com> Message-ID: Excerpts from ext.python: 6-Nov-96 [PYTHON DOC-SIG] Re: [PYTHO.. Skip Montanaro@automatri (826) > (In case it's not clear, I still think migrating to FM is a mistake for > documentation of free > software.) Yes, I tend to agree. Bill ================= 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 Wed Nov 6 18:53:10 1996 From: guido@CNRI.Reston.Va.US (Guido van Rossum) Date: Wed, 06 Nov 1996 13:53:10 -0500 Subject: [PYTHON DOC-SIG] Re: [PYTHON MATRIX-SIG] Alpha release of new tutorial for 1.0a5 In-Reply-To: Your message of "Wed, 23 Oct 1996 13:21:12 EDT." <199610231721.NAA22272@maigret> References: <199610231721.NAA22272@maigret> Message-ID: <199611061853.NAA02216@monty> > For most of the python modules, I think TIM would be good enough. > For the scientific extensions which are bound to arrive in droves =), > it'd be nice to have one which allowed math like LaTeX, but also > allowed it to be displayed in HTML form. One short-term solution would be to use conditional inclusion. I believe texinfo supports this -- you can have one version of a paragraph/sentence/word for one back-end (e.g. TeX), and another for the others. I *think*... --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 skip@calendar.com (Skip Montanaro) Thu Nov 7 02:19:44 1996 From: skip@calendar.com (Skip Montanaro) (Skip Montanaro) Date: Wed, 6 Nov 1996 21:19:44 -0500 (EST) Subject: [PYTHON DOC-SIG] Re: [PYTHON MATRIX-SIG] Where to go (was Numerical Recipes) In-Reply-To: <199610211441.JAA00648@darwin.rsoc.rockwell.com> References: <199610211441.JAA00648@darwin.rsoc.rockwell.com> Message-ID: <199611070219.VAA16356@dolphin.automatrix.com> Robin Friedrich writes: It should be made clear that the Language Reference and Tutorial are the only docs converted to FrameMaker. It should also be made clear that restricting those docs to FrameMaker makes it doubly difficult to get any help updating them... (In case it's not clear, I still think migrating to FM is a mistake for documentation of free software.) Skip Montanaro | Musi-Cal: http://concerts.calendar.com/ skip@calendar.com | Conference Calendar: http://conferences.calendar.com/ (518)372-5583 | Python: http://www.python.org/ Annoyed with coverage of WWW? http://www.automatrix.com/~skip/diatribe.html ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From janssen@parc.xerox.com Wed Nov 6 20:33:12 1996 From: janssen@parc.xerox.com (Bill Janssen) Date: Wed, 6 Nov 1996 12:33:12 PST Subject: [PYTHON DOC-SIG] Re: [PYTHON MATRIX-SIG] Alpha release of new tutorial for 1.0a5 In-Reply-To: <199611061853.NAA02216@monty> References: <199610231721.NAA22272@maigret> <199611061853.NAA02216@monty> Message-ID: Excerpts from direct: 6-Nov-96 Re: [PYTHON DOC-SIG] Re: [P.. Guido van Rossum@cnri.re (539) > One short-term solution would be to use conditional inclusion. I > believe texinfo supports this -- you can have one version of a > paragraph/sentence/word for one back-end (e.g. TeX), and another for > the others. I *think*... Yes; here's the relevant section from the TeXinfo manual: Using Ordinary TeX Commands =========================== Inside a region delineated by `@iftex' and `@end iftex', you can embed some PlainTeX commands. Info will ignore these commands since they are only in that part of the file which is seen by TeX. You can write the TeX commands as you would write them in a normal TeX file, except that you must replace the `\' used by TeX with an `@'. For example, in the `@titlepage' section of a Texinfo file, you can use the TeX command `@vskip' to format the copyright page. (The `@titlepage' command causes Info to ignore the region automatically, as it does with the `@iftex' command.) However, many features of PlainTeX will not work, as they are overridden by features of Texinfo. You can enter PlainTeX completely, and use `\' in the TeX commands, by delineating a region with the `@tex' and `@end tex' commands. (The `@tex' command also causes Info to ignore the region, like the `@iftex' command.) For example, here is a mathematical expression written in PlainTeX: @tex $$ \chi^2 = \sum_{i=1}^N \left (y_i - (a + b x_i) \over \sigma_i\right)^2 $$ @end tex The output of this example will appear only in a printed manual. If you are reading this in Info, you will not see anything after this paragraph. ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From x-aes@telelogic.se Tue Nov 19 09:56:50 1996 From: x-aes@telelogic.se (Andy Eskilsson) Date: 19 Nov 1996 10:56:50 +0100 Subject: [PYTHON DOC-SIG] Self-documenting code.. :-) Message-ID: I don't know if this has been discussed before (I just joined the list) but would it be possible to do some kind of browser for X and uhm.. well curses sort of would be fine? What I really want to say is that most X applications has a help-menu.. and well there already (hopefully) exists documentation for the application in the __doc__ strings, so why not use the __doc__ string when generating the help dialog? Of course this should use the standards the rest of the docs are using.. An example of this have I done in my Regexper application, just trying it out, check http://www.fukt.hk-r.se/~flognat/hacks/Regexer3.py. Another way to use this could also be text displayed when issuing a application -h, instead of needing a bunch of print statements, it could print out a selection of the __doc__ strings? This is maybe easy to do for one app, but it would maybe be nice having a good browser that people can use, and maybe also the possibility to not only grab the modules doc string, but the other doc strings belonging to classes/imported modules/functions? /Andy -- Hi I am an alien .sig, and at the | Unsolicited commercial email is moment I am having sex to your mind,|subject to an archival fee of $400. by looking at your smile I can see |See www.fukt.hk-r.se/~flognat/mail that you like it. | for more info. ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From x-aes@telelogic.se Wed Nov 20 13:57:20 1996 From: x-aes@telelogic.se (Andy Eskilsson) Date: 20 Nov 1996 14:57:20 +0100 Subject: [PYTHON DOC-SIG] Self-documenting code.. :-) In-Reply-To: "Andy Eskilsson's message of Tue, 19 Nov 1996 10:56:50 +0100 References: Message-ID: Thinking a bit more.. what would be nice is some kind of browser that could be used for example by developers, they do 'helpbrowse script.py', up pops a window that contains the 'master' doc-string (maybe 'folded' in some way) of script.py, and from there links to the function/class doc-strings, also links to imported modules, so they can be browsed. Hopefully this is done so it is possible to use it from a unix-prompt, not only under some window manager. Michael suggested using the grail textwidget, sounds like a good idea, will take a look, but I would like to emphasize that the 'markup' language should be the same as the one agreed on for python sources. /Andy p.s. Hmm people want to have the documentation outside the python code, maybe add ability to browse external files too, sort of, tada.. the problem with documentation for 'external' modules is solved.. hmm -- Hi I am an alien .sig, and at the | Unsolicited commercial email is moment I am having sex to your mind,|subject to an archival fee of $400. by looking at your smile I can see |See www.fukt.hk-r.se/~flognat/mail that you like it. | for more info. ================= 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 Wed Nov 20 14:55:47 1996 From: fdrake@CNRI.Reston.Va.US (Fred L. Drake) Date: Wed, 20 Nov 1996 09:55:47 -0500 (EST) Subject: [PYTHON DOC-SIG] Self-documenting code.. :-) In-Reply-To: from "Andy Eskilsson" at Nov 20, 96 02:57:20 pm Message-ID: <199611201455.JAA06928@weyr.CNRI.Reston.Va.US> > Michael suggested using the grail textwidget, sounds like a good idea, > will take a look, but I would like to emphasize that the 'markup' > language should be the same as the one agreed on for python sources. Andy, Try writing a "parser" for the text/x-python MIME type for Grail; this should be sufficient. The class used for Grail could simply be a Tkinter-using subclass of a more general base class for Python source browsing, and another subclass could be written for curses or whatever. Perhaps the gendoc package or the even the parser module documentation might provide some useful ideas. -Fred -- Fred L. Drake, Jr. fdrake@cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191-5434 ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org ================= From x-aes@telelogic.se Wed Nov 20 15:08:45 1996 From: x-aes@telelogic.se (Andy Eskilsson) Date: 20 Nov 1996 16:08:45 +0100 Subject: [PYTHON DOC-SIG] Self-documenting code.. :-) In-Reply-To: "Fred L. Drake"'s message of Wed, 20 Nov 1996 15:55:47 +0100 References: Message-ID: / "Fred L. Drake" wrote: | > Michael suggested using the grail textwidget, sounds like a good idea, | > will take a look, but I would like to emphasize that the 'markup' | > language should be the same as the one agreed on for python sources. | | Perhaps the gendoc package or the even the parser module | documentation might provide some useful ideas. Hmm I just thought of it targetting the documentation in the python code, but it could probably be easy to show the code too.. and maybe edit it.. and.. uhm get it written.. :-) A close integration to, or at least look at gendoc is a good idea.. if it is what I think it is.. /Andy -- Hi I am an alien .sig, and at the | Unsolicited commercial email is moment I am having sex to your mind,|subject to an archival fee of $400. by looking at your smile I can see |See www.fukt.hk-r.se/~flognat/mail that you like it. | for more info. ================= 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 Wed Nov 20 15:29:33 1996 From: fdrake@CNRI.Reston.Va.US (Fred L. Drake) Date: Wed, 20 Nov 1996 10:29:33 -0500 (EST) Subject: [PYTHON DOC-SIG] Self-documenting code.. :-) In-Reply-To: from "Andy Eskilsson" at Nov 20, 96 04:08:45 pm Message-ID: <199611201529.KAA07166@weyr.CNRI.Reston.Va.US> > Hmm I just thought of it targetting the documentation in the python > code, but it could probably be easy to show the code too.. and maybe > edit it.. and.. uhm get it written.. :-) Sounds like some folding modes are in order. The reason I suggest the parser module is that what you end up working with is structured exactly as the interpreter sees it; you could create an augmented parse tree with any additional display and folding information you need fairly easily, and filling in something like a Tkinter.Text widget becomes a depth-first traversal of the tree. > A close integration to, or at least look at gendoc is a good idea.. if > it is what I think it is.. There might be some usable intermediate structures which can be used. Also, gendoc allows you to work by either parsing source files or importing them, depending on whether the code is trusted. -Fred -- Fred L. Drake, Jr. fdrake@cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191-5434 ================= DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org =================