From skip@mojam.com (Skip Montanaro) Tue Mar 2 14:19:04 1999 From: skip@mojam.com (Skip Montanaro) (skip@mojam.com (Skip Montanaro)) Date: Tue, 2 Mar 1999 09:19:04 -0500 Subject: [Doc-SIG] Reference Counting "reference"? Message-ID: <199903021419.JAA06774@dolphin.calendar.com> I don't write tons of extension modules, so Python's reference counting details aren't emblazoned on my frontal lobe or encoded in my DNA. Whenever I have trouble with refcounts I find I also have trouble figuring out what the behavior of various functions is by reading the documentation. While there are a couple treatises on reference counting http://www.python.org/doc/api/refcountDetails.html http://www.python.org/doc/ext/refcounts.html in the docs, I generally still have trouble finding what I'm looking for and find I have to reread all the available materials pretty carefully to convince myself I understand things. (It would be nice if there was only a single treatise with pointers from other places...) I would find it helpful to have one table that identifies the exceptional cases. This table could have columns for "return borrowed" and "steal reference": Function returns steals or Macro borrowed reference ----------------------------------------------------- PyList_SetItem XXX PyTuple_SetItem XXX PyList_GetItem XXX PyTuple_GetItem XXX PyList_SET_ITEM XXX PyTuple_SET_ITEM XXX It may be that those functions and macros are the only special cases. A simple footnote that indicates that all other functions borrow input arguments and return owned references would suffice to sum up the entire state of affairs for someone needing to look up the behavior of a particular function they are unsure about. Skip Montanaro | Mojam: "Uniting the World of Music" http://www.mojam.com/ skip@mojam.com | Musi-Cal: http://www.musi-cal.com/ 518-372-5583 From Fred L. Drake, Jr." After much thought, I have decided to violently overthrow the current leadership of this SIG... what's that? I can have it for the asking? Well, anyway, I am now the SIG "champion"; Mike agreed that perhaps I could handle it, so we've turned over the mailing list. I hope to spend some time on the Web pages over the next couple of weeks. Any questions should be addressed to the SIG or to doc-sig-owner@python.org. -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191 From da@ski.org Wed Mar 3 00:52:35 1999 From: da@ski.org (David Ascher) Date: Tue, 2 Mar 1999 16:52:35 -0800 (Pacific Standard Time) Subject: [Doc-SIG] \begin{interactive} Message-ID: This message is in MIME format. The first part should be readable text, while the remaining parts are likely unreadable without MIME-aware tools. Send mail to mime@docserver.cac.washington.edu for more info. --15889198-29424-920422355=:222 Content-Type: TEXT/PLAIN; charset=US-ASCII Here's my hack for the day. I keep writing doc, and I'm always frustrated when there's a mismatch between the stuff that the user is supposed to have input and the output that is shown. Here's a solution for LaTeX documents: The comment below should explain it to the LaTeXgnescenti. Comments welcome. ######################################################################## # # Latex Python Preprocessor For Interactive Accuracy # (c) 1999 David Ascher # # Take a set of latex files and convert blocks that look like: # # \begin{interactive} # x = 3 # print x # here's a comment # x / 0 # \end{interactive} # # to: # # \begin{interactive} # x = 3 # print x # here's a comment # x / 0 # \end{interactive} # # \begin{interactiveoutput} # >>> \textbf{x = 3} # >>> \textbf{print x }\textit{\# here's a comment} # 3 # >>> \textbf{x / 0} # Traceback (innermost last): # File "", line 1, in ? # ZeroDivisionError: integer division or modulo # \end{interactiveoutput} # # # Assumes that the following are in the preamble: # # \usepackage{alltt} # \usepackage{verbatim} # \newenvironment{interactive}{\comment}{\endcomment} # \newenvironment{interactiveoutput}{\alltt}{\endalltt} # ######################################################################## --15889198-29424-920422355=:222 Content-Type: TEXT/plain; name="proc.py" Content-Transfer-Encoding: BASE64 Content-ID: Content-Description: Content-Disposition: attachment; filename="proc.py" IyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMj IyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjDQojDQojIExhdGV4IFB5dGhv biBQcmVwcm9jZXNzb3IgRm9yIEludGVyYWN0aXZlIEFjY3VyYWN5DQojIChj KSAxOTk5IERhdmlkIEFzY2hlcg0KIw0KIyBUYWtlIGEgc2V0IG9mIGxhdGV4 IGZpbGVzIGFuZCBjb252ZXJ0IGJsb2NrcyB0aGF0IGxvb2sgbGlrZToNCiMN CiMgICAgXGJlZ2lue2ludGVyYWN0aXZlfQ0KIyAgICB4ID0gMw0KIyAgICBw cmludCB4DQojICAgIHggLyAzDQojICAgIFxlbmR7aW50ZXJhY3RpdmV9DQoj DQojIHRvOiANCiMNCiMgICAgXGJlZ2lue2ludGVyYWN0aXZlfQ0KIyAgICB4 ID0gMw0KIyAgICBwcmludCB4ICAgIyBoZXJlJ3MgYSBjb21tZW50DQojICAg IHggLyAwDQojICAgIFxlbmR7aW50ZXJhY3RpdmV9DQojDQojICAgIFxiZWdp bntpbnRlcmFjdGl2ZW91dHB1dH0NCiMgICAgICAgICA+Pj4gXHRleHRiZnt4 ID0gM30NCiMgICAgICAgICA+Pj4gXHRleHRiZntwcmludCB4ICAgfVx0ZXh0 aXR7XCMgaGVyZSdzIGEgY29tbWVudH0NCiMgICAgICAgICAzDQojICAgICAg ICAgPj4+IFx0ZXh0YmZ7eCAvIDB9DQojICAgICAgICAgVHJhY2ViYWNrIChp bm5lcm1vc3QgbGFzdCk6DQojICAgICAgICAgRmlsZSAiPGNvbnNvbGU+Iiwg bGluZSAxLCBpbiA/DQojICAgICAgICAgWmVyb0RpdmlzaW9uRXJyb3I6IGlu dGVnZXIgZGl2aXNpb24gb3IgbW9kdWxvDQojICAgIFxlbmR7aW50ZXJhY3Rp dmVvdXRwdXR9DQojDQojDQojIEFzc3VtZXMgdGhhdCB0aGUgZm9sbG93aW5n IGFyZSBpbiB0aGUgcHJlYW1ibGU6DQojDQojICBcdXNlcGFja2FnZXthbGx0 dH0NCiMgIFx1c2VwYWNrYWdle3ZlcmJhdGltfQ0KIyAgXG5ld2Vudmlyb25t ZW50e2ludGVyYWN0aXZlfXtcY29tbWVudH17XGVuZGNvbW1lbnR9DQojICBc bmV3ZW52aXJvbm1lbnR7aW50ZXJhY3RpdmVvdXRwdXR9e1xhbGx0dH17XGVu ZGFsbHR0fQ0KIw0KIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMj IyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjICANCg0K aW1wb3J0IHN0cmluZywgc3lzLCBjb2RlLCBjU3RyaW5nSU8NCg0KaSA9IGNv ZGUuSW50ZXJhY3RpdmVDb25zb2xlKCkNCnN5cy5wczEgPSAnPj4+ICcNCnN5 cy5wczIgPSAnLi4uICcNCg0KQkkgPSByJ1xiZWdpbntpbnRlcmFjdGl2ZX0n KydcbicNCkVJID0gcidcZW5ke2ludGVyYWN0aXZlfScrJ1xuJw0KQk8gPSBy J1xiZWdpbntpbnRlcmFjdGl2ZW91dHB1dH0nKydcbicNCkVPID0gcidcZW5k e2ludGVyYWN0aXZlb3V0cHV0fScrJ1xuJw0KDQpkZWYgZG9wYXJ0KHBhcnQp Og0KICAgIHBhcnQgPSBzdHJpbmcucmVwbGFjZShwYXJ0LCAnXHJcbicsICdc bicpDQogICAgcGFydCA9IHN0cmluZy5yZXBsYWNlKHBhcnQsICdcblxyJywg J1xuJykNCiAgICBpZiBwYXJ0WzBdID09ICdcbic6IHBhcnQgPSBwYXJ0WzE6 XQ0KICAgIGlmIHBhcnRbLTFdID09ICdcbic6IHBhcnQgPSBwYXJ0WzotMV0N Cg0KICAgIHByb21wdCA9IHN5cy5wczENCiAgICB2ID0gJycNCiAgICBmb3Ig bGluZSBpbiBzdHJpbmcuc3BsaXQocGFydCwgJ1xuJyk6DQoJbyA9IGNTdHJp bmdJTy5TdHJpbmdJTygpDQoJZSA9IGNTdHJpbmdJTy5TdHJpbmdJTygpDQoJ c3Rkb3V0ID0gc3lzLnN0ZG91dA0KCXN5cy5zdGRvdXQgPSBvDQoJc3RkZXJy ID0gc3lzLnN0ZGVycg0KCXN5cy5zdGRlcnIgPSBlDQoJcHJpbnQgcHJvbXB0 K3InXHRleHRiZnsnK2xpbmUrJ30nDQoJbW9yZSA9IGkucHVzaChsaW5lKQ0K CW92ID0gby5nZXR2YWx1ZSgpDQoJZXYgPSBlLmdldHZhbHVlKCkNCgl3ID0g c3RyaW5nLmZpbmQoZXYsICcjJykgICMgY29tbWVudHMgYXJlbid0IGFjdHVh bGx5IHNob3duIGluIHRiLg0KCWlmIHcgIT0gLTE6DQoJICAgIGV2ID0gZXZb OnctMV0NCglzeXMuc3Rkb3V0ID0gc3Rkb3V0DQoJc3lzLnN0ZGVyciA9IHN0 ZGVycg0KCXYgPSB2ICsgIG92ICsgZXYNCglpZiB2Wy0xXSAhPSAnXG4nOiB2 ID0gdiArICdcbicNCglpZiBtb3JlOiANCgkgICAgcHJvbXB0ID0gc3lzLnBz Mg0KCWVsc2U6DQoJICAgIHByb21wdCA9IHN5cy5wczENCgkNCiAgICBsaW5l cyA9IHN0cmluZy5zcGxpdCh2LCAnXG4nKQ0KICAgIGRlZiBpdGFsaWNpemVf Y29tbWVudHMobGluZSk6DQoJaWYgJyMnIGluIGxpbmU6DQoJICAgIHdoZXJl ID0gc3RyaW5nLmluZGV4KGxpbmUsICcjJykNCgkgICAgaWYgc3RyaW5nLmZp bmQobGluZSwgcidcdGV4dGJmJykgPj0gMDoNCgkJbGluZSA9IGxpbmVbOndo ZXJlXSArIHInfVx0ZXh0aXR7JytsaW5lW3doZXJlOl0NCgkgICAgZWxzZToN CgkJbGluZSA9IGxpbmVbOndoZXJlXSArIHInXHRleHRpdHsnK2xpbmVbd2hl cmU6XSsnfScNCglyZXR1cm4gbGluZQ0KICAgIGxpbmVzID0gbWFwKGl0YWxp Y2l6ZV9jb21tZW50cywgbGluZXMpDQogICAgdiA9IHN0cmluZy5qb2luKGxp bmVzLCAnXG4nKQ0KICAgIHYgPSBzdHJpbmcucmVwbGFjZSh2LCAnIycsICdc IycpDQogICAgZGVmIGFkZF9pbmRlbnQoeCk6DQoJaWYgeDoNCgkgICAgcmV0 dXJuICcgICAgJyt4DQoJZWxzZToNCgkgICAgcmV0dXJuIHgNCiAgICB2ID0g c3RyaW5nLmpvaW4obWFwKGFkZF9pbmRlbnQsIHN0cmluZy5zcGxpdCh2LCAn XG4nKSksICdcbicpDQogICAgcmV0dXJuIEJJICsgcGFydCArICdcbicgKyBF SSArICdcbicgKyBCTyArIHYgKyBFT1s6LTFdDQoNCmRlZiBkbyhmaWxlbmFt ZSk6DQogICAgZCA9IG9wZW4oZmlsZW5hbWUpLnJlYWQoKQ0KDQogICAgIyBz dHJpcCBpbnRlcmFjdGl2ZV9vdXRwdXQgcmVnaW9ucw0KICAgIHdoaWxlIDE6 DQoJdyA9IHN0cmluZy5maW5kKGQsIEJPKQ0KCWlmIHcgPT0gLTE6DQoJICAg IGJyZWFrDQoJayA9IHN0cmluZy5maW5kKGQsIEVPKQ0KCWlmIGsgPT0gLTE6 DQoJICAgIHJhaXNlIFZhbHVlRXJyb3IsICJVbmFibGUgdG8gZmluZCBlbmQg b2YgaW50ZXJhY3RpdmVfb3V0cHV0IHJlZ2lvbiINCglkID0gZFs6d10gKyBk W2srbGVuKEVPKTpdDQoNCiAgICBwYXJ0cyA9IHN0cmluZy5zcGxpdChkLCBC SSkNCiAgICBuID0gJycNCiAgICBmb3IgcGFydCBpbiBwYXJ0czoNCgl3ID0g c3RyaW5nLmZpbmQocGFydCwgRUkpDQoJaWYgdyA9PSAtMTogDQoJICAgIG5w YXJ0ID0gcGFydA0KCWVsc2U6DQoJICAgIG5wYXJ0ID0gZG9wYXJ0KHBhcnRb OnddKSArIHBhcnRbdytsZW4oRUkpOl0NCgluID0gbiArIG5wYXJ0DQogICAg IyBpZiB5b3Ugd2FudCB0byBwbGF5IHdpdGggZmlyZToNCiAgICAjZiA9IG9w ZW4oZmlsZW5hbWUsICd3YicpDQogICAgIyBlbHNlOiANCiAgICBmID0gb3Bl bihmaWxlbmFtZVs6LTRdKyctMi50ZXgnLCAnd2InKQ0KICAgIGYud3JpdGUo bikNCg0KZm9yIGZpbGVuYW1lIGluIHN5cy5hcmd2WzE6XToNCiAgICBkbyhm aWxlbmFtZSkNCg0K --15889198-29424-920422355=:222-- From se6y095@public.uni-hamburg.de Thu Mar 4 15:42:41 1999 From: se6y095@public.uni-hamburg.de (Berthold =?iso-8859-1?Q?H=F6llmann?=) Date: Thu, 04 Mar 1999 16:42:41 +0100 Subject: [Doc-SIG] \begin{interactive} References: Message-ID: <36DEA9F1.A71C1B99@public.uni-hamburg.de> David Ascher wrote: > > Here's my hack for the day. I keep writing doc, and I'm always frustrated > when there's a mismatch between the stuff that the user is supposed to > have input and the output that is shown. Here's a solution for LaTeX > documents: > > The comment below should explain it to the LaTeXgnescenti. > > Comments welcome. > Hello David, hello all, I took "proc.py" and developed "LaTeXPy.py" on it's ideas and code. I also added "python.sty", which simply defines the preamble options. "LaTeXPy.py" is not only ment to be used for python documentation, but also for documents where som calculation is neede. The new "Python" environment is used to execute some python code without leaving any trace in the generated LaTeX file, the command "\CallPython" is ment to insert python output into the LaTeX file. A function "PyLaTeX" can be called to escape special characters. As an Example, if you want to get a pair of curly braces in the LaTeX output take this LaTeX input: --- snip --- \documentclass[a4paper]{article} \usepackage{python} \begin{document} \begin{Python} import LaTeXPy \end{Python} \CallPython{LaTeXPy.PyLaTeX('{}')} \end{document} --- snip --- creates as output: --- snip --- \documentclass[a4paper]{article} \usepackage{python} \begin{document} \begin{Python} import LaTeXPy \end{Python} \CallPython[{\{\}}]{LaTeXPy.PyLaTeX('{}')} \end{document} --- snip --- The package PyLaTeX-1.0 on my starship.python home contains UnitPrint, which allowes nice formatting of Floats, Integers and PhysicalQuantities (from Konrad Hinsen's ScientificPyton modules). LaTeX.py on my homepage is ment to generate LaTeX files from python. I'm not shure, which is the better srategy, to write a python file with strings containing the LaTeX commands, or to write a LaTeX file with embedded python code. Any comments are welcome Cheers Berthold -- bhoel@starship.python.net http://starship.python.net/crew/bhoel/ It is unlawful to use this email address for unsolicited ads (USC Title 47 Sec.227). I will assess a US$500 charge for reviewing and deleting each unsolicited ad. From Fred L. Drake, Jr." A few people on the list owe me sections of documentation on various modules. How are those coming along? -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From skip@mojam.com (Skip Montanaro) Thu Mar 11 19:50:47 1999 From: skip@mojam.com (Skip Montanaro) (skip@mojam.com (Skip Montanaro)) Date: Thu, 11 Mar 1999 14:50:47 -0500 Subject: [Doc-SIG] A couple documentation questions Message-ID: <199903111950.OAA15981@dolphin.calendar.com> Fred's note motivated me to return to work on the two sections he assigned me. I have a couple questions... 1. Are there any standards or conventions for module documentation? I thought there used to be a template doc file named libxxmodule.tex file that you could use as a starting point, but I couldn't find anything that looked promising. For now I'm just poking around the other module doc files and sort of following my nose. 2. How do people test what they've written? It takes forever to format the entire manual. I quickly tried creating a libsmall.tex file that's lib.tex with just my modules, but "make libsmall.ps" fails in both the paper-letter and lib directories. I guess that route will require some Makefile fiddling. It would be nice if there were already default targets for the common chain .tex -> .dvi -> .ps. Skip From Fred L. Drake, Jr." References: <199903111950.OAA15981@dolphin.calendar.com> Message-ID: <14056.13771.940229.849492@weyr.cnri.reston.va.us> skip@mojam.com writes: > 1. Are there any standards or conventions for module documentation? > I thought there used to be a template doc file named libxxmodule.tex See the file Doc/templates/module.tex; there are extensive comments in the file. Where there are gaps, send a note to me or the SIG. Where the comments can be improved, I'll be glad to do so. > 2. How do people test what they've written? It takes forever to format > the entire manual. I quickly tried creating a libsmall.tex file > that's lib.tex with just my modules, but "make libsmall.ps" fails in > both the paper-letter and lib directories. I guess that route will > require some Makefile fiddling. It would be nice if there were > already default targets for the common chain .tex -> .dvi -> .ps. Probably the easiest way, if the speed is a problem for you, is to create a short "howto" style document. Use Doc/mac/mac.tex as a template. The point Doc/tool/mkhowto (or Doc/tools/mkhowto.sh if you're not using the CVS repo) at the top-level .tex file. Use the --help option for usage information. If even that proves too painful or if you encounter difficulties, do what you can by inspection and then send it to me; I'll be reviewing the markup anyway. It'll also help me develop better tools for dealing with all this stuff. (The mkhowto script should pretty well take care of everything, though.) -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives