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

Updates to Docutils
by David Goodger May 30, 2002

May 30, 2002

I've just checked in a bunch of changes to Docutils. The biggest change was the addition of a command-line interface to the front-end scripts. Greg Ward's Optik package is now required (http://optik.sf.net/). I added ``docutils.frontend`` to support command-line processing of front-end scripts (which are now down to 3 lines each). The ``docutils.core.Publisher`` class and ``publish`` function have been greatly simplified by the use of Optik. Download the latest snapshot from: http://docutils.sf.net/docutils-snapshot.tgz The sandbox snapshot is also available: http://docutils.sf.net/docutils-sandbox-snapshot.tgz -- David Goodger <goodger(a)users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/

1 0

Eros e soldi:guadagna con internet 0,08 euro a clic
by lolita May 23, 2002

May 23, 2002

sono lolita, voglio presentarti il mio nuovo sito affiliazione gratuita con guadagni immediati: erotismo, chat,loghi e sonerie etc, etc, l'unico sito che paga cos� tanto 0,08 euro a clic ............................guarda bene la pg di affiliazione............................e buon divertimento. visita il sito: http://members.xoom.it/marym1976 http://members.xoom.it/marym1976 http://members.xoom.it/marym1976

1 0

RE: [Doc-SIG] [development doc updates]
by Moore, Paul May 23, 2002

May 23, 2002

From: Fred L. Drake [mailto:fdrake@acm.org] > > The development version of the documentation has been updated: > > http://www.python.org/dev/doc/devel/ > > Slightly improved version of the experimental change; in > signature lines that start with "class " or "exception ", > avoid line breaks between the leading word and the class > or exception name. > > Please continue to provide comments on the change to > doc-sig(a)python.org or to python-docs(a)python.org. In http://www.python.org/dev/doc/devel/lib/module-copyreg.html, using IE6 on a Windows 2000 machine, scroll down to the definition of pickle() at the bottom. Narrow the window, and when you reach a certain point, the "(" following the function name word wraps onto the next line, resulting in pickle type, function[, ( constructor]) The "(" shouldn't be allowed to wrap. I know this is a borderline case of a borderline case, but I'm not sure that the benefits of all this are worth it. Even when wrapped "properly", you get pickle( type, function[, constructor]) which doesn't look right to me with the "[," hard up against the "function". I'd prefer the "[," to wrap with the following parameter. To do that, you'd need to use unbreakable spaces. Are these universally supported (or even available??) And would unbreakable spaces work in any case? The original problem I noted with "pickle(" would seem to imply that IE6 may well choose to break between text and punctuation anyway. I guess this is only really important for users on very narrow screens (PDAs?), so their comments are probably more important here... Paul.

3 6

RE: [Doc-SIG] [development doc updates]
by Moore, Paul May 23, 2002

May 23, 2002

From: Fred L. Drake, Jr. [mailto:fdrake@acm.org] > I've changed this a bit; it wraps for me the way you > describe on Mozilla 0.9.9; I don't have ready access to > MSIE right now. Yes, that works fine on IE6 now. Thanks, Paul.

1 0

Re: [Python-Dev] [development doc updates]
by Jeff Epler May 21, 2002

May 21, 2002

On Tue, May 21, 2002 at 11:05:55AM -0400, Fred L. Drake wrote: > The development version of the documentation has been updated: > > http://www.python.org/dev/doc/devel/ > > Experimental change: Add some really heavy markup in function signatures > so that when the signature line is wrapped because the browser window is > too narrow, the argument list will wrap to the left parenthesis opening the > argument list. Depending on my browser window's width I get a layout like class addr[, requestHandler[, SimpleXMLRPCServer(logRequests]]) while I would hope for a layout like class SimpleXMLRPCServer(addr[, requestHandler[, logRequests]]) I don't know if it's possible to do this, but it seems that the first line of the parameter list should have the same baseline as the opening paren of the declaration. If this is not possible, then either forcing 'class SimpleXMLRPCServer' to not linebreak, or returning to the old layout class SimpleXMLRPCServer(addr[, requestHandler[, logRequests]]) might be preferable. Jeff PS Please Cc: on replies, not a doc-sig subscriber

2 1

Re: [Python-Dev] [development doc updates]
by David Abrahams May 21, 2002

May 21, 2002

----- Original Message ----- From: "Fred L. Drake" <fdrake(a)acm.org> To: <python-dev(a)python.org>; <doc-sig(a)python.org>; <python-list(a)python.org> Sent: Tuesday, May 21, 2002 11:05 AM Subject: [Python-Dev] [development doc updates] > The development version of the documentation has been updated: > > http://www.python.org/dev/doc/devel/ > > Experimental change: Add some really heavy markup in function signatures > so that when the signature line is wrapped because the browser window is > too narrow, the argument list will wrap to the left parenthesis opening the > argument list. Cool idea! I'm going to have to steal it... after you fix it ;-) On IE6, the doc for excepthook at http://www.python.org/dev/doc/devel/lib/module-sys.html looks like this when wrapped: excepthook type, value, ( traceback) -Dave

1 0

RE: [Doc-SIG] verse construct (was Re: [Docutils-develop] Parsing oddness)
by Moore, Paul May 14, 2002

May 14, 2002

From: David Goodger [mailto:goodger@users.sourceforge.net] > David Goodger wrote: > >> However, a literal block isn't really the ideal way to represent an > >> address block, is it? I've been mulling over an idea for a "verse" > >> directive which seems to apply here. See > >> http://docutils.sf.net/spec/notes.html#body-verse. What do you > >> think? How about that ';;' syntax? > > Tony J Ibbs (Tibs) wrote: > > As you say, the outstanding question is interpretation of > > inline markup within a verse - i.e., in HTML terms, is > > it <pre> or not... > > Literal blocks use <pre> exclusively and treat all whitespace and > line breaks as significant; no inline markup is recognized. > In "verse blocks" (semi-literal blocks; anybody have a better > name?) only line breaks and indentation are treated differently > from a regular paragraph; inline markup like *emphasis* is > recognized normally. Frankly, this seems like overkill to me. I can see what you're getting at - there's a gap in the logical model, between completely literal blocks, and completely interpreted text - but I don't think the gap needs to be filled. How often is this construct likely to be used? In what contexts? (Python docstrings? Wiki pages? I'm not sure what target applications are key for ReST, other than Python docstrings, and doc-sig postings :-) If you really, really, feel the need to put it in, make it a directive. Don't invent new syntax for it. And maybe even just make it a sample directive, not enshrined in the spec, but available as an example of how the directive infrastructure can be extended. This actually raises a question, which may well be covered in the documentation - I haven't read it for a while. How does a document which relies on a particular directive, state that fact? Just by using it? So that if the user doesn't specify the directive (using command line flags to the tools?) he gets a system error/warning, and works out what to do from there? I guess that's OK, actually - we don't want to have to start documents with blurb like:: .. using:: image, quote, my-special-directive That just gets silly... Just my 2p worth. Paul.

5 5

RE: [Doc-SIG] verse construct (was Re: [Docutils-develop] Parsing oddness)
by Moore, Paul May 13, 2002

May 13, 2002

From: David Goodger [mailto:goodger@users.sourceforge.net] > Perhaps you'd feel differently if you needed to use it? Oh, certainly. I wasn't implying otherwise - just noting that we have to take care not to include "the kitchen sink" just because someone wants it. The recent discussion on python-dev was lukewarm, and I got the sense that part of the issue was "why does it need to be so complicated?" > > How often is this construct likely to be used? In what contexts? > > Richard Jones wanted a snailmail address in a document. That's a valid case. Two points - first, with this use case in mind, "verse" is a dreadful name. I can't think of a good one, though. And the second point is why can't this be handled with a literal block? I can't imagine needing markup in an address. Is it just because literal blocks are displayed in a fixed-width font, and so don't "look right"? As I said, I see the value of this, but I think that we need to clarify the aims somewhat. As a related point, I personally would prefer ``*emphasis*`` to be bold, not italic, as this is the usage I see most frequently in E-Mail. However, I accept that reST is addressing logical content, rather than layout, and as such, the way the logical construct is formatted is the role of the backend, not the document source. (This is a *good thing* - the alternative leads to <font> tags...) Given this premiss, I would ask again, what is the *logical* construct involved here? Logically, the gap in functionality is the lack of any way of including markup in a "literal" block. In other words, a linebreak-preserving construct where markup is still respected. This is the construct I fail to see the use for - I wouldn't need markup in a snailmail address, so that use case doesn't mandate this. On the other hand, there is a definite point to the layout issue of wanting a "literal" construct which formats like running text, but with linebreaks preserved. And yes, there is a "logical" value to such a construct - but it's hard to put a name to it, and hence to understand its logical significance (as opposed to its layout significance - "I want a literal block of text here, but it looks funny if I use a real literal block which displays in Courier") > of every time I've had to use a line break in Word, or <br> in HTML, I > believe the construct has merit. Agreed - but Word linebreaks and <br> tags are inherently formatting directives, not structural ones. That's the distinction I'm trying to make. > > If you really, really, feel the need to put it in, make it a > > directive. Don't invent new syntax for it. > > I agree. Syntax can be added later if called for. And at least as importantly, if you use a directive, you're *forced* to think up a decent name for it! Verse doesn't work for 99% of the real life use cases, and its a PR disaster ("look - this thing is clearly a kitchen sink design - who ever needs to quote verse in Python docstrings???") Quote is a little better, but still has unsuitable overtones (in LaTeX, IIRC, the quote environment uses smaller, slanted text, which is a common convention for "real" quotes). > I think that, similarly to modules in Python's library, directives > that are "standard" will be used, but directives that need to be > separately installed won't. I'd like to build a rich variety of > standard directives, and document them all in "reStructuredText > Directives": OK, that fits with the Python library concept. If you make it clear that "library directives" are extensions, not part of "core" reST, then I have no problem with this. It's the bloat question and PR issues again, though. Thanks for listening - as I said, I'm not against the construct per se, but I would like to see a clearer picture of the logic behind it... Paul.

7 8

RE: [Doc-SIG] verse construct (was Re: [Docutils-develop] Parsing oddness)
by Moore, Paul May 11, 2002

May 11, 2002

From: David Goodger [mailto:goodger@users.sourceforge.net] > Paul Moore wrote: > > The recent discussion on python-dev was lukewarm, and I got the > > sense that part of the issue was "why does it need to be so > > complicated?" > > Because too simple is useless. HappyDoc seems like a great tool, but > I don't use it because using StructuredText is like hitting my head > against a brick wall. But it *is* enough for some. "As simple as possible, but no simpler". Exactly. It's the "as possible" bit that is generally the sticking point. What's one person's useless fluff is another's impossible to live without. But the doc-sig is in the unenviable position of having to make priority judgements. Don't forget, we still haven't got a construct to allow words to be set in 24-point blinking script capitals. And please God, don't let us ever get one :-) But I've seen plenty of web sites which provide evidence that *someone* thinks it is appropriate :-( > I've found that many people, programmers especially, take a > condescending attitude toward documentation and related tools, which > results in computers being used as electronic pencils. If we listened > to them, we'd still be using typewriters (nix that: clay tablets!). I > saw it when I was working in Japan with SGML -- well-known > multinational companies (an RDBMS producer, a car manufacturer, and a > telcom giant) treated their documentation as garbage. But I digress. Again, it's a case of being aware of your target application. Not many people quote poetry in technical documentation. But many would want to include an address. On the other hand, the balance could be completely the opposite in E-Mail postings (depending on the mailing list). It's still a case of needing to understand the priorities. > Yes, that's right. Markup may not be needed in address blocks, but it > would be in other applications. The idea originally applied to > quoting verse: poetry, song lyrics, etc. I pointed out to Richard at > the beginning of this thread that it was equally applicable to address > blocks. So address blocks are a secondary use case, not the primary > one. But in terms of probability of being needed, address blocks are more significant (in my personal view of the target application). It's an 80-20 thing. BTW, on the verse issue specifically, I'm convinced (see below), subject to a decent name. The bulk of what I'm now saying is in terms of generalities. I'm really arguing that we have now reached a stage where a more conservative approach is called for. Specifically, no new syntax should be added - directives form our extension mechanism, and we should concentrate on consolidating the core, and if appropriate, building our "standard library". And on *using* these things for real, in visible ways. It's interesting and encouraging to be reminded that the docutils web pages are all generated from reST. More such public examples would be nice - as well as giving a real-life indication of which constructs are important in practice... > I approach it from the opposite side. It's not the lack of markup in > literal blocks, but the lack of linebreak and indentation control in > paragraphs. The "verse" construct permits significant linebreaks and > indentation in otherwise ordinary paragraphs. Literal blocks have the > connotation of program input or output; this construct doesn't. > Literal blocks' use of a monospaced typeface is to emphasize this > connotation. Ah, yes. When you put it like that, I see your point better. BTW, significant indentation? That could be hard - input is monospaced font, but output is proportional, so preserving the *appearance* of an indent won't be that easy. > That gives me an idea for a name for this thing: "literary blocks"... > Probably too clever by far. ;-) Yes. Given that my preferred use case is addresses, I'd argue for "address blocks", and then note in the documentation that these will work for all sorts of other things, like quoting verse... (And I'm not really joking here, either!) > Hmm. I think poets would differ. The way a poem is broken up into > lines (whether there's a rhyming scheme or not) is *very* significant, > and conveys a large part of the poem's structure. Similarly (but in a > much less interesting way) with the pedestrian address block: the line > itself is a unit of structure. OK. This is the point at which you have convinced me. There are significant cases where line breaking denotes structure, but in a sufficiently "unstructured" way (:-)) that the existing constructs such as lists, etc, don't do what you want. Maybe something like "multiline" blocks gives the flavor, without stressing a particular usage...? > I've rearranged the text of the directive definition to reflex this > emphasis: > > http://docutils.sf.net/spec/rst/reStructuredText.html#directives I'd add a bit more. "Directives which have been implemented and registered in the reference reStructuredText parser are described in the reStructuredText Directives document." Add after this "Document authors are entitled to expect that all such standard directives are available. Any other directives should be viewed as domain-specific, and may require special action to make them available when processing the document." Or something like that... Paul.

6 5