Mailman 3 December 2000 - 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

docutils status report
by Tony J Ibbs (Tibs) Dec. 22, 2000

Dec. 22, 2000

Well, the Tools/compiler hint was just what I needed - it took very little time to start extracting docstrings from a Python file, and it's fairly clear how one would manage a package. Anyway, here is a status report and some "to do" information: I currently have some code that will: 1. Find the docstrings in a Python file (currently itself!) 2. Split the text into paragraphs at blank lines. 3. Identify lines within a paragraph that start like a list item, and split there as well - this allows:: This is a paragraph. 1. So is this fred -- and so is this to produce 3 paragraphs, and I think this is the main place that Python users want/need to be able to have "no blank lines". 4. Identify subparagraphs of a paragraph ending "::" as literal text (note that, as in STNG, the "::" is enough text to constitute "text in a paragraph", so the "empty header" idea will work). 5. Identify paragraphs starting ">>>" (allowing leading whitespace) as Python code (i.e., literal) 6. Recognise bullet list items (as in ST - the use of "o" may go away following David's comments) 7. Recognise numbered list items (but the final dot *is* required, otherwise 3 above will fail on:: My favourite drink is tea, but also I like coffee (thinking the second line to have a Roman numeral at the start!)). Note that one won't be able to do:: And the final number is 1. without a spurious list, but I reckon we can live with that! (We have to pay for apparent simplicity with true complexity.) 8. Recognise descriptive list items (note that markup is allowed in the "title" of the item, so one can do:: ' -- ' -- This is an awkward case 9. Recognise *emphasised* text, **strong** text and 'literal' text (but, except by "accident" nesting of markup does not work (well, you can't *nest* markup in literal, since it won't be seen!)). The emphasised and strong texts may contain any characters (except the terminating sequence, of course), and inline literals may contain anything but "'". Escaping characters is not yet addressed. 10. Emit a "dump" of the datastructure that is built up. Note that the markup done is handled in a way that should be simple to customise - I may well provide the final product as an example of this, with an "STNG-like" core and the pyST extras as "extension". I'd prefer not to make code public until I've got stuff DOM structured (see below), but if anyone *really* wants to, I can make it available for download. Things to do next ----------------- (in no particular order) include: A. Move the datastructure to a DOM model (probably based on Python 2.0's mindom.py). DOM looks sensible because it is (erm) fashionable, and if I use minidom then I get XML output for free. B. Add more markup (I've got a bare minimum for testing at the moment) C. Define what the command line interface is (i.e., how to specify that one wants to parse a file or package, what one wants the output to be, and so on.) D. Document what it does, so that David and company can haggle over the exact syntax supported. This obviously includes making sure the whole thing has nice (correct) docstrings throughout. E. Make nested markup work, so one can do:: *This is **strong and 'literal'** text within emphasised* I do *not* intend to provide support for tables! (that can come later). Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ Give a pedant an inch and they'll take 25.4mm (once they've established you're talking a post-1959 inch, of course) My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

3 5

docutils status report - STpy.html draft
by Tony J Ibbs (Tibs) Dec. 20, 2000

Dec. 20, 2000

What with school and nursery concerts, office lunch, work dinner and the imminent approach of Christmas exhaustion (oh, and "real" work as well, mustn't forget that), I haven't had time to do any docutils programming this week. However, I've got the *start* of some docutils documentation - it's available at: http://www.tibsnjoan.demon.co.uk/STpy.html http://homepage.ntlworld.com/tibsnjoan/STpy.html Note that it isn't finished - but it's probably already got enough in it to comment on. We'll see if the first version of docstring.py is *actually* finished before my Christmas holiday (when I'll be incommunicado until the new year) or not next week... All the best, Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "Bounce with the bunny. Strut with the duck. Spin with the chickens now - CLUCK CLUCK CLUCK!" BARNYARD DANCE! by Sandra Boynton My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

1 3

docutils status report 2
by Tony J Ibbs (Tibs) Dec. 8, 2000

Dec. 8, 2000

Here is a further status report on the docutils work. I currently have some code that will: 1. Find the docstrings in a Python file (currently itself!) 2. Split the text into paragraphs at blank lines. 3. Identify lines within a paragraph that start like a list item, and split there as well - this allows:: This is a paragraph. 1. So is this fred -- and so is this to produce a paragraph and two lists. 4. Partition list items up into lists (so that a "bare" <li> is actually a child of an <ol>, or whatever, to use HTML terms) 5. Identify paragraphs starting ">>>" (allowing leading whitespace) as Python code (i.e., literal) 6. Recognise bullet list items (as in ST - the use of "o" may go away following David's comments) 7. Recognise numbered list items (but the final dot *is* required, otherwise 3 above will fail on:: My favourite drink is tea, but also I like coffee (thinking the second line to have a Roman numeral at the start!)). Note that one won't be able to do:: And the final number is 1. without a spurious list, but I reckon we can live with that! (We have to pay for apparent simplicity with true complexity.) 8. Recognise descriptive list items (note that markup is allowed in the "title" of the item, and I'm still hoping to get round to enabling:: ' -- ' -- This is an awkward case (I forgot to tweak the RE yet) 9. Recognise *emphasised* text, **strong** text and 'literal' text (but, except by "accident" nesting of markup does not work (well, you can't *nest* markup in literal, since it won't be seen!)). The emphasised and strong texts may contain any characters (except the terminating sequence, of course), and inline literals may contain anything but "'". Escaping characters is not yet addressed. 10. Produce something that's getting close to a sensible DOM tree (the only issue is "paragraph within paragraph", which will be addressed in my documentation - see next week!). That's not too dissimilar to what I reported last week, and indeed the main thing that I've been working on is the "DOM"ising of the code, including getting lists to nest themselves nicely (well, the code isn't neat yet, but it works). There's also been a fair amount of restructuring, part of which is why the "::" recognition has gone away (don't worry, it's not away for long). As before, I'd rather not release code yet, but can if someone *really* wants to take a look (damn, that sounds so, well, non-open-source). Things to do next ----------------- The task list (in no particular order) includes: A. Document the supported pyST syntax, so that David and company can haggle over the exact syntax that *should* be supported. B. Update the internal documentation. C. Add support for more markup (I've got a bare minimum for testing at the moment). D. Define what the command line interface is (i.e., how to specify that one wants to parse a file or package, what one wants the output to be, and so on.) E. Make nested markup work, so one can do:: *This is **strong and 'literal'** text within emphasised* I intend to do a little more implementation work (but not a lot) and then attack task A, pyST syntax, aiming to have a document by the end of next week. Cross fingers and I might still hit the "before Christmas" release point... Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

1 0

latex2html
by Michael Hudson Dec. 7, 2000

Dec. 7, 2000

My installation of latex2html seems to have withered and died (like, gosh). What's the current blessed version and where can I get it from? Much thanks in advance! M. Grumble, grumble, all software sucks, etc.

2 3

[development doc updates]
by Fred L. Drake Dec. 7, 2000

Dec. 7, 2000

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Lots of small changes, but most important, more DOM documentation: http://python.sourceforge.net/devel-docs/lib/module-xml.dom.html

1 0