Mailman 3 March 1999 - Doc-SIG

A couple documentation questions
by skip＠mojam.com March 11, 1999

March 11, 1999

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

2 1

Documentation sections
by Fred L. Drake March 11, 1999

March 11, 1999

A few people on the list owe me sections of documentation on various modules. How are those coming along? -Fred -- Fred L. Drake, Jr. <fdrake(a)acm.org> Corporation for National Research Initiatives

1 0

\begin{interactive}
by David Ascher March 4, 1999

March 4, 1999

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 "<console>", 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} # ########################################################################

2 1

Doc-SIG Takeover
by Fred L. Drake March 2, 1999

March 2, 1999

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(a)python.org. -Fred -- Fred L. Drake, Jr. <fdrake(a)acm.org> Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191

1 0

Reference Counting "reference"?
by skip＠mojam.com March 2, 1999

March 2, 1999

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(a)mojam.com | Musi-Cal: http://www.musi-cal.com/ 518-372-5583

1 0