Mailman 3 September 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

Re: [Docstring-develop] pydps futures (was RE: Document titles)
by David Goodger Oct. 8, 2001

Oct. 8, 2001

Tony J Ibbs (Tibs) wrote: > Combs > ----- > The metaphor of combing through hair to remove tangles is a bit > iffy, but I like the term (I think David calls them Filters, which > is less obvious to me) Strictly speaking, a filter reduces the amount of information. Rather than "combs", I'd use the common term: "transforms". Tony's made a good start listing the transforms we'll need. Looking at them and thinking of others, we will need to identify which transforms are parser-specific and which are generic. The "bibliographic field list" transform is obviously parser-specific, but must be run after the "section promotion" transform (what Tony calls "TitleComb"). > David - a question or two on this. Each autonumbered > footnote/footnote reference has the attribute 'auto' > set to "1". I want to *insert* actual footnote numbers > into the tree. Auto-numbered footnotes have attribute ``auto=1`` and no label. Auto-numbered footnote_references have no reference text (they're empty elements). If you resolve the numbering, just add a label element to the beginning of the footnote, and reference text to the footnote_reference. Take this input:: References to the first ([A]_), third ([#spam]_), and second ([#]_) footnotes. .. [A] This footnote is labeled with "A". .. [#] This footnote is auto-numbered. .. [#spam] This footnote has autonumber name "spam". Parsed (watch for empty footnote_reference elements: indentation):: <document> <paragraph> References to the first ( <footnote_reference refname="a"> A ), third ( <footnote_reference auto="1" refname="spam"> ), and second ( <footnote_reference auto="1"> ) footnotes. <footnote name="a"> <label> A <paragraph> This footnote is labeled with "A". <footnote auto="1"> <paragraph> This footnote is auto-numbered. <footnote auto="1" name="spam"> <paragraph> This footnote has autonumber name "spam". Only the first footnote_reference contains reference text. After auto-numbering resolution, the tree should become:: <document> <paragraph> References to the first ( <footnote_reference refname="a"> A ), third ( <footnote_reference auto="1" refname="spam"> 2 ), and second ( <footnote_reference auto="1" refname="_footnote 1"> 1 ) footnotes. <footnote name="a"> <label> A <paragraph> This footnote is labeled with "A". <footnote auto="1" name="_footnote 1"> <label> 1 <paragraph> This footnote is auto-numbered. <footnote auto="1" name="spam"> <label> 2 <paragraph> This footnote has autonumber name "spam". The labels and reference text are added to the two auto-numbered footnotes & footnote_references. The unnamed auto-numbered footnote & reference need name & refname attributes. Let's use "_footnote " + footnote number for those attributes (a name-mangling unlikely to occur in the real world; note that this hasn't been documented yet). Of course (!), the implicitlinks and refnames instance attributes of the dps.nodes.document instance must be updated. (It will soon be my pleasure to document the dps/nodes.py data structure, since I'm gradually forgetting its details.) After adding labels and reference text, the "auto" attributes can be ignored. -- 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

3 5

examples in reStructuredText spec
by David Goodger Oct. 8, 2001

Oct. 8, 2001

Call for opinions re: http://structuredtext.sourceforge.net/spec/reStructuredText.txt - Are the "syntax diagrams" useful? - Would "before & after" examples be useful (also/instead)? For example:: Example input:: A Title ======= Paragraph. Parsed:: <document> <section name="a title"> A Title <paragraph> Paragraph. Examples such as this would extend the spec's length quite a bit (they could be put into another file, examples.txt). However, I think they would help to document the DPS document tree structure. I would include a section explaining the indented pseudo-XML notation used to represent the parsed document tree. -- 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

3 2

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

Sept. 28, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Various small adjustments and bug fixes. Added preliminary docs for the SimpleXMLRPCServer module.

1 0

[development doc updates]
by Fred L. Drake Sept. 27, 2001

Sept. 27, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Documentation as released for Python 2.2 alpha 4.

1 0

Python 2.2a4 docs frozen
by Fred L. Drake, Jr. Sept. 27, 2001

Sept. 27, 2001

The documentation for Python 2.2a4 is now frozen; the HTML packages have been pushed to the server and the online version is available on python.org from the Python 2.2 pages. SourceForge will be updated momentarily. The trunk is *not* frozen; updates can continue there. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Zope Corporation

1 0

Re: [Docstring-develop] pydps - new version uploaded
by David Goodger Sept. 27, 2001

Sept. 27, 2001

Tony J Ibbs (Tibs) wrote: > http://www.tibsnjoan.co.uk/reST/pydps.tgz ... > The package now contains a README.txt file at David's request Thanks! > (yes, it's a text file written in reST, despite my grumbles at David > the other day about file extensions). I think ".rtxt" is the winner, by the way. > All this means I can now turn > restructuredtext/spec/reStructuredText.txt into HTML and produce > something that I find easier to read. Yeh. I ran pydps.py on reStructuredText.txt and took a look. Wow! Very cool to see the text come to life. I had some trouble running it over some Python modules though (tracebacks sent separately). I didn't see any unit test code in the distro... -- 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

RE: [Doc-SIG] Re: Document titles (was RE: [Docstring-develop] D PS - possible bugs/features)
by Moore, Paul Sept. 26, 2001

Sept. 26, 2001

From: David Goodger [mailto:goodger@users.sourceforge.net] > > 1. The parser makes one up (yuck) > > 2. The application makes one up (yuck) > > 3. An error is generated (yuck) > > > > I'd vote for 3 ... > > Probably me too, in those cases where it's necessary. If the writer > doesn't need a document title, it need not complain. As an alternative, let's take a higher level view. Someone, somewhere, is going to be running this stuff via command-line wrapper applications. In that context, the obvious approach would be to have a command-line option which specifies the document title, with "the only" section header being the default, and with an error generated if there are no or too many sections. So you have rest2html --title "My Document" doc.rest >doc.html That seems logical to me. How it gets propogated down to the guts is for you guys to work out :-) Paul.

1 0

DPS components
by David Goodger Sept. 26, 2001

Sept. 26, 2001

I like Tony's name for the outputter: "writer". Generalizing, it fits my idea of separation of components (see "Modes and Styles" in http://docstring.sourceforge.net/spec/dps-notes.txt). We can have "readers" (what I'd called "input modes") that understand the data source (e.g. "pysource" for Python source files, "pep" for PEPs, one or more for standalone .rtxt files, "email" is possible, etc.). Readers understand where the data is coming from, send discrete "chunks" to the parser, and provide the context to bind the chunks together into a cohesive whole. Readers also resolve all hyperlinks, footnote numbers and links, interpreted text links, and anything else that requires context-sensitive computation. We have "parsers" for the syntax itself (just "reStructuredText" a.k.a. "rst" a.k.a. "reST" a.k.a. "rtxt" for now). Parsers don't know or care anything about the source or destination of the data; they just analyze their input and produce conformant output. I'm calling the next set of components "designers" (previously called "syles"; "designers" is OK until a better term is found; "stylists"? [#]_). Designers take the output from a reader and transform it. Content transformations (moving stuff around, grouping, separating) as well as cosmetic transformations (?) happen here. The output from a designer is the input of the writer. "Writers" (formerly "formatters") produce the final output (HTML, XML, TeX, etc.). Writers merely do translations from one data format to another; they don't do any content transformations. Their input may be an augmented form of the current schema, with color and layout information added. It appears to me that there will be strong links between readers and designers, whereas parsers and writers are more independent and interchangeable. Opinions? Comments? .. [#] You may be able to tell that names for things are very important to me when designing a system. When all the pieces of the system have the right names, it feels right, and everything falls into place. I spend a lot of time searching for the right names. My thesaurus and dictionary are prominent in my technical library. -- 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

4 14

Re: Document titles (was RE: [Docstring-develop] DPS - possible bugs/features)
by David Goodger Sept. 26, 2001

Sept. 26, 2001

[As it may be of more widespread interest, I'm moving this discussion over to Doc-SIG.] Tony J Ibbs (Tibs) wrote: > Ueli Schläpfer gave a good explanation of why David Goodger had chosen > to do something I didn't understand - namely make a document with a > title at the start have no section within it (except it was subtler than > that). For those new to this discussion, please see Tony's original post at http://www.geocrawler.com/lists/3/SourceForge/12823/0/6666616/ (Ueli's followup is http://www.geocrawler.com/lists/3/SourceForge/12823/0/6667890/). To begin, let me reiterate what I wrote on Friday (21 Sept): ... Perhaps this parser-specific transformation should be made optional [#]_. Then you can treat everything as generic sections until integration is complete. .. [#] Along with bibliographic field list interpretation, RCS keyword filtering, and whatever other conveniences we dream up. I will make these transformations optional, or remove them altogether and relocate them to a separate module. The only problem with this separation is that these transformations are markup-specific; they may not be necessary with another markup syntax. I don't know the best way to handle this situation yet; suggestions are welcome. [Tony] > By the way, I did check the documentation, and it seemed to me that > the current documentation indicated that a title would cause a > section to be started - so David, if you want to perform this > promotion, then it needs to be documented (unless I've missed it > *again*). No, you haven't missed anything. It wasn't documented; I guess it was just so obvious to me that I never thought to write it down. I'll work on an explanation for the spec (taking into account this discussion, of course). > On the other hand, I don't actually see why the DPS system should > have to do the promotion for the user, when it's not clear that it > is always wanted (in other words, why is it up to the DPS system to > decide that the case of a single section is special, and then have a > sudden disjunction in its behaviour for two sections - that's my > inner pedant objecting!). True, there's some ambiguity here. But the user needs some way to indicate the document title. > Regardless, an immediate solution to resolve the docstring case (and > possibly a useful thing to do anyway) would be to have an argument > to the Parser that states upfront that we are working on a document > *fragment* That's one possibility, yes. > Broadly, HTML common practise treats a document as having a single > title at the top, which is used for both <title> and <h1>, and the > "section hierarchy" (if any) starts with an <h2>. That's a transformation the HTML writer will want to do to the document: convert the document title to both <HEAD><TITLE> and <H1>. > Maybe (horrors) we should reserve one specific markup form to mean > "overall title":: That won't fly. > Or perhaps we'll have to resort to:: > > :Title: Document title PEPs use this, but I wouldn't want to use it in my documents. > Somehow, I don't see David liking either of those... You know me so well! > My problem is that I'm trying to write formatters for *any* document > that might come in (yes, I know I'm writing pydps/pysource, but I > want the Writer to work for any document) The "Writer" being an "HTML Writer"? > so we have to be able to cope with: > > 1. Document with no titles at all > 2. Document with one title (OK - David does that) > 3. Document with more than one title (at the same level) > - which in essence *really* resolves back to case 1. 1 & 3 merge to become "Document without exactly one title". I'd say that warrants an error from the HTML writer since a title is a prerequisite. Or the HTML writer can call that document "Untitled". Or both. The TeX writer need not complain. > I'm afraid that the only "perfect" solution I can see for that (in > the sense of *predictable*) is to require the user to indicate that > they *do* have a document title, and that it is *this* thing, here. > That then makes them aware of the problem, also, which I think is a > necessary thing (otherwise, surprise will eventuate). I think, documented, the promotion of a single section to document status is natural and predictable. However, it's not the parser's job. Is there an alternative? > David Goodger wrote: > > It is actually intended that by the time the document tree gets to > > the writer, it must have a title. The parser can't always > > determine the title by itself, such as in PySource mode. The > > PySource reader is expected to supply all the titles as > > appropriate. > > Hmm. In PySource mode, the parser should not be trying to introduce > titles - it is, after all, handling arbitrary document fragments, > and can't know anything about their global scope (unless it is > told!). We'll turn off the transformations for PySource mode. The parser will no longer introduce titles; that's the reader's job. > *If* the final tree shall always have a title, where does it come > from if the document author didn't provide one? Surely in that case > it is not up to the *parser* to decide on what a title should be - > that is up to the application. So one has three options: > > 1. The parser makes one up (yuck) > 2. The application makes one up (yuck) > 3. An error is generated (yuck) > > I'd vote for 3 ... Probably me too, in those cases where it's necessary. If the writer doesn't need a document title, it need not complain. [Ueli] > The source filename isn't known to the writer, is it? [Tony] > I think that the sourcefile as an optional attribute on the document > is probably a useful thing, as well. I've added an optional attribute 'source' (not just files!) to 'basic.atts', so all elements will get it. That way, each fragment of a document can record its origin. -- 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 3