Mailman 3 June 2002 - Doc-SIG

Older Python Documentation
by Grant Harris July 9, 2002

July 9, 2002

Hello, I'm working on a web site (http://www.webdocs.org) that hosts the current and older releases of the official Python documentation, along with some other Python-related docs. I currently have Python documentation from as far back as version 1.4 on the site, but nothing older. If possible, I'd like to include as many releases of the Python documentation as I can find (if not all of them). However, I can't seem to find anything prior to Python 1.4. (I did happen to find some tex files for a couple older versions, but no html files.) Also, I'm relatively new to Python (less than a year), so I don't even know which older versions were officially released. For instance, I know that there was a version 1.3 and a 1.2 released, but was there ever a version 1.2.1 or 1.3.1? My guess is that no one today would even care about documentation from that far back. But personally I think it's cool to be able to see how Python has evolved over the years. If anyone knows where I can get documentation for versions of Python older than 1.4, please let me know. Regards, -Grant

3 2

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

References in the same line as the target text
by Simon Budig July 6, 2002

July 6, 2002

Hi everybody. I am currently poking around in the reStructuredText stuff of the docutils. I like it. However, there is one thing that really bugs me a bit. It seems impossible to get a Reference (Link) without having to type the name twice, which is a point where errors occur easily. Also sometimes it is not feasible to have the link targets stand out after a paragraph (where they interrupt the read flow) or at the end of the text (hard to keep in sync in case of changes to the target text). I would like to have some kind of inline link markup. I think a very logical way would be something like the following reference to Python_(http://www.python.org) or this Reference to `The GIMP`_(http://www.gimp.org). IMHO this is a logical and unintrusive extension to the Link Syntax (If a ')' is in the Link itself it should be escaped, but maybe somebody has a better idea for the delimiters). I am currently not sure if it is feasible to have these Links added to the target name list, because this might result in inconsistencies like here_(http://foo.bar) and here_(http://bar.baz). Or leave this problem to the user and allow also anonymous inline links like here__(http://blubb.bla). I think this addition would make it way easier to write structured text with links. But it is perfectly possible that I missed something obvious, since I am pretty new to this field. Please tell me what you think... :-) Bye, Simon -- Simon.Budig(a)unix-ag.org http://www.home.unix-ag.org/simon/

6 24

RE: [Doc-SIG] Simplified table syntax proposals (reStructuredText )
by Moore, Paul June 28, 2002

June 28, 2002

From: David Goodger [mailto:goodger@users.sourceforge.net] > Moore, Paul wrote: > > I find option (3) almost totally unreadable. > > Did you look at this example? It's much clearer: > > http://docutils.sf.net/spec/notes.html#bugs > > The example in the problems.txt file shows all possible > variations in a single small table, so it's bound to be > difficult. Yes, that looks a *lot* better. I think the limitation of not being able to have multi-line cells could be significant, but otherwise it looks reasonable. Depends on what the design constraints are (functionally complete, vs easy to enter, vs easy to read in raw form, ...) I don't have enough use cases to judge on that. I get the impression that functional completeness has been a criterion in previous cases, though. Paul.

1 0

RE: [Doc-SIG] Simplified table syntax proposals (reStructuredText )
by Moore, Paul June 28, 2002

June 28, 2002

From: David Goodger [mailto:goodger@users.sourceforge.net] > I've added some new, simplified but limited, alternative table syntax > proposals (http://docutils.sf.net/spec/rst/problems.html#tables, > alternatives 3, 4, and 5), incorporating an idea from Simon Hefti. > There's a better example of alternative 3 in the notes.txt file > (http://docutils.sf.net/spec/notes.html#bugs). > > Could people please take a look at these alternatives and tell me what > they think? Thank you. [[Disclaimer: I don't use tables much in raw text, so I don't have much of an opinion from a writer's point of view. This is basically a view in the context of being able to read the markup in raw form, which I feel is important...]] I find option (3) almost totally unreadable. Option (5) is OK, but the inability to have blank cells in column 1 makes tables like this:: +-----+-----+ | | A | +-----+-----+ | 1 | A1 | +-----+-----+ unrepresentable. And I suspect that such tables are fairly common (spreadsheet type layouts). Option (4) is the best of the 3, from that point of view. But I don't like the (mis?) use of the bullet list notation. I'd stick with the current approach. It's verbose, but very clear. The need to pad out columns to type the | characters is a (mild) nuisance. But for that, option (2) is fine. I feel that minimalism beyond that point is useless - it hampers readability and expressiveness, for no clear gain in ease of use. [If reST ever grows a way of declaring options for a document, maybe having a "table-format=boxed/minimal" option to choose between table formats (1) and (2) would be worthwhile, but I imagine tghat the price is not worth the gain. No, stick with things as they are.] Paul.

2 1

Docutils updates -- encodings and I/O
by David Goodger June 28, 2002

June 28, 2002

I've just added support for Unicode and file encodings. The new ``docutils.io`` module implements a uniform API for a variety of input & output mechanisms. Please check it out, especially those of you who write in more than plain ASCII. Download the latest snapshot from: http://docutils.sf.net/docutils-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

Simplified table syntax proposals (reStructuredText)
by David Goodger June 27, 2002

June 27, 2002

I've added some new, simplified but limited, alternative table syntax proposals (http://docutils.sf.net/spec/rst/problems.html#tables, alternatives 3, 4, and 5), incorporating an idea from Simon Hefti. There's a better example of alternative 3 in the notes.txt file (http://docutils.sf.net/spec/notes.html#bugs). Could people please take a look at these alternatives and tell me what they think? Thank you. -- 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

Trouble using CVS version
by Dethe Elza June 27, 2002

June 27, 2002

I'm having trouble getting the CVS version of docutils to convert anything to HTML (or even parse a simple reST file). When I run tools/html.py or tools/publish.py on tools/test.txt I get errors for |problematic|, which I expect, and for the figure:: directive, which looks like a bug. When I fix these problems (by removal), I get only an empty document. The only thing which seems to come from the test.txt is the first comment. I've created a dead simple test: When it's nothing but text it works OK, but as soon as I add an underlined section, all the content disappears, including the text. Is this a known problem with the current CVS code? --Dethe

2 8

RE: [Doc-SIG] Non-ASCII Characters in reST (was: [Doc-SIG] docuti ls f eedback )
by Schlaepfer, Ueli (ESEC ZG) June 18, 2002

June 18, 2002

Hi again, > David Goodger wrote: [...] > This is an input encoding issue, the solution to which (you guessed > it!) hasn't been implemented yet. I'm not even sure what the solution > should be. Although I've worked with different "character sets" in > the past (such as Japanese SJIS, and Chinese and Korean encodings), > the encoding was always known beforehand. With Docutils, it won't be. > Anyone with Unicode encoding/decoding experience, I'd appreciate some > advice. Emacs does some guesswork concerning file encoding -- should we have a look at that for a starter? > I've got an "--encoding" option in docutils/frontend.py, but it's > commented out as unimplemented. I've heard that such a command-line > option is a **bad thing**, as are inline magic comments or directives. > There's a comment, "Take default encoding & language from locale?". I > don't know how best to proceed. I'd like to make the *right* decision > here, not just "good enough for now". That's one of the reasons I > haven't implemented the encoding issue yet. I've seen this debated, > on Python-Dev and elsewhere, but I have yet to be shown "the one true > way" or convinced that it *is* the right way. I'm way off base here, but as I mentioned -- one condition is that the result is not "anything-centric", but defaults to a reasonable value. If the locale is wrong -- well, blame the site administrator... The language is much less of an issue, I think. Stating it in the document if it's not what the default would be is easy enough to understand, and such a statement won't turn into a lie as easily as the encoding. A command-line option is a must, though; I don't expect an American to state that his documents are in English, but I won't state it if mine are in German either. So I need a way to tell the frontend what language it should use. > Another reason is because there are really two encodings at play here: > the input encoding and the output encoding. Is it reasonable to > require that both be specified (with UTF-8 as defaults)? Western > Europeans will want to use Latin-1 as the default, but that's not > friendly to the rest of the world. Is locale the answer? Or are > explicit command-line options the best way? A combination? A sensible default is definitely required. Explicit command or another mechanism should be there, too, but as a last resort only and for people who (unlike me ;-) know what they're doing. > My brain hurts. > > > I ran into this bug before (I happen to have an 'ä' in my last name, > > so it occured at least once per document) and tracked it to line 98 > > in docutils/writers/__init__.py, which reads (note the > > ``temporary``!):: > > > > output = output.encode('utf-8') # @@@ temporary; must not hard-code > > > > Apparently, ``'something'.encode()`` expects ``'something'`` to > > contain clean 7-bit ASCII text. > > My understanding is as follows (please correct me if I'm wrong). > ``output.encode('utf-8')`` actually expects ``output`` to be a Unicode > string, *not* 7-bit ASCII. If it's a regular (8-bit, non-Unicode) > string, the operation will try to coerce it (decode it using the > default encoding) into a Unicode string, then encode that into a > UTF-8-encoded 8-bit string. It's the *decoding* stage that's raising > the exception, because the default encoding is 7-bit "ascii", and > ``output`` is a regular string containing non-ASCII (the a+umlaut). > As an experiment, could you try editing your site.py file? Try > enabling the locale-detecting mechanism (search for "locale"), and/or > the explicit default encoding above it. What happens then? Thanks for the clarification! The experiment you suggested suggests that you're correct. I just tried enabling locale detection, and the error went away... My fix is a lot less dirty now :-) > As I said, the problem isn't encoding the output, it's decoding the > input. Since the HTML being produced says it's using UTF-8, if there > are non-ASCII charactes in your output they may be misinterpreted by > your browser. I'm aware of that. But since it's running in the same environment, chances are that it'll work out all right anyway, and so far it did. > > Fixing this kind of things can be nasty, I think -- for a simple > > text file, there's (AFAIK) no way to know the encoding but guessing. > > Yes. The question is, how best to guess? And how best to override > the guesswork? > > > One way to handle it would probably be to have such an educated > > guess based on the system docutils is running on (assuming the file > > was typed in a dumb editor on the same machine), and to allow the > > encoding to be stated explicitly with a directive along the lines:: > > > > .. encoding: cp1250 > > That's an alternative (already in the "To Do" list). It's not my > favorite, since it's ugly and can lie. When saving from a text editor > a file could be re-encoded without the author noticing, and the > "encoding" directive would become wrong. Good point! ...and what do you get if you save from a browser window (say, webmail written in reST) ? After the above experiment, I think (but I'm definitely no authority here!!) that using the locale should be the default way to go. -- Ueli

2 1

Non-ASCII Characters in reST (was: [Doc-SIG] docutils f eedback )
by Schlaepfer, Ueli (ESEC ZG) June 18, 2002

June 18, 2002

Hi all, In a recent thread, Simon posted the following traceback:: Traceback (most recent call last): File "/home/hefti/local_in_archive/src/docutils-0.1/tools/html.py", line 26, in ? reporter=reporter) File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/core.py", line 85, in publish pub.publish(source, destination) File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/core.py", line 67, in publish self.writer.write(document, destination) File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/writers/__init __.py", line 56, in write self.record() File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/writers/html4c ss1.py", line 36, in record self.recordfile(self.output, self.destination) File "/usr/local/Python-2.2b1/lib/python2.2/site-packages/docutils/writers/__init __.py", line 86, in recordfile output = output.encode('raw-unicode-escape') # @@@ temporary UnicodeError: ASCII decoding error: ordinal not in range(128) To which David replied: >> This is a bug in the Docutils code, not a problem with the data, so >> it's appropriate to see a Python traceback. The code crashed! >> >> However, I believe the problem is solved in current CVS. Try >> installing from the CVS snapshot: >> http://docutils.sf.net/docutils-snapshot.tgz I ran into this bug before (I happen to have an 'ä' in my last name, so it occured at least once per document) and tracked it to line 98 in docutils/writers/__init__.py, which reads (note the ``temporary``!):: output = output.encode('utf-8') # @@@ temporary; must not hard-code Apparently, ``'something'.encode()`` expects ``'something'`` to contain clean 7-bit ASCII text. My quick-and-dirty fix to the problem was to comment out this line. The offending chjaracters make it through to the HTML, but as my documents are for internal use only, this doesn't matter so far. Now I just checked with yesterdays (june 16) CVS. The `minimal document`_ below still triggers the bug, contrary to David's statement. .. _`minimal document`: === 8< ========================================== ä === 8< ========================================== ;-) Fixing this kind of things can be nasty, I think -- for a simple text file, there's (AFAIK) no way to know the encoding but guessing. It's the raison d'être for TeX's "inputenc" package (and for a few more, I think). This package provides a way to state the encoding in the source file. One way to handle it would probably be to have such an educated guess based on the system docutils is running on (assuming the file was typed in a dumb editor on the same machine), and to allow the encoding to be stated explicitly with a directive along the lines:: .. encoding: cp1250 That's it for now... (I was hoping to provide a fix, but my current work situation doesn't allow for substantial contributions :-( ) -- Ueli

3 3