Mailman 3 April 2002 - Doc-SIG

Error in pyexpat docs
by uche.ogbuji＠fourthought.com July 9, 2002

July 9, 2002

An excerpt from the Python 2.0 docs for pyexpat: """ ParseFile (file) Parse XML data reading from the object file. file only needs to provide the read(nbytes) method, returning the empty string when there's no more data. [snip] The following attributes contain values relating to the most recent error encountered by an xmlparser object, and will only have correct values once a call to Parse() or ParseFile() has raised a xml.parsers.expat.error exception. ErrorByteIndex Byte index at which an error occurred. [etc.] """ The wrong, "xml.parsers.expat" is the first indicator that there might be a problem, yet I took the docs at their word and wrapped the call to ParseFile in a blanket try/except, only to find that no exception of any sort is ever raised by ParseFile. It turns out that ParseFile actually returns 0 on error, returning 1 otherwise. The first matter is that the code and the docs need to be reconciled. However, I would _much_ rather prefer that things were as in the docs. I think ParseFile should raise an exception rather than return an error flag. Interestingly enough, this is the same argument I had with a colleague just last week. -- Uche Ogbuji Principal Consultant uche.ogbuji(a)fourthought.com +1 303 583 9900 x 101 Fourthought, Inc. http://Fourthought.com 4735 East Walnut St, Ste. C, Boulder, CO 80301-2537, USA Software-engineering, knowledge-management, XML, CORBA, Linux, Python

3 2

Auto-Numbered Enumerated Lists (reStructuredText)
by David Goodger April 30, 2002

April 30, 2002

