From guido@CNRI.Reston.Va.US Tue Apr 1 03:42:28 1997 From: guido@CNRI.Reston.Va.US (Guido van Rossum) Date: Mon, 31 Mar 1997 22:42:28 -0500 Subject: [PYTHON DOC-SIG] Documentation enhancements In-Reply-To: Your message of "Mon, 31 Mar 1997 17:34:25 EST." <199703312234.RAA08427@lemur.magnet.com> References: <199703312234.RAA08427@lemur.magnet.com> Message-ID: <199704010342.WAA05625@monty> > I've found a publisher who's somewhat interested in producing a > printed version of the Python docs, though nothing is certain yet. In > the knowledge that there may be a printed version of the 1.5 docs, > what changes should be made? > > Gabriel Berriz made some excellent suggestions, where the priority is > improving the index and adding cross-references from module to module. > (For example, the rand module would also reference random.py and > whrandom.py. Michael K. Johnson at Red Hat independently suggested > the same improvement.) I don't like writing documentation much, and indexing is the most boring part of documentation :-( So any help here would be appreciated. The best way to index, I've been told, is for someone to make a separate pass over the complete text when it's finished. (However, O'Reilly did this for PP and the resulting index in the first printing is considered somewhat lacking by most.) > Regarding a printed version, what should be in it? Probably the big 4 > should all be included: library, reference, extension manual, and > tutorial. (Or can the tutorial be left out? I'd vote no, but...) It should be in! Makes it more valuable by itself. > Are there other documents that should be included? Possibilities: > > * qua.tex No, no, no! > * The man page for the Python interpreter Yes. > * Documentation for the matrix extensions? PIL? Something > else? The Tkinter lifesaver, if someone can be bothered to upgrade it to Tk 4.x. I think NumPy and PIL are a bit too specialized. (In fact, some chapters of the library manual, e.g. the SGI and Mac specific parts, might be left out too.) > * Is there Windows or Mac documentation that could/should be > included? Hmm, not sure. Probably a specialized audience that requires special catering anyway. But maybe Mark Hammond has something to add and we could increase the audience 10-fold this way. --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 guido@CNRI.Reston.Va.US Tue Apr 1 03:46:07 1997 From: guido@CNRI.Reston.Va.US (Guido van Rossum) Date: Mon, 31 Mar 1997 22:46:07 -0500 Subject: [PYTHON DOC-SIG] Documentation enhancements In-Reply-To: Your message of "Mon, 31 Mar 1997 18:06:07 EST." References: Message-ID: <199704010346.WAA05660@monty> > > I've found a publisher who's somewhat interested in producing a > > printed version of the Python docs, though nothing is certain yet. In > > the knowledge that there may be a printed version of the 1.5 docs, > > what changes should be made? > > I for one would want to make sure that we don't rush into something like > this without making sure that the product is high-quality. I agree with > ,I think it was you, Andrew, that the docs need a typesetting makeover at > the very least. I also feel that the tutorial badly needs an overhaul -- > right now most of the good stuff is in "and then we added ..." sections, > which gives the wrong impression. I realize that the author of the > tutorial (GvR) is too busy, but I do think it's an important and needed > change... Yes, and yes... :-( > BTW: the reason I think it's important to do a good job is that I think > this sort of product has a much bigger PR effect than one might think -- > and first impressions count a lot. Hmm, I'm not sure. We don't have a marketing organization like O'Reilly, and we'll probably mostly sell to people who already like Python but don't have the resources to print the docs themselves. So I don't think it will be a big PR item. --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 da@maigret.cog.brown.edu Tue Apr 1 04:22:44 1997 From: da@maigret.cog.brown.edu (David Ascher) Date: Mon, 31 Mar 1997 23:22:44 -0500 (EST) Subject: [PYTHON DOC-SIG] Documentation enhancements In-Reply-To: <199704010342.WAA05625@monty> Message-ID: > I don't like writing documentation much, and indexing is the most > boring part of documentation :-( So any help here would be > appreciated. The best way to index, I've been told, is for someone to > make a separate pass over the complete text when it's finished. > (However, O'Reilly did this for PP and the resulting index in the > first printing is considered somewhat lacking by most.) In this case, it might be possible to use technology -- we could ask the python-list readers (and tchrist, why not =) to email a list of terms they would want to an automatic email processing system which could remove duplicates -- it might yield some 'collective insight' -- I especially think that the input of novices is most useful for this kind of thing (assuming that the input of experts is included as a matter of course). > The Tkinter lifesaver, if someone can be bothered to upgrade it to Tk > 4.x. I think NumPy and PIL are a bit too specialized. Agreed -- I think that whoever added 15 pages to the Tkinter lifesaver would make a lot of people very happy (and I mean a little more than just Tk 4.x compatibility). Don't look at me -- I got a dissertation to write, and then some... --david _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From MHammond@skippinet.com.au Tue Apr 1 07:34:44 1997 From: MHammond@skippinet.com.au (Mark Hammond) Date: Tue, 1 Apr 1997 17:34:44 +1000 Subject: [PYTHON DOC-SIG] Documentation enhancements Message-ID: <199704010739.RAA20701@minotaur.labyrinth.net.au> > > * Is there Windows or Mac documentation that could/should be > > included? > > Hmm, not sure. Probably a specialized audience that requires special > catering anyway. But maybe Mark Hammond has something to add and we > could increase the audience 10-fold this way. Not much. Everything I have is at the Pythonwin pages, and thats not a real lot. Im unlikely to do much on this (soon to start on a "Python and ActiveX" book :-) But you are welcome to it. Mark. _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From fredrik_lundh@ivab.se Tue Apr 1 08:13:17 1997 From: fredrik_lundh@ivab.se (Fredrik Lundh) Date: Tue, 1 Apr 1997 10:13:17 +0200 Subject: [PYTHON DOC-SIG] Documentation enhancements In-Reply-To: (message from David Ascher on Mon, 31 Mar 1997 23:22:44 -0500 (EST)) Message-ID: <9704010813.AA06728@arnold.image.ivab.se> > Agreed -- I think that whoever added 15 pages to the Tkinter > lifesaver would make a lot of people very happy (and I mean a little > more than just Tk 4.x compatibility). Don't look at me -- I got a > dissertation to write, and then some... Working on it. A replacement, that is; it has happened a lot since 3.x... Fragments are available at the address below. Comments are welcome. Cheers /F (http://hem1.passagen.se/eff) _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From jeff@ollie.clive.ia.us Tue Apr 1 14:00:50 1997 From: jeff@ollie.clive.ia.us (Jeffrey C. Ollie) Date: Tue, 01 Apr 1997 08:00:50 -0600 Subject: [PYTHON DOC-SIG] Documentation enhancements In-Reply-To: Your message of "Mon, 31 Mar 1997 23:22:44 EST." Message-ID: <199704011400.IAA30323@worf.netins.net> -----BEGIN PGP SIGNED MESSAGE----- On Mon, 31 Mar 1997 23:22:44 -0500 (EST), da@maigret.cog.brown.edu writes: > >> I don't like writing documentation much, and indexing is the most >> boring part of documentation :-( So any help here would be >> appreciated. The best way to index, I've been told, is for someone to >> make a separate pass over the complete text when it's finished. >> (However, O'Reilly did this for PP and the resulting index in the >> first printing is considered somewhat lacking by most.) > >In this case, it might be possible to use technology -- we could ask the >python-list readers (and tchrist, why not =) to email a list of terms they >would want to an automatic email processing system which could remove >duplicates -- it might yield some 'collective insight' -- I especially >think that the input of novices is most useful for this kind of thing >(assuming that the input of experts is included as a matter of course). Even better, some way for people to add concepts (and associated page references) that should be indexed. That would probably require a human editor, though. [A copy of the headers and the PGP signature follow.] Date: Tue, 01 Apr 1997 08:00:50 -0600 From: "Jeffrey C. Ollie" In-reply-to: Your message of "Mon, 31 Mar 1997 23:22:44 EST." Subject: Re: [PYTHON DOC-SIG] Documentation enhancements To: doc-sig@python.org -----BEGIN PGP SIGNATURE----- Version: 2.6.2 Comment: AnySign 1.4 - A Python tool for PGP signing e-mail and news. iQCVAwUBM0EVFpwkOQz8sbZFAQE30AP/SN6p8NptFrx5BSfEfYJX8+WRV5Xr6LKb +ITP7w/ZVLnalUF8QgX3hdyonzF+FNI1mtvS3t8o93Y1DgZtsQwcJCUmp9uIYElr OBl2akoX6a7GkcDttdpI/h82MajBa79rRi8BTulLkSjF/z/NjUQqbB8gyfmXPbsN S8vfNtjb76U= =3Xox -----END PGP SIGNATURE----- -- Jeffrey C. Ollie | Should Work Now (TM) Python Hacker, Mac Lover | _______________ 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 Tue Apr 1 17:36:37 1997 From: amk@magnet.com (Andrew Kuchling) Date: Tue, 1 Apr 1997 12:36:37 -0500 (EST) Subject: [PYTHON DOC-SIG] Documentation enhancements In-Reply-To: <199704010342.WAA05625@monty> from "Guido van Rossum" at Mar 31, 97 10:42:28 pm Message-ID: <199704011736.MAA02236@lemur.magnet.com> G. Berriz also suggested having a note at the start of the index: "If you notice omissions, please help save the world and drop a note to XXX@python.org", where XXX is some mail alias for Guido or an editor, or possibly XXX='doc-sig'. The Tkinter life preserver is something I hadn't thought of; how long is it? (Place reference to the Monty Python lifeboat sketch here.) However, if Frederik is revising it for inclusion in his book, O'Reilly would have to agree to allowing republication of those sections. Regarding the tutorial: the later sections seem to contain two sorts of items. Some are just informational ChangeLog-like things ("The Macintosh version is much more robust now." "The string module now has a capwords() function.") which can be cut out and put in another file, and others are actual language changes, which will need to be integrated into the text. Tutorial readers probably don't care about the interpreter's past history. Guido van Rossum wrote: > (In fact, some chapters of the library manual, e.g. the SGI and Mac > specific parts, might be left out too.) Good point. One might also wonder if the SGI-specific modules should be dropped from the distribution; Python isn't only (or even mostly) on SGIs these days, and time seems to be taking its toll on them---there's a more recent OpenGL interface, PIL for image processing... >So I don't think it will be a big PR item. Ah, but the HTML documentation would also benefit from improvements, and that is highly visible. People may also lend the book to others when evangelizing. Andrew Kuchling amk@magnet.com http://people.magnet.com/%7Eamk/ Save the Gutenberg Project! http://www.promo.net/pg/nl/pgny_nov96.html _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________ From hochberg@wwa.com Wed Apr 2 19:35:25 1997 From: hochberg@wwa.com (Timothy A. Hochberg) Date: Wed, 2 Apr 1997 13:35:25 -0600 (CST) Subject: [PYTHON DOC-SIG] Structured Text to LaTeX converter. Message-ID: I've written a structured text to LaTeX converter. If anyone has any use for it feel free to use it (it's included below), just let me know if it gets used for anything really cool. It looks like some form of this will be incorporated into py2tex so that it formats doc-strings better. So, if anyone on the doc-sig uses LaTeX I'd appreciate them trying this out so I can shake out all the bugs. Thanks, -tim --cut-me----------------------------------------------- """Convert structured text to LaTeX. *LaTeX* - A class that converts structured text (cf. the "doc-sig") into a format readable by LaTeX. Based on the class *HTML* authored by Jim Fulton which appears in *StructuredText.py*. Usage (this is long and rambling so I can test it with itself...): 1. Put *struct2latex.py* someplace that python and can find it. 2. Create your LaTeX file by: a. Creating a **LaTeX** object (e.g., 'st = LaTeX(string)'). b. Getting the LaTeXified string by converting the **LaTeX object to a string (.e.g, 'lt = str(st)' or 'print st'). c. Save your LaTeXified string somewhere. 3. You should be able to include the LaTeX text in any LaTeX file. Two ways I use it are: * Use the text by itself by putting it in a stub file. For example:: \\documentstyle[11pt]{article} \\begin{document} \\include{docstring} \\end{document} * I'm using use it to support structured text in *py2tex*. 4. Run LaTeX. 5. Once you have a dvi file your on your own.... There are some caveats (of course): Characters -- I believe all the LaTeX special characters (&%#_{}~^\) should be properly escaped (with the exception of $ - see below, but no guarantees. * And now it should allow bullet lists that are adjacent to work. * This is provided by the magic of regsub.gsub. * But who knows it may have some horrible side effects... Equations -- I thought, ``as long as we're using LaTeX, we should have access to equations.'' So, '$' is used to invoke math mode, just as in LaTeX. For example, '$x = \oint y\,dy$' produces $x = \oint y\,dy$. $ obeys the same rules as ', so you usually shouldn't have to quote it - although that would probably be safer... Quotes -- The normal LaTeX style quotes work fine as long as there is no white space inside the quote ( ' ). .. "doc-sig" http://www.python.org/sigs/doc-sig/ """ import regex, regsub, string import StructuredText ST = StructuredText href_re = regex.compile('[.][.] \(".+"\)[ \t]*\(.*\)\n') line2_re = regex.compile('.*\n\([ \t]*\n\)*\([ \t]*\)') slashable_re = regex.compile('[$&%#_{}]') quotable_re = regex.compile('[~^\\]') eqn_re = regex.compile("[ \t\n(]$\([^ \t$]\([^\n']*[^ \t']\)?\)$\([) \t\n,.:;!?]\)") carrot_re = regex.compile("\\^") expand_bullet=regex.compile('\n[ \t\n]*[o*-][ \t\n]') expand_deflist=regex.compile('\n[ \t\n]*[^\n]+[ \t]+--[ \t\n]') def _split(s): """Split a string into normal and quoted pieces. Splits a string into normal and quoted (or math mode) sections. Returns a list where the even elements are normal text, and the odd elements are quoted. The appropiate quote tags ($ and \\verb) are applied to the quoted text. """ r = [] while 1: epos = eqn_re.search(s) qpos = ST.code.search(s) if epos == qpos: ## == -1 break elif (qpos == -1) or (epos != -1 and epos < qpos): r.append(s[:epos]) end = epos + eqn_re.match(s[epos:]) arg = [eqn_re.group(1), eqn_re.group(3)] if not arg[1]: arg[1] = '' r.append( ' $%s$%s ' % tuple(arg)) else: ## (epos==-1) or (qpos != -1 and epos > qpos): r.append(s[:qpos]) end = qpos + ST.code.match(s[qpos:]) arg = [regsub.gsub(carrot_re, '^\\verb@\\0@\\verb^', ST.code.group(1)), ST.code.group(3)] if not arg[1]: arg[1] = '' r.append(' \\verb^%s^%s ' % tuple(arg)) s = s[end:] r.append(s) return r def _ctag(str, hrefs=()): """Quote, tag, and escape the text. This is a modified version of the 'ctag' function appearing in StructuredText.py. The differences include, * it uses _split, so that it avoids escaping text in quotes or in math-mode. * it processes hrefs. * it escapes LaTeX special characters. * it doesn't try to find duplicate list items - that got moved into LaTeX. """ if str is None: str = '' str = ' %s' % str # prepend a space str = _split(str) for i in xrange(len(str)): if not i%2: str[i]=regsub.gsub(quotable_re, '\\verb@\\0@', str[i]) str[i]=regsub.gsub(slashable_re, '\\\\\\0', str[i]) str[i]=regsub.gsub(ST.strong,' {\\bfseries \\1}\\2', str[i]) str[i]=regsub.gsub(ST.em,' {\\itshape \\1}\\2',str[i]) for ref, link in hrefs: tag = '{\slshape %s}\\footnote{%s}' % (ref[1:-1], link) str[i] = string.joinfields(string.split(str[i], ref), tag) return string.joinfields(str) def _strip_hrefs(string): """Strip hrefs out of a string. Strip the hrefs of the form '.. "tag" url' out of *string*. Return string, as well as a dictionary containing the stripped references. """ hrefs = [] s = string l = href_re.search(s) while l != -1: hrefs.append(href_re.group(1,2)) s = s[l+1:] l = href_re.search(s) string = regsub.gsub(href_re, '', string) return string, hrefs def _separate_bullets(string): """Separate list items by a newline.""" string = regsub.gsub(expand_bullet, '\n\\0', string) string = regsub.gsub(expand_deflist, '\n\\0', string) return string class LaTeX(ST.StructuredText): """Translate StructuredText to LaTeX. This is loosely based on Jim Fulton's class HTML. """ def __init__(self, aStructuredString, level=1, isdoc=1): """Create a LaTeX object.""" self.level = level aStructuredString = ST.untabify(aStructuredString) if isdoc: if line2_re.match(aStructuredString) != -1: aStructuredString = line2_re.group(2) + aStructuredString aStructuredString, self.hrefs = _strip_hrefs(aStructuredString) aStructuredString = _separate_bullets(aStructuredString) paragraphs = regsub.split(aStructuredString, ST.paragraph_divider) paragraphs = map(ST.indent_level, paragraphs) self.structure = ST.structure(paragraphs) def _str(self,structure,level): """Translate *structure* to LaTeX. Driver for the translation. Based on HTML._str. Differences include: 1. changed the handling of examples so that bullets could have examples too. """ if type(structure) == type(''): return structure r='' for s in structure: ##print s[0],'\n', len(s[1]), '\n\n' if ST.example.search(s[0]) >= 0 and s[1]: s0, s1 = s[0], self.pre(s[1]) elif s[0][-2:]=='::' and s[1]: s0, s1 = s[0][:-1], self.pre(s[1]) else: s0, s1 = s[0], s[1] # if ST.bullet.match(s0) >= 0: p=ST.bullet.group(1) r=self.ul(r,p,self._str(s1,level)) elif ST.ol.match(s0) >= 0: p=ST.ol.group(3) r=self.ol(r,p,self._str(s1,level)) elif ST.olp.match(s0) >= 0: p=ST.olp.group(1) r=self.ol(r,p,self._str(s1,level)) elif ST.dl.match(s0) >= 0: t,d=ST.dl.group(1,2) r=self.dl(r,t,d,self._str(s1,level)) elif ST.nl.search(s0) < 0 and s1: # Treat as a heading t=s0 r=self.head(r,t,level,self._str(s1,level+1)) else: r=self.normal(r,s0,self._str(s1,level)) return r def ul(self, before, p, after): """Process an unordered list.""" if before[-14:] == '\\end{itemize}\n': return ('%s\n\\item %s%s\n\n\\end{itemize}\n' % (before[:-15],_ctag(p, self.hrefs),after)) else: return ('%s\\begin{itemize}\n\n\\item %s%s\n\n\\end{itemize}\n' % (before,_ctag(p, self.hrefs),after)) def ol(self, before, p, after): """Process an ordered list.""" if before[-16:] == '\\end{enumerate}\n': return ('%s\n\\item %s%s\n\n\\end{enumerate}\n' % (before[:-16],_ctag(p, self.hrefs),after)) else: return ('%s\\begin{enumerate}\n\n\\item %s%s\n\n\\end{enumerate}\n' % (before,_ctag(p, self.hrefs),after)) def dl(self, before, t, d, after): """Process a description list.""" if before[-18:] == '\\end{description}\n': return ('%s\n\\item[%s]%s%s\n\n\\end{description}\n' % (before[:-18], _ctag(t, self.hrefs), _ctag(d, self.hrefs),after)) else: return ('%s\\begin{description}\n\n\\item[%s]%s%s\n\n\\end{description}\n' % (before,_ctag(t, self.hrefs),_ctag(d, self.hrefs),after)) def head(self, before, t, level, d): """Process a heading.""" t="{\\bfseries %s }" % _ctag(t, self.hrefs) return ('%s\\begin{description}\n\\item[%s]\\ \n\n%s\n\\end{description}\n' % (before,t,d)) def normal(self,before,p,after): """Process a normal paragraph.""" return '%s\n%s\n%s\n' % (before,_ctag(p, self.hrefs),after) def pre(self,structure,tagged=0): """Process some pre-formatted (example) text.""" if not structure: return '' if tagged: r='' else: r='\\begin{verbatim}\n' for s in structure: r="%s%s\n\n%s" % (r,s[0],self.pre(s[1],1)) if not tagged: r=r+'\\end{verbatim}\n' return r def __str__(self): """Return the translated text.""" return self._str(self.structure,self.level) if __name__ == '__main__': print LaTeX(__doc__) _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________