Mailman 3 November 2001 - 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

[development doc updates]
by Fred L. Drake Nov. 30, 2001

Nov. 30, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Updated the httplib docs to cover the API provided in recent versions of Python. Please review and comment on this and all other new material! (In case you have forgetten, other large chunks of new material include the sections covering modules in the email package, the compiler package, and the Tkinter/Tix chapter.)

1 0

[development doc updates]
by Fred L. Drake Nov. 29, 2001

Nov. 29, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Added section of example regular expressions to the "re" module docs. Various small clarifications.

1 0

[development doc updates]
by Fred L. Drake Nov. 28, 2001

Nov. 28, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Minor updates; mostly changed organization of the "Internet Data Handling" chapter.

1 0

yummy treats!
by David Goodger Nov. 27, 2001

Nov. 27, 2001

It really was only meant as a joke... >From the reStructuredText home page: If you can test, administrate, or contribute code, ideas, bug reports, yummy treats, computer equipment, and/or large sums of money, please `contact the project administrator`_. .. _contact the project administrator: me_ Got a call from my wife today. Seems a package arrived at our door, addressed to me but "'re: structured text', what does that mean?". I get home, and my 4-year-old son helps me to sift through the styrofoam peanuts to dig out a seemingly endless assortment of delectables, from caramel corn to ginger chews (*way* too spicy for my taste, but I'm sure we'll find them a good home), from light-as-feathers lemon meringues to a "Pound Plus" (500g) bar of Belgian bittersweet chocolate. About a cubic foot of yummy treats. Thanks Alan! Whatever possessed you? Now if only someone would send me a nice new (or even slightly used) laptop. Boy would the rate of checkins ever go up then! JUST KIDDING!!! (well...) -- 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 1

[development doc updates]
by Fred L. Drake Nov. 26, 2001

Nov. 26, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Various small corrections and additions.

1 0

Getting started with restructured text
by Amos Latteier Nov. 26, 2001

Nov. 26, 2001

Hi, I don't know much about restx, but what I've seen so far impresses me. The spec seems well thought out. I currently use structured text quite a bit. In fact I've written a book with it. I am painfully aware of shortcomings in structured text. I'd like to evaluate restx as an alternative for writing articles and books. I downloaded the latest cvs snapshot and tried to figure out how to get going. I ran into a couple problems: * distutils doesn't add __init__.py files to the dps and parsers directories that it creates. This means that they aren't considered packages. I don't know if this is a distutils bug or a problem with how restx uses distutils. * restx seems to require that the entire dps package be installed. * There is no obvious way to create HTML output. Should I write an HTML formatter along the lines shown in dps.formatters.model? Or is XSLT preferred? Thanks for any pointers. -Amos -- Amos Latteier amos(a)zope.com Zope Corporation http://www.zope.com/

4 5

Last Friday, "groups", washing machines
by Tony J Ibbs (Tibs) Nov. 20, 2001

Nov. 20, 2001