[The following is an excerpt from http://docutils.sf.net/spec/rst/alternatives.html (working version, not checked in yet). It was prompted by a suggestion by Fred Bremmer, which became alternative 3. I'm looking for comments, pro or con, on all aspects. Should this be implemented? (The implementation itself is trivial.) Which syntax is best? Which behavior? Any other suggestions? TIA.] The advantage of auto-numbered enumerated lists would be similar to that of auto-numbered footnotes: lists could be written and rearranged without having to manually renumber them. The disadvantages are also the same: input and output wouldn't match exactly; the markup may be ugly or confusing (depending on which alternative is chosen). 1. Use the "#" symbol. Example:: #. Item 1. #. Item 2. #. Item 3. Advantage: simple, explicit. Disadvantage: enumeration sequence cannot be specified (limited to arabic numerals); ugly. 2. As a variation on #1, first initialize the enumeration sequence? For example:: a) Item a. #) Item b. #) Item c. Advantages: simple, explicit, any enumeration sequence possible. Disadvantages: ugly; perhaps confusing with mixed concrete/abstract enumerators. 3. Alternative suggested by Fred Bremmer, from experience with MoinMoin:: 1. Item 1. 1. Item 2. 1. Item 3. Advantages: enumeration sequence is explicit (could be multiple "a." or "(I)" tokens). Disadvantages: perhaps confusing; otherwise erroneous input (e.g., a duplicate item "1.") would pass silently, either causing a problem later in the list (if no blank lines between items) or creating two lists (with blanks). Take this input for example:: 1. Item 1. 1. Unintentional duplicate of item 1. 2. Item 2. Currently the parser will produce two list, "1" and "1,2" (no warnings, because of the presence of blank lines). Using Fred's notation, the current behavior is "1,1,2 -> 1 1,2" (without blank lines between items, it would be "1,1,2 -> 1 [WARNING] 1,2"). What should the behavior be with auto-numbering? Fred has produced a patch__, whose initial behavior is as follows:: 1,1,1 -> 1,2,3 1,2,2 -> 1,2,3 3,3,3 -> 3,4,5 1,2,2,3 -> 1,2,3 [WARNING] 3 1,1,2 -> 1,2 [WARNING] 2 (After the "[WARNING]", the "3" would begin a new list.) I have mixed feelings about adding this functionality to the spec & parser. It would certainly be useful to some users (myself included; I often have to renumber lists). Perhaps it's too clever, asking the parser to guess too much. What if you *do* want three one-item lists in a row, each beginning with "1."? You'd have to use empty comments to force breaks. Also, I question whether "1,2,2 -> 1,2,3" is optimal behavior. In response, Fred came up with "a stricter and more explicit rule [which] would be to only auto-number silently if *all* the enumerators of a list were identical". In that case: 1,1,1 -> 1,2,3 1,2,2 -> 1,2 [WARNING] 2 3,3,3 -> 3,4,5 1,2,2,3 -> 1,2 [WARNING] 2,3 1,1,2 -> 1,2 [WARNING] 2 Should any start-value be allowed ("3,3,3"), or should auto-numbered lists be limited to begin with ordinal-1 ("1", "A", "a", "I", or "i")? __ http://sourceforge.net/tracker/index.php?func=detail&aid=548802 &group_id=38414&atid=422032 -- David Goodger <goodger(a)users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ - The Go Tools Project: http://gotools.sourceforge.net/

2 2

Re: [Python-Dev] [development doc updates]
by Sean Reifschneider April 29, 2002

April 29, 2002

On Thu, Apr 04, 2002 at 05:59:27PM -0500, Fred L. Drake wrote: >The development version of the documentation has been updated: On the topic of dev documentation... What happened to the info distribution? I had info and HTML in the 2.2 RPM, but only the HTML were around for 2.2.1c2 when I tried to pick it up the other night... Is there going to be an info release for the 2.2.1 final, or should I just leave it as HTML-only? Sean -- Tragedy is when I cut my finger. Comedy is when you fall into an open sewer and die. -- Mel Brooks Sean Reifschneider, Inimitably Superfluous <jafo(a)tummy.com> tummy.com - Linux Consulting since 1995. Qmail, KRUD, Firewalls, Python

3 2

ANN: Docutils 0.1 Released
by David Goodger April 20, 2002

April 20, 2002

The purpose of the Docutils project is to create a set of tools for processing plaintext documentation into useful formats, such as HTML, XML, and TeX. It is the subject of PEPs 256 & 258. Docutils currently supports input from standalone files; soon it will process PEPs, and eventually it will support inline documentation from Python modules and packages. Docutils uses the reStructuredText markup, the subject of PEP 287; other markups are possible. It produces simple HTML for CSS; other formats will become available in time. Quick link to the download: http://prdownloads.sf.net/docutils/docutils-0.1.tar.gz Docutils home page: http://docutils.sourceforge.net/ To subscribe to the mailing lists: - Development discussions (docutils-develop(a)lists.sourceforge.net): http://lists.sourceforge.net/lists/listinfo/docutils-develop - CVS checkin messages: http://lists.sourceforge.net/lists/listinfo/docutils-checkins High-level discussions take place on the Python Doc-SIG mailing list: http://mail.python.org/mailman/listinfo/doc-sig, mailto:Doc-SIG@python.org A ReStructuredText Primer (gentle introduction): http://docutils.sf.net/docs/rst/quickstart.html Quick reStructuredText (user reference): http://docutils.sf.net/docs/rst/quickref.html There has been a lot of progress lately. The reStructuredText parser is feature-complete, there's a standalone input file reader, and a simple HTML/CSS writer. The web site's HTML files are generated from reStructuredText source (the quickref being the only exception). There are a few simple front-ends in docutils/tools; see the README: http://docutils.sf.net/README.html. There is still much work to be done. Contributors are welcome! Release 0.1 (2002-04-20) ======================== This is the first release of Docutils, merged from the now inactive reStructuredText_ and `Docstring Processing System`_ projects. For the pre-Docutils history, see the `reStructuredText HISTORY`_ and `DPS HISTORY`_ files. .. _reStructuredText: http://structuredtext.sf.net/ .. _Docstring Processing System: http://docstring.sf.net/ .. _reStructuredText HISTORY: http://structuredtext.sf.net/HISTORY.html .. _DPS HISTORY: http://docstring.sf.net/HISTORY.html General changes: renamed 'dps' package to 'docutils'; renamed 'restructuredtext' subpackage to 'rst'; merged the codebases; merged the test suites (reStructuredText's test/test_states renamed to test/test_rst); and many modifications required to make it all work. -- David Goodger <goodger(a)users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ - The Go Tools Project: http://gotools.sourceforge.net/

1 0

DPS & reStructuredText 0.4 Released
by David Goodger April 19, 2002

April 19, 2002

Release 0.4 of each of the Docstring Processing System and reStructuredText markup parser projects have been posted to their project sites (URLs in my .sig below). These releases are the final ones for these projects. The two projects will be merged and renamed to "Docutils"; a SourceForge project is being constructed at http://docutils.sourceforge.net/, and a 0.1 release of Docutils will follow shortly. Once the DPS and reStructuredText projects are merged and renamed, they will become inactive. So this is really a contractual obligation non-announcement; you might as well wait a day or three for Docutils 0.1. Quick links to the downloads: - http://prdownloads.sf.net/structuredtext/restructuredtext-0.4.tar.gz - http://prdownloads.sf.net/docstring/dps-0.4.tar.gz There has been a lot of progress since the last release, long ago. The parser is construct-complete, there's a standalone input file reader, and a simple HTML/CSS writer. There are a few simple front-ends in restructuredtext/tools; see its README.txt. There is still much work to be done. If you would like to be added as a developer to the new Docutils project, please let me know (I've already added some people as developers). -- David Goodger goodger(a)users.sourceforge.net Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net

1 0

State of xml documentation standart project.
by Vivian De Smedt April 12, 2002

April 12, 2002

Dear all, I have write some module documentation using LaTeX according to the documentation standart of Python but I didn't succeed in converting them into html pages using Latex2Html on my windows platform. Hence I'am interested in the xml version of the documentation standart and the existing tools that already exist to convert from: latex to xml xml to latex xml to html If they do not exist I will be glad to help writing xslt filter to produce both html and LaTeX. I'am sorry not to be able to find what's happening with the xml migration project and I hope not bothering you with question I should be able to answer alone. Vivian.

2 1

2.2.1 docs
by Fred L. Drake, Jr. April 9, 2002

April 9, 2002

The Python 2.2.1 docs have now been published on python.org, and are listed as the "current" documentation. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Zope Corporation

1 0

ann: xmltoys 1.0a4, featuring pythondoc
by Fredrik Lundh April 9, 2002

April 9, 2002

I just released xmltoys 1.0a4, which includes an updated version of the javadoc-like pythondoc document parser: http://effbot.org/downloads/index.cgi/xmltoys-1.0a4-20020407.zip (click on download to get the code) -- about xmltoys pythondoc this tool uses introspection to find functions, classes, and methods in a module, and source code scanning to extract javadoc-style comments. the description part is written in HTML, and converted to XHTML fragments by the parser. additional information is extracted from the source code, and from javadoc tags in the comment. the result is stored in an XML infoset. the tool comes with a relatively simple HTML converter; a docbook converter is in the works. you can of course also run the result through your favourite XML processor. more information can be found here: http://effbot.org/guides/pythondoc.htm http://java.sun.com/j2se/javadoc/ http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/javadoc.html sample output (showing off some rather obvious bugs): http://effbot.org/doc/ -- about the 1.0a4 release this version has been tested with itself, PIL, and a couple of other rather large libraries. unlike the first release, it can also parse the python standard library without getting stuck on None objects (but for obvious reasons, it doesn't generate any output for the standard library... it uses the new HTMLParser module, so the current version requires Python 2.2. I plan to get rid of that dependency for the next release. enjoy /F

1 0

Re: PEP 287: reStructuredText Standard Docstring Format
by David Goodger April 9, 2002

April 9, 2002

Thank you to everyone who has commented on PEP 287, be they in favor, well-meaning but opposed, or ill-wishing troll ;-) [1]_. I have been otherwise busy and haven't been able to keep up with replies, but I have read and kept a record of all the posts so far (and will, for posts yet to come) for consideration and reference when revising the PEP. I may not be able to offer timely replies to all the posts; ultimately the revised PEP will serve as an umbrella reply. .. [1] Actually, the posts opposed and even the trolls are often the most useful, since they point out weaknesses and help strengthen the arguments. The number of people posting *in favor* of the PEP was roughly the same as the number opposed, but supporters tend to be silent while protesters tend to be quite vociferous and relentless. Over the weeks to come, I will be revising PEP 287 and related PEPs 256-258, merging the reStructuredText_ and DPS_ projects into the renamed Docutils_ project, and producing a "road map" describing the big picture. Further suggestions for improvement are welcome. .. _reStructuredText: http://structuredtext.sourceforge.net/ .. _DPS: http://docstring.sourceforge.net/ .. _Docutils: http://docutils.sourceforge.net/ A special thanks must go to Richard Jones for taking up arms (or keyboard) in my stead, and for taking the initiative to start work on `A ReStructuredText Primer`_. In hindsight it was much needed, and it's coming along nicely. Thanks Richard! .. _A ReStructuredText Primer: http://mechanicalcat.net/tech/quickstart.html -- David Goodger goodger(a)users.sourceforge.net Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net

2 2

Re: [Python-Dev] Searching Python docs
by Fred L. Drake, Jr. April 5, 2002

April 5, 2002

[This is cross-posted; followups to the Doc-SIG only, please!] Thomas Heller writes: > Hm, in the good old days this was the only way ;-) > because the chances where at most 50% that this stuff > was undocumented. I think a lot of us here remember when that 50% was less than 5%, and there was no C API manual. ;-) I still remember seeing the checkin message for api.tex 1.1. > But the docs have improved in the meantime, now you > could also use *them*. Which brings me to the issue of a decent index. (What doesn't, eventually?) We currently have two documents that discuss the C API, though they take (mostly) different approaches. The API reference has a tolerable index (the symbols are there, at least), but the Extending & Embedding document doesn't have enough index entries to be very useful (so little we don't even include an index), even though it contains some strongly overlapping information. I *think* it might be a good idea to merge the two documents, but I'm not certain I really like that. There is a strong need to add good index entries to the existing Extending & Embedding document at the very least, and a combined index would be very valuable. This is something that's been requested for the entire set of documents on many occaisions, and would be very handy. (Especially if we provided a better interface for it!) -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Zope Corporation

3 2