Humph. OK, Friday happened, and we have a new washing machine, but for reasons mostly to do with the vagaries of how such things get delivered and the difficulties of arranging childcare and pickup around them, I actually got less than two hours of computer time - and essentially none over the weekend for other reasons. Mind you, we're now building up a nice backlog of ironing, so it's not all downside! I managed to write something on <group> and "style", but it's still a bit hazy, and I haven't had time to make it shorter. Still, rather than put it off, here goes: .. begin:: reST included text .. ############################################################ Adding <group>, losing <package_section> and their ilk ====================================================== :Author: Tibs :Date: 2001-11-18 Background ---------- I am currently writing software that will take information from Python source files, produce a DPS node tree therefrom, and allow the user to generate HTML from that. My initial implementation produced a *variant* of the DPS node tree, which contained many structures that related closely to the information derived from Python - for instance, something like:: <py_class name="Fred"> <docstring> This is a very silly class. <py_attr_list> <py_attr name="jim"> <py_method "name="method"> For various reasons, the (implicit) DTD wasn't shaping up very like that proposed by David Goodger, so I asked about the possibility of amending the "standard" DTD. This led to a discussion of how the flow of information through a DPS processor should actually work, with the result being David's diagram [#diagram]_:: +--------+ +--------+ +------------+ +--------+ | READER | --> | linker | --> | transforms | --> | WRITER | +--------+ +--------+ +------------+ +--------+ | TOC, index, | | etc. (optional) | +--------+ +--------+ | PARSER | | filer | +--------+ +--------+ David also made the point that, within this plan, the result of the ``linker`` phase is a normal DPS tree, which can be transformed with any of the "standard" transformation tools (for instance, to resolve automatic footnotes), and then output with any writer. Whilst David's diagram is not *quite* how I see the process, it's close enough for this purpose. Thus pydps [#pydps]_ might be shown as:: +--------+ +--------------+ +------------+ +---------+ | READER | --> | transform.py | --> | transforms | --> | html.py | +--------+ +--------------+ +------------+ +---------+ | | +----------+ +---------------+ | visit.py | | buildhtml.py | +----------+ +---------------+ The "READER" is implicit in the main utility (currently ``pydps.py``), and locates the relevant Python files. It then uses ``visit.py`` to generate a tree representing the Python code (the Python ``compiler`` module, standard with Python 2.2 and above, but in ``Tools`` before that, is used). ``transform.py`` (which, by David's diagrams, should maybe be called ``link``) transforms that information into a proper DPS node tree. At the time of writing, no transformations are done. Finally, HTML is output from the DPS node tree by ``html.py``. So, in summary: 1. ``transform.py`` generates a *normal* DPS tree. It doesn't use any "odd" nodes (except <group> - but we'll discuss that later on). This means that it should be possible to plug in any other writer, and produce a different format as output - a very significant advantage. 2. ``html.py`` expects to be given a *normal* DPS tree. This means that it should be usable by any other utility that also provides a normal DPS tree - again an advantage. The problem ----------- But there is a clash in requirements here. Whilst it is very nice to be able to represent the Python information as "normal" DPS (guaranteeing that anyone can do useful things with it), there is some need to transfer information that goes beyond that. There are two main reasons for wanting to do this: * Data mining * Presentation For the first, although DPS/reST/pydps is primarily about producing human-viewable documentation, it might also be nice to be able to extract parts of it automatically, for various purposes - for instance, retrieve just the information about which classes inherit from other. This information will, in part, be obvious from the text chosen within the document (a title like "Class Fred" might be taken to be useful, for instance!), but it would be nice to give a bit more help. For the second, it's relatively difficult to produce better layout for DPS Python documentation without more information to work on. If one uses the (rather garish) default presentation produced by pydps (and no, I'm not saying that's a *nice* presentation, but it is the one I've got as an example), it is clearly useful to be able to: 1. group together the package/class/method/etc title and its full name/path/whatever 2. group together a method or function's signature and its docstring David's original approach to this was to introduce a host of Python specific tags into ``nodes.py`` [#nodes]_ - for instance:: package_section module_section ... instance_attribute_section ... parameter_item parameter_tuple ... package module class_attribute There are several problems with approach. Perhaps the most serious is that *all* generic DPS writers need to understand this host of elements that are only relevant to Python. Clearly, someone writing a writer for other purposes may be reluctant to go to this (to them) redundant effort. >From my point of view, an immediate problem is that the set of elements is not *quite* what I want - which means working towards a set of patches for ``nodes.py`` and the relevant DTD, and getting David to agree to them (well, that last is a useful process to have in place, but still). Since I'm not likely to get it right immediately, this is a repetitive process. Lastly, one might imagine someone from another programming language domain adopting DPS/reST. One can expect them to be frustrated if the set of constructs provided for Python doesn't quite match the set of constructs required to describe their language in a natural manner. Luckily (!), I have a counter proposal, which hopefully keeps the baby and just loses the bath water. Groups and "style" ------------------ The first thing that I realised was that, for convenience of output at least, I wanted to be able to group elements together - or, in terms of the DPS tree, insert an arbitrary "subroot" within the tree to 'abstract' a branch of the tree. This is particularly useful for linking together the parts of the text that deal with (for instance) attribution, or unusual globals, without having to embed yet another section. There is, of course, precedent. HTML provides <div> and <span> - one for "structural" elements, and one for inline elements (I forget which is which), and TeX and LaTeX are well-known for their use of grouping (e.g., the ``\begin{xxx}`` and ``\end{xxx}`` in LaTeX). I don't consider it worth making the <div>/<span> distinction in the context of a tree - it is perfectly evident what is beingp grouped from the elements themselves. Once one has a <group> element, it is natural to annotate it with *what* it is a group of/for. I chose the arbitrary term "style" - partly because it is not used in HTML/XML for any purpose I am aware of. And once one has the "style" attribute, it becomes possible to use it elsewhere - most notably in <section> elements, saving the need for a myriad of different sections for different purposes. In these instances, it is perhaps acting more like the "class" attribute in HTML - indicating, to some extent, meaning, but aimed mostly at presentation (via CSS). The other obvious place to use it is in the automatically generated text for things like names, where (at least pre-"combing"/transformation) one is "pretending" to have assigned a role (just as a person might in a docstring) (but see [#style]_). Summary ------- Current DPS defines many element types for use in Python code representation. However, there are major advantages in only using the "simple" DPS nodes for all purposes. This becomes simple and practical given a single extra, general purpose, element: <group>. Furthermore, adding a standard attribute called "style" (or perhaps "role" - see [#style]_) seems to fulfil any other outstanding requirements. References ---------- .. [#diagram] in email by David Goodger to Doc-SIG, dated 21 September 2001 04:31, "Re: [Doc-SIG] DPS components". .. [#style] Hmm - maybe "style" should be "role", to match with the way that a :role:`of something` gets handled... .. [#pydps] Normally to be found at http://www.tibsnjoan.co.uk/reST/pydps.tgz, although note that this is not currently up-to-date. .. [#nodes] dps/dps/nodes.py in the DPS distribution (``dps.nodes`` if one is importing it). .. ############################################################ .. end:: reST included text Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "No one trike will do everything... buy the whole set!" - Rob Hague My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

2 4

scope of the parser
by Alan Jaffray Nov. 20, 2001

Nov. 20, 2001

Since the rules for which references are associated with which targets are defined by reStructuredText, shouldn't the parser explicitly state which target is to be used for each reference? Ditto for footnotes, inline directive references, etc. It seems misplaced for an output formatter to be dealing with details of autonumbering, ambiguous refnames, etc. Meanwhile, since the meaning of directives and the set of meaningful directive names is *not* defined by reStructuredText, shouldn't the rST parser output most directives (including unknown ones) untouched? It seems advantageous to be able to decouple directive processing and implementation from reStructuredText parsing and implementation. Alan

2 5

RE: [Doc-SIG] Use cases for inline directive references
by Moore, Paul Nov. 19, 2001

Nov. 19, 2001

From: Alan Jaffray [mailto:jaffray@pobox.com] > I'm uncomfortable with the current "forgiving" rules. It's clear that > you've put a lot of thought into them, and they're clever, and they > handle many cases well. But they're not clever enough to prevent > the user from being surprised if they use unquoted characters without > knowing the rules, and they're sufficiently complicated and ad-hoc > that knowing all the rules is difficult. I agree that they are somewhat confusing to *write*, but they are very natural to *read*. In other words, I agree that there are many borderline cases which I, as a non-expert, would quote because I don't understand that I don't need to. On the other hand, when I read text written by other people which use things like 2*x inline, with no quoting, I find it very natural to read, and much less obtrusive. So, in my view, I would say that the current rules are good, as they enhance the goal of *allowing* marked-up text which is readable in raw form. (The fact that they don't quite manage to *encourage* writing of such text, because the rules are a bit more complex than the minimum possible, is a shame, but worth it). It boils down to whether you like DWIM-type rules (which are never 100% perfect, by their nature). But I don't mind much about the character-level markup issue... Paul

1 0